Как перенести данные в Омнидеск с помощью API?

Последние изменения: 19.01.2021

Если у нас нет готовой функциональности для миграции с сервиса, от которого вы хотите отказаться, данные можно перенести с помощью API. Для решения этой задачи вам потребуется подключить разработчиков, но мы написали подробную инструкцию, чтобы облегчить им задачу :)

Перед написанием скрипта для переноса данных

1) Ознакомьтесь с лимитами API, чтобы скрипт переноса данных не отправлял запросы слишком часто, и вы не получили ответы с ошибками.

Ограничение на количество запросов — 500 запросов в час на активного сотрудника (за исключением лёгких — доступ «только просмотр»), но не менее 1000 запросов в час. К примеру, если у вас 15 активных сотрудников, лимит вашего аккаунта — 7500 запросов в час. При превышении лимита выдаётся сообщение с ошибкой.

Количество оставшихся API-запросов при любом запросе можно отследить в заголовках ответа через параметр: api_calls_left

Если скрипт написан так, что все запросы часового лимита выполняются за 5 минут, то для успешного выполнения следующего запроса придётся ждать 55 минут. Поэтому запросы нужно выполнять равномерно в течение часа.

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 Проверка параметров обращения канала «Email»

Если при создании обращения вы передавали лишь обязательные параметры, то после добавления всех сообщений может потребоваться сверка параметров через метод просмотра обращения. При необходимости изменить какие-то параметры (выставить статус, добавить метку, назначить ответственного и т.д.) используйте метод редактирования.

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 Проверка параметров обращения кастомного канала

Если при создании обращения вы передавали лишь обязательные параметры, то после добавления всех сообщений может потребоваться сверка параметров через метод просмотра обращения. При необходимости изменить какие-то параметры (выставить статус, добавить метку, назначить ответственного и т.д.) используйте метод редактирования.

Помогла ли вам статья?