Sending Messages — Overview
All message-sending endpoints follow the same base structure, regardless of the channel. Understanding this structure makes it easier to work with multiple channels at the same time.
Base structure
{
"from": "<channel-uuid-or-channel-specific-id>",
"to": "<recipient-identifier>",
"content": { "text": "Hello!" }
}
| Field | Type | Required | Description |
|---|---|---|---|
from | string | ✅ | Sender Application Channel: UUID (always works), or the channel-specific alternate when supported — see from field. Web Chatt: UUID or configured display name. |
to | string | ✅ | Recipient identifier (varies by channel) |
content | object | ✅ | The message content (see types below) |
from field (sender channel)
For all six supported channels, from selects which Application Channel sends the message. You may pass:
- Application channel UUID — always accepted (shown in Hub as Application Channel ID).
- Alternate identifier — must match the channel configuration for your Application (Hub shows copyable values on the channel details screen):
| Channel | Alternate from |
|---|---|
| Telegram | Bot username (botUsername), with or without a leading @ |
Business phone number (phoneNumber), with or without a leading + | |
Instagram username (username), with or without a leading @ | |
| Messenger | Facebook Page username, Page ID (pageId), or configured account id when used |
| SMS | Twilio sender number (phoneNumber) or Brazilian SMS display name |
| Web Chatt | Configured display name (case-insensitive) |
Aliases must belong to the API-key application. Use the UUID when a name is ambiguous or unavailable. The widget public key is not a send identifier. The Web Chatt send operation is included in the API reference.
Discover available channels
Use the application's API key to discover configured channels and copy each returned from value:
curl 'https://app.chatt2.me/v1/integration/application/channels?offset=0&limit=20' \
-H 'x-api-key: YOUR_APPLICATION_API_KEY'
{
"data": [
{
"id": "e690cc45-4abe-4f83-8373-01e7026797ad",
"channelType": "WEB_CHATT2ME",
"name": "Website support",
"from": "Website support",
"isSandbox": false,
"keyword": null
}
],
"pagination": { "offset": 0, "limit": 20, "total": 1, "totalPages": 1 }
}
offset is a zero-based page index, not a row offset: the second page is ?offset=1&limit=20 (rows 21–40). The default limit is 20, maximum 50, minimum 1; offset must be nonnegative. Invalid pagination returns HTTP 400 with the common API error body. Completed sandboxes return their keyword as from; incomplete setup is not listed. Use the channel discovery reference for the complete response.
Endpoints by channel
Sandbox sends reuse the WhatsApp, Instagram, and Messenger endpoints below. See Sandbox.
| Channel | Endpoint |
|---|---|
POST /v1/communication/whatsapp/message | |
POST /v1/communication/instagram/message | |
| Messenger | POST /v1/communication/messenger/message |
| Telegram | POST /v1/communication/telegram/message |
| SMS | POST /v1/communication/sms/message |
| Web Chatt | POST /v1/communication/web-chatt2me/message |
to field format by channel
The format of to varies by channel. See to field formats in Concepts & Architecture for the complete reference.
Response status
Successful message submissions normally return a Hub messageId and a submission status:
{
"messageId": "9307b9ab-5fab-4151-b7c2-b00c2a8a6e8e",
"status": "sent"
}
| Status | Channels | Meaning |
|---|---|---|
sent | Telegram, Instagram, SMS, Web Chatt; control actions on supported channels | The send/control call succeeded; this is not proof that the recipient read or received a new message |
enqueued | WhatsApp, Messenger, and all three sandboxes | Submission accepted; delivery can still fail later |
error | All | The send result failed; inspect available errorMessage and errorCode |
Typing actions create no message and return messageId: "". WhatsApp mark-seen returns the existing target's Hub ID; Web Chatt mark-seen returns an empty ID. Instagram/Messenger mark-seen is forwarded as a provider control action but persisted through the ordinary outbound path, returning a new Hub ID (sent for Instagram, enqueued for Messenger); it is not a new user-visible text message. Offline Web Chatt messages can remain pending even when the send response says sent.
Validation, authentication, application scope, media checks, quota, or credit failures can instead return a non-2xx HTTP response with statusCode, code, message, hint, and optional errors; they are not send-result objects. A provider submission failure caught by a live send can return HTTP 200 with status: "error". Check both the HTTP status and the body. See Troubleshooting and the operation's documented errors.
Delivery/read updates arrive as eventType: "message_status" through the configured webhook subscriptions. Use webhook payload.message.id for inbound message IDs; messageId belongs to a send response. A provider's own ID is a separate identifier.
Sessions, Agent ownership, and billing
An ordinary public API send participates in the conversation lifecycle. When a matching Agent session is active or awaiting_human, sending transfers it to transferred, stopping Agent inference for that session. A successful request can create or reuse a session; receiving a message is not the only way a session appears. Coordinate API replies with the session/queue workflow to avoid taking over an Agent conversation unintentionally.
For Instagram, Messenger, Telegram, and Web Chatt, a normal outbound can authorize and finalize the session charge if that session has not already been charged. WhatsApp and SMS use their applicable message/template pricing; SMS still has a technical Agent session. Technical session duration is not permission to send under a provider's policy. Credit authorization can reject the request before provider submission; check the HTTP error and the organization's wallet in Hub. See Application wallet history.
Typing and WhatsApp/Web Chatt mark-seen take their control paths before ordinary session/billing logic. Instagram/Messenger mark-seen uses the ordinary outbound session/charge path. Sandboxes use their shared message quota, rather than ordinary live-channel charging. Instagram comment automation has the separate behavior described in its channel guide.
Content types
The content field determines the type of message sent. The available types are:
| Type | Main field | Description |
|---|---|---|
| Text | text | Simple text message |
| Image | imageUrl | Image with optional caption |
| Video | videoUrl | Video with optional caption |
| Audio | audioUrl | Audio file |
| Document | documentUrl | File (PDF, DOCX, etc.) |
| Sticker | stickerUrl | Sticker |
| Location | location | Geographic coordinates |
| Contact | contact / contacts | One or multiple vCard contacts |
| Interactive | interactive | Buttons, list, CTA URL, location request |
| Template | template | Meta-approved template (WhatsApp) |
| Reaction | reaction | React to an existing message |
| Mark as seen | markSeen | Mark message as read |
| Is typing | isTyping | Show typing indicator |
| Payment Request | paymentRequest | Charge via PIX, Boleto, or Link |
| Order Status | orderStatus | Order status update |
See availability of each type per channel in Content Types. To send media with
a caption, include text alongside the media field and check the caption support matrix:
Telegram supports image/video/audio/document captions; WhatsApp supports image/video/document
captions; Web Chatt supports image/video/document captions (documents require widget v1.3.3 or later). Instagram and Messenger do not support media captions.
Next steps
- Content Types — channel support and examples for each type
- Interactive Messages — buttons, lists, and CTA URL
- WhatsApp Templates — sending outside the 24h window