Вебхуки результатов

Вебхук — HTTP-запрос, который Helpfy AI отправляет на ваш сервер с готовым результатом. Его адрес задаётся в настройках бота. Это позволяет получать ответы без повторных запросов состояния.

1. Указать адрес получателя

PATCH /api/v1/bots/{uniqueId}

URL

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

Заголовки

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

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

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

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

curl --request PATCH "https://app.helpfy.ai/api/v1/bots/11111111-1111-4111-8111-111111111111" \
  --user "user@example.com:api_key" \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data-binary @- <<'JSON'
{
  "webhook_url": "https://your-service.example/helpfy/results"
}
JSON

Ответы

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

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

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

{
  "unique_id": "11111111-1111-4111-8111-111111111111",
  "webhook_url": "https://your-service.example/helpfy/results"
}

После сохранения отправьте асинхронный запрос. Поле meta можно использовать для связи результата с обращением в вашей системе.

2. Принять результат на своём сервере

POST /helpfy/results

URL

https://your-service.example/helpfy/results

Это пример адреса вашего обработчика, а не метод сервера Helpfy AI.

Заголовки

Заголовок	Значение
Content-Type	application/json
Accept	application/json

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

Параметр	Тип	Обязательный	Описание
response.message	строка	Может отсутствовать при ошибке	Текст ответа бота.
meta.unique_id	строка	Да	Идентификатор исходного запроса.
meta.bot_unique_id	строка	Да	Идентификатор бота.
meta.meta	объект	Нет	Ваши данные из поля meta исходного запроса.
type	строка	Да	Результат обработки: SUCCESS, OPERATOR или другой статус.
error	логическое значение	Да	true — результат содержит ошибку.

Пример входящего запроса

Пример POST с результатом

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

{
  "response": {
    "message": "Адрес можно изменить до передачи заказа в доставку."
  },
  "meta": {
    "unique_id": "e07ab05f-f97d-44f4-b668-2339d642e373",
    "bot_unique_id": "11111111-1111-4111-8111-111111111111",
    "meta": {
      "source": "shop-support",
      "traceId": "ticket-123"
    }
  },
  "type": "SUCCESS",
  "error": false
}

Ответы вашего сервера

Верните успешный HTTP-статус после того, как результат надёжно принят. Повторный результат с тем же идентификатором не должен создавать второй ответ клиенту. Храните факт обработки по meta.unique_id.

Сетевые сбои, HTTP 408, 429 и ответы 5xx могут вызвать повторную доставку. Проверяйте webhook_status и webhook_error в состоянии запроса: ошибка доставки не обязательно означает, что модель не подготовила ответ.