Запросы, статусы и диалоги

Для коротких операций можно получать ответ в одном запросе. Если обработка занимает время, отправьте сообщение в очередь и проверяйте результат по идентификатору.

Режимы ответа

Значение mode	Назначение
SUPPORT	Ответ клиенту с учётом базы знаний и настроек поведения
PROMPTER	Подготовка ответа сотруднику; применяется по умолчанию
DIRECT	Прямой запрос языковой модели

1. Отправить сообщение в очередь

POST /api/v1/bots/{uniqueId}/completion

URL

https://app.helpfy.ai/api/v1/bots/{uniqueId}/completion

Заголовки

Заголовок	Значение
Authorization	Basic <base64(email:api_key)>
Accept	application/json
Content-Type	application/json

Параметры запроса

Параметр	Тип	Обязательный	Описание
uniqueId	строка	Да	Идентификатор бота в адресе запроса.
prompt	строка	Да	Сообщение пользователя.
mode	строка	Нет	Режим ответа: SUPPORT, PROMPTER или DIRECT. По умолчанию PROMPTER.
meta	объект	Нет	Ваши дополнительные данные для связи запроса с обращением клиента. До 5 КБ.

Пример запроса

curl --request POST "https://app.helpfy.ai/api/v1/bots/11111111-1111-4111-8111-111111111111/completion" \
  --user "user@example.com:api_key" \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data-binary @- <<'JSON'
{
  "prompt": "Как изменить адрес доставки?",
  "mode": "SUPPORT",
  "meta": {
    "source": "shop-support",
    "traceId": "ticket-123"
  }
}
JSON

Ответы

Успешный запрос: HTTP 201.

Пример ответа — HTTP 201

Сокращённый пример; значения условные.

{
  "message": "The prompt has been successfully sent to the queue",
  "unique_id": "e07ab05f-f97d-44f4-b668-2339d642e373"
}

Сохраните unique_id и подставьте его в адрес запроса состояния. Ответ 201 означает постановку в очередь, а не завершение обработки. Технический текст поля message может быть на английском — ориентируйтесь на статус и идентификатор.

2. Получить состояние запроса

GET /api/v1/bots/{uniqueId}/completion/{completionUniqueId}

URL

https://app.helpfy.ai/api/v1/bots/{uniqueId}/completion/{completionUniqueId}

Заголовки

Заголовок	Значение
Authorization	Basic <base64(email:api_key)>
Accept	application/json

Параметры запроса

Параметр	Тип	Обязательный	Описание
uniqueId	строка	Да	Идентификатор бота в адресе запроса.
completionUniqueId	строка	Да	Идентификатор запроса из ответа предыдущего шага.

Пример запроса

curl --request GET "https://app.helpfy.ai/api/v1/bots/11111111-1111-4111-8111-111111111111/completion/e07ab05f-f97d-44f4-b668-2339d642e373" \
  --user "user@example.com:api_key" \
  --header 'Accept: application/json'

Ответы

Успешный запрос: HTTP 200.

Пример ответа — HTTP 200

Сокращённый пример; значения условные.

{
  "status": "SUCCESS",
  "response": "Адрес можно изменить до передачи заказа в доставку.",
  "unique_id": "e07ab05f-f97d-44f4-b668-2339d642e373",
  "webhook_status": 200,
  "webhook_error": null
}

Поля response, webhook_status, webhook_error и другие дополнительные сведения могут отсутствовать, пока соответствующих данных нет.

Не проверяйте состояние непрерывным циклом. Делайте паузу, постепенно увеличивайте её и ограничьте общее время ожидания. Альтернатива — доставка результата на ваш сервер.

Значения статуса

Статус	Значение
PENDING	Запрос ожидает обработки.
IN_PROGRESS_REQUEST	Сообщение обрабатывается.
RESPONSE_IN_PROCESSING	Ответ подготавливается.
IN_PROGRESS_RESPONSE	Результат передаётся получателю.
SUCCESS	Ответ подготовлен.
GREETING	Распознано приветствие.
CLOSING	Распознано завершение диалога.
OPERATOR	Нужна передача оператору.
SPAM	Сообщение признано спамом.
NO_ANSWER	Бот не смог подготовить ответ.
EMPTY_CONTEXT	Недостаточно материалов для ответа.
ERROR	Ошибка обработки.
HTTP_ERROR	Ошибка HTTP-запроса к внешнему сервису.
LIMIT_EXCEEDED	Достигнут лимит.

3. Создать диалог

POST /api/v1/bots/{uniqueId}/dialogues

URL

https://app.helpfy.ai/api/v1/bots/{uniqueId}/dialogues

Заголовки

Заголовок	Значение
Authorization	Basic <base64(email:api_key)>
Accept	application/json
Content-Type	application/json

Параметры запроса

Параметр	Тип	Обязательный	Описание
uniqueId	строка	Да	Идентификатор бота в адресе запроса.
name	строка	Да	Название переписки.
message_limit	число	Да	Сколько предыдущих сообщений учитывать. 0 — без контекста.
operator_limit	число	Нет	Количество сообщений клиента до перевода на оператора.

Пример запроса

curl --request POST "https://app.helpfy.ai/api/v1/bots/11111111-1111-4111-8111-111111111111/dialogues" \
  --user "user@example.com:api_key" \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data-binary @- <<'JSON'
{
  "name": "Обращение по заказу 123",
  "message_limit": 10,
  "operator_limit": 25
}
JSON

Ответы

Успешный запрос: HTTP 201.

Пример ответа — HTTP 201

Сокращённый пример; значения условные.

{
  "unique_id": "11111111-1111-4111-8111-111111111111",
  "dialogue_id": "11111111-1111-4111-8111-111111111111",
  "name": "Обращение по заказу 123",
  "message_limit": 10,
  "operator_limit": 25
}

Сохраните dialogue_id. У каждого обращения должен быть свой диалог, чтобы переписки клиентов не смешивались.

4. Продолжить диалог

POST /api/v1/bots/{uniqueId}/completion/sync

URL

https://app.helpfy.ai/api/v1/bots/{uniqueId}/completion/sync

Заголовки

Заголовок	Значение
Authorization	Basic <base64(email:api_key)>
Accept	application/json
Content-Type	application/json

Параметры запроса

Параметр	Тип	Обязательный	Описание
uniqueId	строка	Да	Идентификатор бота в адресе запроса.
prompt	строка	Да	Сообщение пользователя.
mode	строка	Нет	Режим ответа: SUPPORT, PROMPTER или DIRECT. По умолчанию PROMPTER.
dialogue_id	строка	Да, в этом примере	Идентификатор созданного диалога.

Пример запроса

curl --request POST "https://app.helpfy.ai/api/v1/bots/11111111-1111-4111-8111-111111111111/completion/sync" \
  --user "user@example.com:api_key" \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data-binary @- <<'JSON'
{
  "prompt": "А можно изменить адрес?",
  "mode": "SUPPORT",
  "dialogue_id": "11111111-1111-4111-8111-111111111111"
}
JSON

Ответы

Успешный запрос: HTTP 200.

Пример ответа — HTTP 200

Сокращённый пример; значения условные.

{
  "response": {
    "message": "Да, если заказ ещё не передан в доставку."
  },
  "error": false,
  "type": "SUCCESS"
}

Полные параметры приведены в методе отправки сообщения.