Ответить в диалоге

Этот метод позволяет отвечать в диалоге и добавлять внутренние заметки.

URL

POST https://api.carrotquest.io/conversations/{id}/reply

В качестве {id} нужно использовать ID диалога.

Параметры

Параметры аутентификации.
Параметр id_as_string.
Параметры, включающие опциональные поля объекта ConversationPart.

Параметр	Тип	Описание
body	Optional[строка]	Текст сообщения. Может быть не задан, если сообщение содержит только приложение без текста (например, картинку). По умолчанию, пустая строка
body_json	Optional[Dict]	Дополнительные данные с контентом сообщения в формате json. Зависят от типа создаваемой реплики
attachment	Optional[File]	Файл приложения к реплике.
attachment_file_name	Optional[строка]	Название файла-приложения для вывода в чате. Строка от 1 до 255 символов.
from_user	Optional[ID]	Укажите default_user в случае отправки сообщения от пользователя на сайте или ID пользователя вашего сайта
from_admin	Optional[ID/default_admin]	Укажите ID администратора в случае ответа от администратора или default_admin для отправки от имени дефолтного отправителя сайта
type	Optional[строка]	Тип реплики. Допустимы типы reply_admin, note, article. При отправке от имени пользователя (from_user) параметр игнорируется. По умолчанию: reply_admin
external_id	Optional[строка]	Id сообщения во внешнем сервисе
random_id	Optional[integer]	Случайное целое число, чтобы сопостовлять создаваемое сообщение с репликой из RTS. По умолчанию, 0
auto_assign	Optional[ID]	ID администратора. Перед ответом автоматически назначить диалог администратору с этим ID
auto_assign_random_id	Optional[integer]	Случайный ID ConversationPart о назначении для контроля отправки. По умолчанию: 0
referrer	Optional[строка]	URL страницы, с которой написано сообщение. По умолчанию не задан.
actions	Optional[Array[Dict]]	Действия, которые пользователь может совершать с данной репликой. См. описание ниже.

Замечания

Чтобы контролировать, от чьего имени будет отправлено сообщение, используйте параметры from_admin и from_user.
Чтобы указать тип сообщения (обычный ответ reply_admin, заметка note или статья базы знаний article), задайте type.

Чтобы перед ответом автоматически назначить диалог на того или иного администратора, можно указать его ID в поле auto_assign. При этом будет создано 2 реплики, а не одна: системная реплика назначения на оператора и основная реплика.

random_id и auto_assign_random_id используются для сопоставления реплики, пришедшей через Realtime services. Вы можете записать сюда случайное 32-битное число, которое придет в поле random_id объекта ConversationPart, созданного этим запросом. В этом случае нельзя использовать ID реплики, поскольку Realtime services работают асинхронно и сообщение туда может прийти раньше, чем вы получите ответ на запрос создания реплики. А может и наоборот. Порядок не определен.

Действия

Поле actions позволяет добавить действия, которые можно совершать с данной репликой. Оно используется, когда у реплики есть какой-то интерактив:

1. Кнопки
2. Поле ввода
3. Переход по ссылке

В данный момент по API можно отправить только один вид действия: quick_reply.

Быстрый ответ (quick reply)

Данное действие позволяет показать вместе с репликой кнопки с текстом, указанным в поле body этой кнопки. Когда пользователь нажимает на кнопку, в чат отправляется реплика с соответствующим контентом.

Параметры

Параметр	Тип	Описание
type	строка	Тип действия. quick_reply
body	строка, не более 300 символов	Текст кнопки. Учтите, что слишком длинный текст может некрасиво выглядеть в кнопке.
meta_data	Optional[Dict]	Дополнительные данные, добавляемые в поле meta_data реплики.

Необязательное поле meta_data позволяет при нажатии на кнопку добавить в созданную реплику пользователя данные из поля meta_data, которые можно будет придет при получении реплики через Web API, Realtime Services API и Webhook. Это позволяет сопоставить, какая именно кнопка была нажата и предпринять соответствующее автоматическое действие, используя API.

Примеры

[
  {"type":  "quick_reply", "body": "Принять", "meta_data":  {"external_id": 1}},
  {"type":  "quick_reply", "body": "Отказаться", "meta_data":  {"external_id": 2}}
]

Ответ

Поле data будет содержать созданные реплики (объекты ConversationPart):

• основная реплика будет возвращена как базовое содержимое data
• реплика назначения будет возвращена в поле data.assign_part (если был указан параметр auto_assign)

Пример:

{
  "data": {
    "id": "1453279698921457472",
    "created": 1685352440,
    "conversation": "1447294760057308402",
    "body": "Каков твой выбор, Нео?",
    "body_json": {},
    "direction": "u2a",
    "type": "reply_user",
    "sent_via": "api",
    "attachments": [
      {
        "type": "file",
        "id": "1453279691052943108",
        "filename": "test_import.csv",
        "mime_type": "text/csv",
        "size": 156,
        "url": "https://files.carrotquest.app/attachments/2782/2e7cac55-dff0-4142-9460-14d64ff08623/test_import.csv",
        "created": 1685352439
      }
    ],
    "meta_data": {
      "some_extra_reply_information": 123
    },
    "reply_type": "no",
    "actions": [{"type": "quick_reply", "body": "Красная", "meta_data": {"id":  1}}, {"type": "quick_reply", "body": "Синяя", "meta_data": {"id":  2}}],
    "edited": null,
    "removed": null,
    "external_id": null,
    "part_group": "1447294760216691955",
    "from": "1447294708215711734",
    "assign_part": {
      "id": "1453281238935668443",
      "created": 1685352624,
      "conversation": "1447294760057308402",
      "body": "",
      "body_json": {},
      "direction": "a2u",
      "type": "assigned",
      "sent_via": "api",
      "meta_data": {},
      "reply_type": "no",
      "actions": null,
      "edited": null,
      "removed": null,
      "external_id": null,
      "part_group": "1447294760216691955",
      "assignee": {
        "id": "30542",
        "name": "Test",
        "avatar": "https://files.carrotquest.app/avatars/default-v4.png",
        "type": "admin"
      },
      "from": {
        "id": "30542",
        "name": "Test",
        "avatar": "https://files.carrotquest.app/avatars/default-v4.png",
        "type": "admin"
      }
    }
  },
  "meta": {
    "status": 200
  }
}

Ошибки

Стандартные ошибки Web API.

Ошибки данного метода

Ошибка	Код	Описание
ReplyTooBig	400	Слишком длинный текст реплики (body)

Примеры

Ответить от имени администратора и назначить диалог на него (ID администратора 8164):

curl -X POST \
  --data-urlencode "body=Some Admin Message" \
  --data-urlencode "from_admin=8164" \
  --data-urlencode "auto_assign=8164" \
  -H "Authorization: Token XXX" \
  https://api.carrotquest.io/conversations/1789152/reply

Ответить от имени пользователя на сайте:

curl -X POST \
  --data-urlencode "body=Some User Message" \
  --data-urlencode "from_user=default_user" \
  -H "Authorization: Token XXX" \
  https://api.carrotquest.io/conversations/1789152/reply

Добавить заметку от имени администратора (ID администратора 8164):

curl -X POST \
  --data-urlencode "body=Some Admin Message" \
  --data-urlencode "from_admin=8164" \
  --data-urlencode "type=note" \
  -H "Authorization: Token XXX" \
  https://api.carrotquest.io/conversations/1789152/reply