Если у нас нет готовой функциональности для миграции с сервиса, от которого вы хотите отказаться, данные можно перенести с помощью API. Для решения этой задачи вам потребуется подключить разработчиков, но мы написали подробную инструкцию, чтобы облегчить им задачу :)
Перед написанием скрипта для переноса данных
1. Ознакомьтесь с лимитами API, чтобы скрипт переноса данных не отправлял запросы слишком часто, и вы не получили ответы с ошибками. Ограничение на количество запросов зависит от вашего текущего тарифа. При превышении лимита выдаётся сообщение с ошибкой «429 Too Many Requests».
Для клиентов, чьи аккаунты созданы до 5 марта 2024 года, действуют старые лимиты: 500 запросов в час на активного сотрудника (за исключением лёгких — с доступом «только просмотр»), но не менее 1000 запросов в час. К примеру, если у вас 15 активных сотрудников, лимит вашего аккаунта — 7500 запросов в час.
Окончательный переход на новую схему расчета лимитов произойдет 12 июня 2024 года. Поставьте задачу вашим разработчикам, чтобы они учли изменения логики в скриптах, которые выполняют запросы в адрес API Омнидеска.
Чтобы не превышать лимит на количество запросов, ваш скрипт должен проверять заголовки в ответе:
rate_limit_per_minute — максимальное количество запросов в минуту;
api_calls_left — количество запросов, оставшихся в текущем интервале лимита;
retry_after — количество секунд, после которых лимит сбросится.
Запросы на запись (методы POST, PUT, DELETE) засчитываются как два запроса в рамках лимита.
2. Создавать сначала пользователей, а потом их обращения, нет смысла, потому что при создании обращения мы автоматически создаём пользователя, если его нет в базе данных. Так вы сможете перенести больше данных, не превышая лимиты API.
3. Создавать обращения (и пользователей) можно только по каналам: Email, «Звонки» и кастомным. Если при использовании сервиса, с которого переходите на Омнидеск, вы обрабатывали обращения и других каналов (соцсети, мессенджеры), перенести их не получится.
API-методы для переноса данных
1.1 Создание обращения канала «Email»
Для создания обращения нужно использовать соответствующий API-метод (или похожий, если к сообщению, с которого начинается переписка, нужно прикрепить файлы). Однако в зависимости от того, кто инициировал обращение, передаваемые параметры должны отличаться.
а. Пользователь (ваш клиент) инициировал переписку:
обязательно — user_email, subject, content_html, created_at
опционально — user_full_name, staff_id, group_id, status, priority, custom_fields, labels
б. Сотрудник инициировал переписку:
обязательно — user_email, initiator_id, subject, content_html, created_at, case_email_id=-1
опционально — user_full_name, staff_id, group_id, status, priority, custom_fields, labels
После отправки корректного запроса на создание обращения вы должны получить ответ 200. В нём будут все данные обращения, включая: case_id, case_number и user_id. Эти данные нужно сохранить, чтобы после вы могли просматривать/редактировать данные обращения и добавлять ответы от пользователя.
1.2 Добавление сообщения в обращение канала «Email»
При создании обращения в нём есть лишь сообщение, с которого началась переписка с пользователем. Остальные сообщения нужно добавлять через отдельный API-метод. В этом случае также нужно передавать разные параметры в зависимости от того, чьё сообщение добавляется.
а. Сообщение пользователя (клиента):
обязательно — content_html, created_at, user_id
опционально — нет опциональных параметров
б. Сообщение сотрудника:
обязательно — content_html, created_at, staff_id, do_not_send_email=true
опционально — нет опциональных параметров
Если по ходу переписки у вас есть и заметки (внутренние комментарии), их можно добавить через специальный API-метод.
1.3 Проверка параметров обращения канала «Email»
Если при создании обращения вы передавали лишь обязательные параметры, то после добавления всех сообщений может потребоваться сверка параметров через метод просмотра обращения. При необходимости изменить какие-то параметры (выставить статус, добавить метку, назначить ответственного и т.д.) используйте метод редактирования.
2.1 Создание обращения канала «Звонки»
Для создания обращения нужно использовать соответствующий API-метод (или похожий, если к сообщению, с которого начинается переписка, нужно прикрепить файлы; к примеру, запись разговора). Однако в зависимости от того, кто инициировал общение, передаваемые параметры должны отличаться.
а. Пользователь (ваш клиент) инициировал общение:
обязательно — user_phone, subject, content, created_at
опционально — user_full_name, staff_id, group_id, status, priority, custom_fields, labels
б. Сотрудник инициировал общение:
обязательно — user_phone, initiator_id, subject, content, created_at
опционально — user_full_name, staff_id, group_id, status, priority, custom_fields, labels
После отправки корректного запроса на создание обращения вы должны получить ответ 200. В нём будут все данные обращения, включая: case_id, case_number и user_id. Эти данные нужно сохранить, чтобы после вы могли просматривать/редактировать данные обращения и добавлять ответы от пользователя.
2.2 Добавление сообщения в обращение канала «Звонки»
Обычно в обращениях канала «Звонки» мало сообщений, так как каждое из них создаётся при созвоне с клиентом, но много заметок (внутренних комментариев), в которых фиксируются важные моменты и ведётся обсуждение с коллегами. Поэтому для всего, что не должен видеть клиент, нужно использовать API-метод добавления заметок. Если же нужно создавать именно сообщения по входящим и исходящим звонкам в рамках одного обращения, используйте API-метод добавления ответа.
а. Пользователь позвонил:
обязательно — content, created_at, user_id
опционально — нет опциональных параметров
б. Сотрудник позвонил:
обязательно — content, created_at, staff_id
опционально — нет опциональных параметров
2.3 Проверка параметров обращения канала «Звонки»
Если при создании обращения вы передавали лишь обязательные параметры, то после добавления всех сообщений может потребоваться сверка параметров через метод просмотра обращения. При необходимости изменить какие-то параметры (выставить статус, добавить метку, назначить ответственного и т. д.) используйте метод редактирования.
3.1 Создание обращения кастомного канала
Подробнее о кастомных каналах можно прочитать тут.
Для создания обращения нужно использовать соответствующий API-метод (или похожий, если к сообщению, с которого начинается переписка, нужно прикрепить файлы). Однако в зависимости от того, кто инициировал обращение, передаваемые параметры должны отличаться.
а. Пользователь (ваш клиент) инициировал переписку:
обязательно — user_custom_id, subject, content_html (или content для кастомного канала синхронного типа), created_at
опционально — user_full_name, staff_id, group_id, status, priority, custom_fields, labels
б. Сотрудник инициировал переписку:
обязательно — user_custom_id, initiator_id, subject, content_html (или content для кастомного канала синхронного типа), created_at
опционально — user_full_name, staff_id, group_id, status, priority, custom_fields, labels
После отправки корректного запроса на создание обращения вы должны получить ответ 200. В нём будут все данные обращения, включая: case_id, case_number и user_id. Эти данные нужно сохранить, чтобы после вы могли просматривать/редактировать данные обращения и добавлять ответы от пользователя.
3.2 Добавление сообщения в обращение кастомного канала
При создании обращения в нём есть лишь сообщение, с которого началась переписка с пользователем. Остальные сообщения нужно добавлять через отдельный API-метод. В этом случае также нужно передавать разные параметры в зависимости от того, чьё сообщение добавляется.
а. Сообщение пользователя (клиента):
обязательно — content_html (или content для кастомного канала синхронного типа), created_at, user_id
опционально — нет опциональных параметров
б. Сообщение сотрудника:
обязательно — content_html (или content для кастомного канала синхронного типа), created_at, staff_id
опционально — нет опциональных параметров
Если по ходу переписки у вас есть и заметки (внутренние комментарии), их можно добавить через специальный API-метод.
3.3 Проверка параметров обращения кастомного канала
Если при создании обращения вы передавали лишь обязательные параметры, то после добавления всех сообщений может потребоваться сверка параметров через метод просмотра обращения. При необходимости изменить какие-то параметры (выставить статус, добавить метку, назначить ответственного и т. д.) используйте метод редактирования.