Коммуникационный API
- Denis Kiselev
API канал служит для подключения произвольных сервисов к AutoFAQ, к примеру:
корпоративные мессенджеры - для переписки пользователей в мессенджере с ботом и операторами
форма обратной связи - для заведения заявок с сайтов и отправки ответов пользователю на электронную почту
Service Desk - для классификации поступающих заявок и получения ответов на запросы
собственный чат на сайте или в личном кабинете - для переписки пользователей с ботом и операторами
Детали работы через API канал
Переписка через API канал ведется только в асинхронном режиме. Полное описание методов API доступно по ссылке в swagger.
Авторизация при отправке запросов ведется через отправку токена в заголовке запроса. Для получения токена авторизации необходима учетная запись пользователя в сервисе AutoFAQ, можно воспользоваться существующей учетной записью или создать новую, набор ролей для новой учетной записи значения не имеет. Получить токен можно отдельным запросом https://app.swaggerhub.com/apis-docs/AutoFAQ.ai/external-api/2.1.4#/Authentication/Authenticate. Время жизни токена 42 года.
Перед началом работы клиентский сервис должен указать адрес для получения ответов от AutoFAQ в настройках канала или отдельным запросом https://app.swaggerhub.com/apis-docs/AutoFAQ.ai/external-api/2.1.4#/Chat/set_webhook.
Отправка сообщений пользователя ведется в теле запроса https://app.swaggerhub.com/apis-docs/AutoFAQ.ai/external-api/2.1.4#/Chat/SendQuestionAsync. Ответные сообщения бота или оператора AutoFAQ придут в виде POST запроса на указанный ранее адрес WebHook. Формат ответного сообщения указан в описании запроса в разделе CallBacks.
Переписка через API канал поддерживает двухсторонюю передачу файлов. Для передачи файлов в сервис AutoFAQ следует сперва передать нужные файлы запросом https://app.swaggerhub.com/apis-docs/AutoFAQ.ai/external-api/2.1.4#/Chat/post_api_ext_v2_services__serviceId__channels__channelId__files, а потом указать полученные идентификаторы в теле запроса с сообщением пользователя. При получении в ответном сообщении от AutoFAQ идентификаторов файлов их можно получить запросом https://app.swaggerhub.com/apis-docs/AutoFAQ.ai/external-api/2.1.4#/Chat/get_api_ext_v2_services__serviceId__channels__channelId__files__fileId_.
Переписка через API канал поддерживает использование кнопок. Список кнопки передаются отдельным списком для каждой реплики AutoFAQ. Нажатия пользователей на кнопки можно возвращать как в виде текстового сообщения, так и в виде события нажатия на кнопку.
В одном сервисе AutoFAQ может быть подключено API каналов. Ограничения по числу каналов нет.
Подключение к API каналу
Cоздать API канал в разделе Каналы настроек сервиса AutoFAQ. При создании необходимо сразу указать название канала, которое будет отображаться в истории диалогов.
2. После нажатия Продолжить откроются настройки канала
В настройке Канал подключен к группам указать принадлежность канала к группам сервиса AutoFAQ. Подробнее о граппах в сервисе можно прочитать в разделе Группы. Если группы в вашем сервисе не настроены, то этот и следующий пункт настроек будет отсутствовать.
В настройке Выбор группы можно указать способ выбора группы в том случае если канал подключен сразу в несколько групп. На данный момент доступен только один способ выбора - через прямой запрос у пользователя.
В настройке URL внешнего webhook можно указать адрес для отправки ответных сообщений от сервиса AutoFAQ. Этот адрес так же можно указать запросом https://app.swaggerhub.com/apis-docs/AutoFAQ.ai/external-api/2.1.4#/Chat/set_webhook
Настройкой Включить удаление HTML из ответов можно убрать все HTML теги из реплик AutoFAQ в том случае если получатель сообщений не поддерживает их использование.
Настройка Генерация ID сессии для исходящих диалогов отвечает за формат поля sessionId в исходящих репликах от сервиса AutoFAQ. Поле sessionId можно использовать в дополнение к идентификатору пользователя в случаях когда один и тот же клиентский сервис может вести сразу несколько переписок в разными сервисами AutoFAQ одновременно или с разными API каналами в одном сервисе. В этом случае поле sessionId позволит определить из какого именно сервиса AutoFAQ пришло исходящее сообщение. Для этого необходимо указать требуемый шаблон в поле Шаблон генерации ID сессии.
Если клиентский сервис ведет переписку только с 1 сервисом AutoFAQ то настройку Генерация ID сессии для исходящих диалогов можно оставить как Случайный.
Настройка Лимит на размер загружаемых файлов отвечает за ограничение размера загружаемых в сервиса AutoFAQ файлов. При превышении указанного размера запрос https://app.swaggerhub.com/apis-docs/AutoFAQ.ai/external-api/2.1.4#/Chat/post_api_ext_v2_services__serviceId__channels__channelId__files вернет ошибку.