Сообщения

Список сообщений

Возвращает сообщения диалога в хронологическом порядке (сначала старые). Внутренние заметки операторов никогда не включаются.

{
  "results": [
    {
      "id": "a1000000-0000-4000-8000-000000000001",
      "conversation_id": "3f2b1c9a-7d4e-4b21-9c33-0a1b2c3d4e5f",
      "thread_id": null,
      "sender_type": "CLIENT",
      "content": "Where is my order?",
      "is_internal_note": false,
      "reply_to_id": null,
      "created_at": "2026-07-01T10:30:00+00:00",
      "attachments": []
    },
    {
      "id": "b2d7e410-3c88-4a15-9f60-7d8e9a0b1c2d",
      "conversation_id": "3f2b1c9a-7d4e-4b21-9c33-0a1b2c3d4e5f",
      "thread_id": null,
      "sender_type": "OPERATOR",
      "content": "It shipped this morning \u2014 tracking below.",
      "is_internal_note": false,
      "reply_to_id": null,
      "created_at": "2026-07-01T10:40:00+00:00",
      "attachments": []
    }
  ],
  "next_cursor": null,
  "has_more": false
}

Объект сообщения

• id, conversation_id, thread_id (обычно null).
• sender_type — CLIENT (клиент), OPERATOR, AI или SYSTEM.
• content — текст сообщения.
• is_internal_note — здесь всегда false.
• reply_to_id — id сообщения, на которое это ответ, или null.
• created_at — ISO-8601.
• attachments — массив { id, filename, content_type, size }.

Отправить сообщение

Доставляет сообщение клиенту через канал диалога. Сообщение записывается как OPERATOR с пометкой об отправке через API и появляется в панели оператора в реальном времени.

{
  "content": "Your refund of $20.00 has been processed.",
  "reply_to_message_id": null,
  "sender_user_id": null
}

{
  "id": "b2d7e410-3c88-4a15-9f60-7d8e9a0b1c2d",
  "conversation_id": "3f2b1c9a-7d4e-4b21-9c33-0a1b2c3d4e5f",
  "thread_id": null,
  "sender_type": "OPERATOR",
  "content": "Your refund of $20.00 has been processed.",
  "is_internal_note": false,
  "reply_to_id": null,
  "created_at": "2026-07-01T10:41:00+00:00",
  "attachments": []
}

{ "detail": "conversation_closed" }

Поля тела

• content — обязательно; текст сообщения (до 4096 символов).
• reply_to_message_id — необязательно; id сообщения из того же диалога, на которое отвечаем.
• sender_user_id — необязательно; приписать сообщение сотруднику вместо самого ключа. См. раздел От чьего имени приходит сообщение ниже.

От чьего имени приходит сообщение

Сообщение, отправленное через API, записывается как сообщение OPERATOR, за которым не стоит человек, — поэтому имя и картинку, которые увидит клиент, выбираете вы. Есть два варианта, и выбрать можно для каждого сообщения.

От имени самого ключа (по умолчанию)

У каждого API-ключа есть имя отправителя и необязательная картинка — они задаются на странице Developer. Если никого не указывать, клиент увидит именно их: например, ключ Order Bot отображается как «Order Bot». Если имя отправителя не заполнено, используется название ключа, поэтому сообщение никогда не будет безымянным.

От имени сотрудника

Передайте sender_user_id — и сообщение будет приписано этому человеку: его имя и аватар, как если бы он написал его в дашборде. Это нужно, когда вы пересылаете ответы, написанные вашими операторами в другом месте.

{
  "content": "Возврат оформлен.",
  "sender_user_id": "7c1e5a02-9b43-4f18-8a77-2d6e0f4b9c81"
}

Идентификаторы можно получить через GET /api/v1/operators/. Человек должен состоять в том же проекте; для любого другого вернётся 400 sender_user_not_a_project_member. В обоих случаях действующий ключ записывается, так что аудит сохраняется.

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

Имя на других языках

У имени отправителя может быть версия для каждого языка — так же, как у имени ИИ-ассистента и никнеймов операторов. Клиент видит имя на языке своего диалога; для языка без перевода используется базовое имя. Добавить их можно на странице Developer, в профиле отправителя ключа.

Замечания и лимиты

• Отправка в CLOSED-диалог возвращает 400 conversation_closed.
• Групповые диалоги (группы Telegram) в v1 не поддерживаются (400 group_conversations_not_supported).
• Пустой content возвращает 400 content_required.
• Лимит: 60 запросов/минуту на API-ключ.