How to send a message to a client via API

Sending a message via the API is how you respond to a client on behalf of your integration. The message reaches the client in their chat with the bot, just like an operator's response from the applica

Updated November 2, 20264 min
Sending a message via the API is how you respond to a client on behalf of your integration. The message reaches the client in their chat with the bot, just like an operator's response from the application.
In this article: how to send text, a file, a reply to a specific message, and a scheduled message; how to check that a message has been sent; and how to edit or delete it.


Requirements

  1. An API key with the Space controller role or higher. Learn more about roles — API Key Permissions: Which Role to Assign.
  1. Chat ID. How to find it — in the article How to get chats and messages via API.
The message will be delivered to a real client
There is no test environment. Test your integration on yourself: message the bot from your Telegram and send messages to that chat.


Send a text message

Use POST /messages/v1/send with chat_id and content in the body to send a message to a client:
POST
https://api.chatterfy.ai/public-api/messages/v1/send

Send a message to the chat


Запросbash
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 ₽."}'
The response will include the created message with its id and status.
Field
Required
Description
chat_id
Yes
Chat ID
content
Text or files
Message text, up to 4096 characters
files
Text or files
Up to 10 attachments, see below
reply_message_id
No
ID of the message you are replying to
schedule
No
When to send, if not now
meta
No
Additional data in JSON format
The API will not accept an empty message—without text or files—and will return an empty_message error.


Send a file: photo, video, document

The API does not accept files directly—only links to them. Place the file where it opens via a direct public link, and pass the link in files.
Тело запросаjson
{
  "chat_id": "ID_ЧАТА",
  "content": "Ваш договор",
  "files": [
    { "type": "document", "url": "https://example.com/files/contract.pdf" }
  ]
}
`type`
What will be sent
photo
Photo
video
Video
audio
Audio file
voice
Voice message
document
Any file as a document
sticker
Sticker
animation
GIF animation
Text from content will be sent together with the file. To send only the file, do not pass content.
The link must be accessible without login
If the file is password-protected or requires authorization, Chatterfy will not be able to retrieve it, and the message will not be sent.


Reply to a specific customer message

To reply to a specific customer message, pass its id in reply_message_id of the POST /messages/v1/send request. The message must be from the same chat, otherwise the API will return an unknown_reply_message error.
Тело запросаjson
{
  "chat_id": "ID_ЧАТА",
  "content": "Да, доставим завтра до 18:00.",
  "reply_message_id": "ID_СООБЩЕНИЯ_КЛИЕНТА"
}


Schedule a message for a specific time

To send a message later, pass a future time in schedule. You can specify the time in UTC with a Z at the end or with your own time zone:
  • 2026-11-01T09:00:00Z — 9:00 UTC, which is 12:00 Moscow time;
  • 2026-11-01T12:00:00+03:00 — the same time, recorded in Moscow time.
Тело запросаjson
{
  "chat_id": "ID_ЧАТА",
  "content": "Напоминаем о встрече сегодня в 15:00.",
  "schedule": "2026-11-01T12:00:00+03:00"
}
Before sending, the message has a schedule status.


Verify that the message was sent

The sending status is in the status field of the message from GET /messages/v1/{message_id}: ready — sent, waiting — still sending, failed — not sent.

  1. Save the message id

    Take the id from the sending response.

  2. Request the message

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

  3. Check the status

    ready — sent. waiting — still sending, check again in a few seconds. failed — not sent, the reason is in the error field.


Edit or delete a message

To change the text of a sent message, send a PATCH /messages/v1/{message_id} request with the new content. A role of Space moderator, Space controller or higher is required.
Изменить текстbash
curl -X PATCH 'https://api.chatterfy.ai/public-api/messages/v1/ID_СООБЩЕНИЯ' \
  -H 'ApiKey: ВАШ_КЛЮЧ' \
  -H 'Content-Type: application/json' \
  -d '{"content": "Исправленный текст"}'
To delete a message, send a DELETE /messages/v1/{message_id} request:
Удалить сообщениеbash
curl -X DELETE 'https://api.chatterfy.ai/public-api/messages/v1/ID_СООБЩЕНИЯ' \
  -H 'ApiKey: ВАШ_КЛЮЧ'


Rules for bulk messaging

  • One request — one message to one chat. There is no bulk sending list.
  • The limit is 120 requests per minute per key. If exceeded, the API will return 429, and the Retry-After header will indicate how many seconds to wait.
  • Before sending, filter your chats and count them using POST /chats/v1/stats — this will show you how many clients will receive the message.
  • If a request fails, do not resend it immediately. First, check the last messages in the chat; otherwise, the client may receive the message twice.


FAQ



Related

How to get chats and messages via API
Chats and messages via the API are read in two requests: first the list of bot chats, then the messages of the specific chat. This is the same as opening the bot in the application and tapping on a co
How to update a chat via API: status, tags, assignee, fields
Modifying a chat via API is the same as editing a client card in the app: changing the status, assignee, tags, and fields. Everything is done with a single PATCH request, in which you pass only what y
New real-time messages via API
Real-time is a way to learn about new messages and changes in chats immediately, without constant polling. Chatterfy sends an event to your program as soon as something happens. Article for programmer
API Errors and Limits
An API error is a response where Chatterfy explains why it didn't complete a request. All errors look the same, so you can figure them out using two fields: the response code and code . This article e

Was this article helpful?