Отправляет текстовое сообщение клиенту в его самую свежую переписку. Клиента метод ищет по полю карточки.
POST /public/contacts/message
Тело запроса
| Поле | Тип | Обязательное | Описание |
|---|---|---|---|
match.field |
строка | да | Ключ поля или колонка списка, 1–64 символа: латиница, цифры, _ . -. См. поиск по полю |
match.value |
строка или число | да | Значение поля. Пробелы по краям обрезаются. На пустое значение придёт ошибка |
text |
строка | да | Текст сообщения, 1–4000 символов после обрезки пробелов по краям |
source |
строка | нет | Подпись источника для события в ленте, 1–60 символов. По умолчанию Внешняя система |
idempotencyKey |
строка | нет | Ключ повтора, 1–100 символов. С тем же ключом сообщение второй раз не отправится |
{
"match": { "field": "crm_accounts.id", "value": "1042" },
"text": "Ваш заказ готов, можно забирать.",
"source": "CRM",
"idempotencyKey": "order-1042-ready"
}
Куда уходит сообщение
Polygram берёт переписки всех найденных контактов и выбирает самую свежую по времени последнего сообщения из тех, куда можно писать:
- канал переписки подключён и работает;
- в WhatsApp и Instagram клиент писал в последние 24 часа. Так требует Meta.
Метод отправляет только текст. Шаблоны WhatsApp, файлы и кнопки отправляйте другим способом.
Ответ
200 OK. Ответ приходит, когда сообщение ушло в канал, но не позже чем через 20 секунд.
{
"sent": true,
"status": "SENT",
"error": null,
"duplicate": false,
"conversationId": "cmg1x2y3z0001ab12cd34ef56",
"messageId": "cmg1x2y3z0002ab12cd34ef56",
"channel": "WhatsApp: Отдел продаж"
}
| Поле | Описание |
|---|---|
sent |
true, если сообщение ушло в канал |
status |
SENT, DELIVERED, READ: сообщение ушло. PENDING: отправка не закончилась за 20 секунд. FAILED: канал вернул ошибку |
error |
Причина при sent: false: текст ошибки канала или Отправка ещё идёт |
duplicate |
true, если сообщение с этим idempotencyKey уже было и новое не отправлялось. Остальные поля тогда описывают первое сообщение |
conversationId |
Диалог, в который ушло сообщение |
messageId |
Сообщение в Polygram |
channel |
Тип и название канала: WhatsApp: …, Telegram: …, Instagram: … |
При sent: false код ответа тоже 200. Сообщение уже создано и стоит в очереди. Polygram делает до трёх попыток с растущей паузой, поэтому ответ с FAILED приходит только через 20 секунд.
Чтобы узнать результат после PENDING, повторите запрос с тем же idempotencyKey. Придёт текущий статус, нового сообщения не будет. Чтобы отправить заново после FAILED, возьмите новый ключ.
Ошибки
| Код | Когда |
|---|---|
| 400 | Поля не прошли проверку |
| 401 | Нет ключа доступа или он неверный |
| 404 | Нет контакта с таким значением поля |
| 409 | У контакта нет ни одной переписки |
| 422 | Все каналы клиента отключены, или все его переписки в WhatsApp и Instagram вне окна 24 часа |
Случай 422 видно по тексту ошибки: Канал клиента отключён или Клиент не писал больше суток….
Что происходит в Polygram
- Сообщение сразу появляется в переписке у сотрудников, без автора-сотрудника.
- В ленту диалога пишется событие Сообщение через внешнюю систему.
- Диалог поднимается в списке.
- Отметка о прочтении и назначение диалога не меняются.
- Запущенные в диалоге workflow продолжают работать: сообщение не считается ответом оператора.
- Пуш-уведомления сотрудникам не отправляются.
Повтор с тем же idempotencyKey возвращает первое сообщение, даже если в повторе другой text.
Пример
curl -X POST https://api.polygram.chat/api/public/contacts/message \
-H "X-Api-Key: ak_..." \
-H "Content-Type: application/json" \
-d '{
"match": { "field": "crm_accounts.id", "value": "1042" },
"text": "Ваш заказ готов, можно забирать.",
"source": "CRM",
"idempotencyKey": "order-1042-ready"
}'
Запрос может идти до 20 секунд, поэтому таймаут клиента ставьте больше.