Sends a message to a contact
POST/api/v1/messages
The contact must have messaged the bot before. Send exactly one of message (free text) or template (WhatsApp only, an approved Meta template). Use Idempotency-Key to avoid duplicates on retries. Scope: messages:send.
- Scope
messages:send- SDK method
- sendMessage · send_message
- MCP tool
sendMessageexternal effect
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
Idempotency-Keyheader | string | no | Optional, 1-255 visible ASCII characters. Valid for 24 hours per organization, endpoint and key: the same key with the same body returns the first response unchanged (Idempotency-Replayed: true) and the action isn't repeated. A different body returns 409 idempotency_conflict; while the first request is running you get 409 idempotency_in_progress with Retry-After. 5xx and 429 responses aren't stored, so you can retry with the same key.len 1–255 |
Body fields
| Name | Type | Required | Description |
|---|---|---|---|
bot_id | uuid | yes | |
to | string | yes | Telegram chat ID or WhatsApp number (the contact must have messaged the bot before)len 3–64 |
message | string | no | len 1–4000 |
template | object | no | |
template.name | string | yes | |
template.language | string | yes | |
template.params | string[] | no | {{isim}} and {{custom_field}} variables are filled per contactitems ≤ 20 |
Example request
curl -X POST "https://hiboty.com/api/v1/messages" \
-H "Authorization: Bearer $HIBOTY_API_KEY" \
-H "Idempotency-Key: order-10482" \
-H "Content-Type: application/json" \
-d '{"bot_id":"3fa85f64-5717-4562-b3fc-2c963f66afa6","to":"123456789","message":"Hello!"}'Example response (201)
{
"id": "string",
"status": "sent",
"bot_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"to": "string",
"template": "string"
}Possible errors
400Invalid request: a missing or wrong field, or an unknown field name (validation_error).401The API key is missing, invalid or revoked (unauthorized).403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.bot_plan_restricted404The record doesn't exist or this key can't access it (not_found).409The action isn't possible in this state; the code gives the reason.429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.502A channel or external service failed (channel_error).