Send on Telegram
Answer people who message your Telegram bot, from your code.
What you'll build
Code that replies to a person who wrote to your Telegram bot.
How Telegram differs
A Telegram bot cannot message someone first. The person has to start a chat with your bot; from then on you can reply in that conversation. There is no reply window. A message is up to 4,096 characters; longer texts are split.
Prerequisites
- A secret API key with
messages:sendandmessages:read. See Authentication and API keys. - A Telegram bot connected in the dashboard under Channels. It is a Binding, your sender on Telegram.
- A conversation someone started with your bot. Its id comes from a
message.receivedevent (webhooks or the event stream) or fromGET /v1/conversations. - curl, Node.js 18 or later with
@voicelayer/api, or Python 3.9 or later withvoicelayer.
export CONVERSATION_ID=<the conversation's id>Step 1: Find the conversation
List recent Telegram conversations if you don't have the id yet. GET /v1/conversations returns the most recently active first:
curl "https://api.vlayers.ai/v1/conversations?controller=human&limit=20" \
-H "Authorization: Bearer $VOICELAYER_API_KEY"The example filters on controller=human; drop that filter, or use channel=telegram, to see all Telegram conversations.
Step 2: Reply
POST /v1/conversations/{id}/messages replies in the conversation. Your bot and the person come from the conversation.
curl -X POST "https://api.vlayers.ai/v1/conversations/$CONVERSATION_ID/messages" \
-H "Authorization: Bearer $VOICELAYER_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"content": {
"type": "text",
"text": "Yes, we have a table at 7pm. Shall I book it?"
}
}'{
"message": {
"id": "0192f5b0-8d1f-7b62-8c3e-5f9a2b7d4e32",
"conversationId": "0192f5b0-7c3e-7a51-9b2d-4e8f1a6c3d21",
"channel": "sms",
"direction": "outbound",
"status": "queued",
"text": "Yes, we have a table at 7pm. Shall I book it?",
"media": [],
"from": "+14155550100",
"to": "+15550123",
"bindingId": null,
"metadata": {},
"error": null,
"createdAt": "2026-10-20T15:04:05.000Z",
"parts": [
{
"id": "0192f5b0-8d1f-7b62-8c3e-5f9a2b7d4e32",
"status": "queued"
}
]
}
}Test it
In test mode, test-1, test-2 and so on play people writing to your bot. Your workspace needs a connected Telegram bot to receive the simulated message on:
curl -X POST https://api.vlayers.ai/v1/test/inbound \
-H "Authorization: Bearer $VOICELAYER_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"channel": "telegram",
"from": "test-1",
"text": "Hi, is my order ready?"
}'Save the returned conversationId as CONVERSATION_ID and run Step 2. See Test mode.
Common errors
| Error | Status | How to fix |
|---|---|---|
not_found | 404 | Check the id, and that the key belongs to the workspace (and covers the channel) that owns it. |
no_sender | 409 | Connect a sender for the channel in the dashboard (for email, create a mailbox), or name one in from. |
capability_not_ready | 409 | Fix the connection in the dashboard (Channels) using details.remediation when present, then send again. |
content_too_long | 422 | Shorten the text, or send it with split: "auto" where it fits the part limit. |
test_address_required | 422 | Use a reserved test address, or a live key to reach a real person. |