Send text message
Sends a free text message to one contact by WhatsApp as a reply. It only works while the 24-hour window of the contact is open; otherwise it fails with window_closed and a template must be used. Needs an Idempotency-Key header.
POST /v1/sends
| Permission | sends:create (all permissions) |
| Risk | Send (reaches other people) |
| Idempotency-Key | Required (how it works) |
| Safe to repeat | Safe to repeat with the same Idempotency-Key: the first answer comes back and nothing is done twice. |
| Rate limit class | send (120 requests per minute per key) |
| Confirmation | None |
| MCP tool | send_text_message |
| Since version | 2026-10-25 |
#What it does
- Sends WhatsApp messages to contacts.
- Safe to repeat with the same Idempotency-Key.
#Request
Header
| Name | Required | Description |
|---|---|---|
Authorization | yes | Bearer <key> |
Idempotency-Key | yes | A unique value for this operation, for example a UUID (1 to 255 visible ASCII characters). |
Body (JSON)
| Name | Type | Required | Description |
|---|---|---|---|
type | string | yes | Always text for a free text message. always text |
contact_id | string | yes | Contact ID from search_contacts. |
text | string | yes | The message text (1 to 4000 characters). length 1 to 4000 |
#Examples
curl -X POST "https://api.smartchat.marketing/v1/sends" \
-H "Authorization: Bearer $SMARTCHAT_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"type": "text",
"contact_id": "con_0f8c1a2e4b7d4c3e9a5b6d7e8f901234",
"text": "Yes, a table is free on Friday at 7 pm."
}'import os
import uuid
import requests
response = requests.post(
"https://api.smartchat.marketing/v1/sends",
headers={
"Authorization": "Bearer " + os.environ["SMARTCHAT_API_KEY"],
"Idempotency-Key": str(uuid.uuid4()),
},
json={
"type": "text",
"contact_id": "con_0f8c1a2e4b7d4c3e9a5b6d7e8f901234",
"text": "Yes, a table is free on Friday at 7 pm.",
},
)
response.raise_for_status()
print(response.json())const response = await fetch("https://api.smartchat.marketing/v1/sends", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.SMARTCHAT_API_KEY}`,
"Idempotency-Key": crypto.randomUUID(),
"Content-Type": "application/json",
},
body: JSON.stringify({
"type": "text",
"contact_id": "con_0f8c1a2e4b7d4c3e9a5b6d7e8f901234",
"text": "Yes, a table is free on Friday at 7 pm."
}),
});
if (!response.ok) throw new Error(await response.text());
console.log(await response.json());Response (202):
{
"object": "send",
"id": "snd_3c4d5e6f7a8b49c0d1e2f3a4b5c6d7e8",
"type": "text",
"status": "sent",
"contact_id": "con_0f8c1a2e4b7d4c3e9a5b6d7e8f901234",
"template_id": null,
"provider_message_id": "wamid.HBgLNDkxNTExMjM0NTY3OA",
"text": "Yes, a table is free on Friday at 7 pm.",
"failure_reason": null,
"created_at": "2026-10-25T09:41:07Z",
"sent_at": "2026-10-25T09:41:07Z"
}#Response
Status 202. Every response has the headers Request-Id, SmartChat-Version and X-RateLimit-*.
| Name | Type | Description |
|---|---|---|
object | string | Always "send". always send |
id | string | Send ID. |
type | string | text = free text inside the 24-hour window, template = approved template. one of: text, template |
status | string | State of the send. one of: queued, sent, delivered, read, failed, skipped |
contact_id | string | Contact ID. |
template_id | string or null | Template ID for template sends, otherwise null. up to 36 characters |
provider_message_id | string or null | ID of the message at WhatsApp (starts with wamid), once WhatsApp accepted it. Not the same as a message ID of the inbox. up to 200 characters |
text | string or null | The final text. Built from the template and contact data: untrusted text. up to 4100 characters; untrusted text |
failure_reason | string or null | Why a send failed or was skipped. English, no internal details. up to 300 characters |
created_at | string | When the send was created. up to 40 characters; format date-time |
sent_at | string or null | When WhatsApp accepted the message. up to 40 characters; format date-time |
#Errors
| Code | Status | When |
|---|---|---|
bad_request | 400 | The request could not be read. |
idempotency_key_invalid | 400 | The 'Idempotency-Key' header must be 1 to 255 visible ASCII characters. |
idempotency_key_required | 400 | This call needs an 'Idempotency-Key' header. |
missing_parameter | 400 | A required field is missing. |
unknown_parameter | 400 | A field is not known. |
api_key_expired | 401 | This API key has expired. |
api_key_invalid | 401 | This API key is not valid. |
api_key_revoked | 401 | This API key was revoked. |
authentication_required | 401 | No API key was sent. Send 'Authorization: Bearer <key>'. |
quota_exceeded | 402 | The monthly message quota is used up. |
account_blocked | 403 | This account is blocked. |
insufficient_scope | 403 | This key lacks a required permission. |
ip_not_allowed | 403 | This IP address is not allowed for this key. |
subscription_locked | 403 | The subscription or payment state blocks this function. |
contact_not_found | 404 | No contact with this ID exists in this account. |
idempotency_in_progress | 409 | A request with this idempotency key is still running. |
contact_not_confirmed | 422 | The contact has no confirmed opt-in. |
contact_opted_out | 422 | The contact has unsubscribed. |
idempotency_key_reused | 422 | This idempotency key was already used with a different request. |
number_suppressed | 422 | The number is on the suppression list. |
validation_failed | 422 | A field is not valid. |
whatsapp_not_connected | 422 | No WhatsApp number is connected. |
window_closed | 422 | The 24-hour window is closed. Free text is not possible. |
rate_limited | 429 | Too many requests. Wait and try again. |
internal_error | 500 | Something went wrong on our side. |
upstream_error | 502 | A connected service (for example WhatsApp) reported an error. |
service_unavailable | 503 | The service is temporarily unavailable. |
suppression_check_unavailable | 503 | The suppression list cannot be read, so nothing was sent. |
All errors use one format.