Как отправить сообщение клиенту через API

Отправка сообщения через API — это ответ клиенту от имени вашей интеграции. Сообщение уходит клиенту в чат с ботом, так же как ответ оператора из приложения. В статье — как отправить текст, файл, отве

Обновлено 2 ноября 2026 г.3 мин

Отправка сообщения через API — это ответ клиенту от имени вашей интеграции. Сообщение уходит клиенту в чат с ботом, так же как ответ оператора из приложения.

В статье — как отправить текст, файл, ответ на конкретное сообщение и отложенное сообщение, как проверить, что сообщение ушло, и как его исправить или удалить.

Что понадобится

API-ключ с ролью Space controller или выше. Подробнее о ролях — Права API-ключа: какую роль выдать.

id чата. Как его найти — в статье Как получить чаты и сообщения через API.

Сообщение получит настоящий клиент

Тестовой среды нет. Проверяйте интеграцию на себе: напишите боту со своего Telegram и отправляйте сообщения в этот чат.

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

Сообщение клиенту отправляет POST /messages/v1/send с chat_id и content в теле:

POST

https://api.chatterfy.ai/public-api/messages/v1/send

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

curl -X POST 'https://api.chatterfy.ai/public-api/messages/v1/send' \
  -H 'ApiKey: ВАШ_КЛЮЧ' \
  -H 'Content-Type: application/json' \
  -d '{"chat_id": "ID_ЧАТА", "content": "Здравствуйте! Доставка по городу — 300 ₽."}'

В ответ придёт созданное сообщение с его id и status.

Поле	Обязательно	Что значит
`chat_id`	Да	id чата
`content`	Текст или файлы	Текст сообщения, до 4096 символов
`files`	Текст или файлы	До 10 вложений, ниже
`reply_message_id`	Нет	id сообщения, на которое вы отвечаете
`schedule`	Нет	Когда отправить, если не сейчас
`meta`	Нет	Дополнительные данные в формате JSON

Пустое сообщение — без текста и без файлов — API не примет и вернёт ошибку empty_message.

Отправьте файл: фото, видео, документ

API не принимает файлы напрямую — только ссылки на них. Положите файл туда, где он открывается по прямой публичной ссылке, и передайте ссылку в files.

{
  "chat_id": "ID_ЧАТА",
  "content": "Ваш договор",
  "files": [
    { "type": "document", "url": "https://example.com/files/contract.pdf" }
  ]
}

`type`	Что отправится
`photo`	Фото
`video`	Видео
`audio`	Аудиофайл
`voice`	Голосовое сообщение
`document`	Любой файл как документ
`sticker`	Стикер
`animation`	GIF-анимация

Текст из content уйдёт вместе с файлом. Чтобы отправить только файл, не передавайте content.

Ссылка должна открываться без входа

Если файл закрыт паролем или требует авторизации, Chatterfy не сможет его забрать, и сообщение не отправится.

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

Чтобы ответить на конкретное сообщение клиента, передайте его id в reply_message_id запроса POST /messages/v1/send. Сообщение должно быть из того же чата, иначе API вернёт ошибку unknown_reply_message.

{
  "chat_id": "ID_ЧАТА",
  "content": "Да, доставим завтра до 18:00.",
  "reply_message_id": "ID_СООБЩЕНИЯ_КЛИЕНТА"
}

Запланируйте отправку сообщения на время

Чтобы отправить сообщение позже, передайте в schedule время в будущем. Время можно указать по UTC с буквой Z в конце или со своим часовым поясом:

2026-11-01T09:00:00Z — 9:00 по UTC, то есть 12:00 по Москве;

2026-11-01T12:00:00+03:00 — то же время, записанное по-московски.

{
  "chat_id": "ID_ЧАТА",
  "content": "Напоминаем о встрече сегодня в 15:00.",
  "schedule": "2026-11-01T12:00:00+03:00"
}

До отправки у сообщения статус schedule.

Проверьте, что сообщение ушло

Статус отправки — в поле status сообщения из GET /messages/v1/{message_id}: ready — отправлено, waiting — ещё отправляется, failed — не отправлено.

Сохраните id сообщения

Возьмите id из ответа на отправку.

Запросите сообщение

curl 'https://api.chatterfy.ai/public-api/messages/v1/ID_СООБЩЕНИЯ' \
  -H 'ApiKey: ВАШ_КЛЮЧ'

Посмотрите на status

ready — отправлено. waiting — ещё отправляется, проверьте через несколько секунд. failed — не отправлено, причина в поле error.

Исправьте или удалите сообщение

Чтобы изменить текст отправленного сообщения, отправьте PATCH /messages/v1/{message_id} с новым content. Нужна роль Space moderator, Space controller или выше.

curl -X PATCH 'https://api.chatterfy.ai/public-api/messages/v1/ID_СООБЩЕНИЯ' \
  -H 'ApiKey: ВАШ_КЛЮЧ' \
  -H 'Content-Type: application/json' \
  -d '{"content": "Исправленный текст"}'

Чтобы удалить сообщение, отправьте DELETE /messages/v1/{message_id}:

curl -X DELETE 'https://api.chatterfy.ai/public-api/messages/v1/ID_СООБЩЕНИЯ' \
  -H 'ApiKey: ВАШ_КЛЮЧ'

Правила массовой отправки сообщений

Один запрос — одно сообщение в один чат. Отправки списком нет.

Лимит — 120 запросов в минуту на ключ. При превышении API вернёт 429, а в заголовке Retry-After подскажет, сколько секунд подождать.

Перед рассылкой отберите чаты фильтром и посчитайте их через POST /chats/v1/stats — так вы увидите, скольким клиентам уйдёт сообщение.

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

Частые вопросы

Связанное

Как получить чаты и сообщения через API

Чаты и сообщения через API читаются двумя запросами: сначала список чатов бота, потом сообщения нужного чата. Это то же самое, что открыть бота в приложении и нажать на диалог. В статье — как получить

Как изменить чат через API: статус, теги, ответственный, поля

Изменение чата через API — это то же, что правка карточки клиента в приложении: смена статуса, ответственного, тегов и полей. Всё делается одним запросом PATCH , в котором вы передаёте только то, что

Новые сообщения в реальном времени через API

Реальное время — это способ узнавать о новых сообщениях и изменениях в чатах сразу, без постоянных повторных запросов. Chatterfy сам присылает событие вашей программе, как только что-то произошло. Ста

Ошибки и лимиты API

Ошибка API — это ответ, в котором Chatterfy объясняет, почему не выполнил запрос. У всех ошибок одинаковый вид, поэтому разобраться можно по двум полям: коду ответа и code . В статье — как читать ошиб

Эта статья была полезна?