Создание обращений через API

Самый частый сценарий интеграции: ваша система создаёт обращение, а поддержка отвечает из привычного интерфейса.

Что нужно

Ключ с правом на запись обращений. Рабочая область определяется по ключу — её в запросе указывать не нужно.

Что передавать

Минимум: кто обратился и что случилось. То есть контактные данные человека, тема и текст.

Дополнительно можно сразу проставить категорию и приоритет — если ваша система знает их лучше, чем угадает ассистент.

Точные названия полей и формат — в технической документации API.

Что происходит дальше

Обращение появляется в общем списке, как если бы пришло письмо: со своим номером, статусом и правилами назначения. Дальше работают автоназначение, классификация и уведомления.

Контакт заводится или находится по переданным данным — как и в остальных каналах.

Как отвечать клиенту

Ответ оператора уходит по каналу обращения. У обращения, созданного через API, своего канала доставки нет — значит, ответ никуда не уйдёт, пока у контакта не появится почта и подключённый почтовый канал.

Учтите это заранее: передавайте адрес почты, если хотите, чтобы поддержка могла ответить.

Второй вариант — забирать ответы через API и показывать их в своём интерфейсе.

Дубли

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

Ограничения по частоте

Запись ограничена по числу запросов в минуту. Если планируете разовую массовую загрузку, разбейте её на порции и делайте паузы.

Проверка

Создайте тестовое обращение и убедитесь, что оно появилось в списке, поля заполнены и назначение отработало. Тестовое потом удалите — оно попадёт в аналитику.

Что дальше

Создание и хранение API-ключа. Вебхуки: получаем события у себя — чтобы узнавать об ответах.