Протокол работы Chatme.ai Public API 1.0

Описание

Chatme.ai Public API 1.0 интегрируется по протоколу HTTPS через webhook. Формат взаимодействия включает в себя форматы запросов и ответов, которыми платформа обменивается со сценариями чат-ботов.

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

Формат запроса

Платформа chatme.ai принимает POST-запрос в формате JSON на webhook URL https://admin.chatme.ai/connector/webim/webim_message/{channel_token}/bot_api_webhook, где channel_token — токен чат-бота, сгенерированного на платформе.

Событие new_chat:

{
    "event": "new_chat",
    "chat": {
            "id": (string)
        },
    "messages": [{
          "kind": "visitor",
          "text": (string),
          "response":{
                     "button": (button)
                }
        }] 
}

Название параметра	Тип	Описание
event	String	Событие new_chat срабатывает в момент назначения нового чата на бота.
chat.id	String	Уникальный идентификатор чата
messages	Array	Массив из сообщений Собеседника, которые были отправлены в чат до появления Собеседника в чате
messages.kind	String	visitor или keyboard_response
messages.text	String	Текст сообщения Собеседника. Присутствует, если kind == visitor.
message.response	Object	Описывает ответ Собеседника на keyboard сообщение. Присутствует, если kind == keyboard_response.
message.response.button	Button	Описывает нажатую кнопку. Ниже будет приведен пример элемента типа Button.

Событие new_message:

{
    "event": "new_message",
    "chat": {
            "id": (string)
    },
    "kind": (string),
    "text": (string),
    "response":{
            "button": (button)
    }
}

Название параметра	Тип	Описание
event	String	Событие new_message инициируется в момент прихода нового сообщения от Собеседника в чат (после нажатия Собеседником кнопки), назначенный на бота.
chat.id	String	Уникальный идентификатор чата
kind	String	visitor или keyboard_response
text	String	Текст сообщения Собеседника. Присутствует, если kind == visitor.
response	Object	Описывает ответ Собеседника на keyboard сообщение. Присутствует, если kind == keyboard_response.
response.button	Button	Описывает нажатую кнопку. Ниже будет приведен пример элемента типа Button.

Формат ответа

Успех: статус 200

Запрос с событием new_chat допускает пустое тело ответа, если в теле запроса нет поля messages. В случае когда поле messages включено в запрос, ответ будет таким же, как и ответ на запрос с событием new_messages.

Ответ на запрос с событием new_message имеет вид:

{
    "has_answer": (boolean)
    "messages": [{
        "kind": (string),
        "text": (string),
        "buttons": [(button), ...]
    },]
}

Название параметра	Тип	Описание
has_answer	Boolean	true — у чат-бота есть ответ на сообщение; false — чат-бот не может ответить на сообщение (подразумевается переход на оператора).
messages	Array	Массив из сообщений. Присутствует, если has_answer == true.

Параметры поля message:

Название параметра	Тип	Описание
kind	String	operator или keyboard. Поле обязательно.
text	String	Сообщение от бота. Поле присутствует в элементе массива message, если kind == operator.
buttons	Array of Buttons	Массив массивов кнопок вида [[b1], [b2], ...]. Поле присутствует, если kind == keyboard.

Элемент типа Button

{
    "id": (string),
    "text": (string)
}

Название параметра	Тип	Описание
id	String	Уникальный идентификатор кнопки
text	String	Текст кнопки

Пример ответа

{
    "has_answer": true,
    "messages": [
        {
            "kind": "operator",
            "text": "Мы работаем над вашей проблемой"
        },
        {
            "kind": "keyboard",
            "buttons": [
                [
                    {
                        "id": "call_agents",
                        "text": "Обратиться к операторам"
                    }
                ],
                [
                    {
                        "id": "call_agent",
                        "text": "Обратиться к оператору"
                    }
                ]
            ]
        }
    ]
}

Неудача: статус 400

Возможен ответ, уведомляющий о том, что запрос был не выполнен и произошла непредвиденная ошибка. Такие ответы выглядят следующим образом:

Пример 1:

{
    "error": "client_error",
    "details": "Channel not found."
}

Пример 2 :

{
    "error": "not_found"
}

Пример 3:

405: Method Not Allowed

Если в ответ на ваш запрос пришел такой ответ, то настоятельно рекомендуем проверить на опечатки Webhook URL и метод, с помощью которого был отправлен данный запрос.