smartchat

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

Permissionsends:create (all permissions)
RiskSend (reaches other people)
Idempotency-KeyRequired (how it works)
Safe to repeatSafe to repeat with the same Idempotency-Key: the first answer comes back and nothing is done twice.
Rate limit classsend (120 requests per minute per key)
ConfirmationNone
MCP toolsend_text_message
Since version2026-10-25

#What it does

  • Sends WhatsApp messages to contacts.
  • Safe to repeat with the same Idempotency-Key.

#Request

Header

NameRequiredDescription
AuthorizationyesBearer <key>
Idempotency-KeyyesA unique value for this operation, for example a UUID (1 to 255 visible ASCII characters).

Body (JSON)

NameTypeRequiredDescription
typestringyesAlways text for a free text message. always text
contact_idstringyesContact ID from search_contacts.
textstringyesThe 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-*.

NameTypeDescription
objectstringAlways "send". always send
idstringSend ID.
typestringtext = free text inside the 24-hour window, template = approved template. one of: text, template
statusstringState of the send. one of: queued, sent, delivered, read, failed, skipped
contact_idstringContact ID.
template_idstring or nullTemplate ID for template sends, otherwise null. up to 36 characters
provider_message_idstring or nullID 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
textstring or nullThe final text. Built from the template and contact data: untrusted text. up to 4100 characters; untrusted text
failure_reasonstring or nullWhy a send failed or was skipped. English, no internal details. up to 300 characters
created_atstringWhen the send was created. up to 40 characters; format date-time
sent_atstring or nullWhen WhatsApp accepted the message. up to 40 characters; format date-time

#Errors

CodeStatusWhen
bad_request400The request could not be read.
idempotency_key_invalid400The 'Idempotency-Key' header must be 1 to 255 visible ASCII characters.
idempotency_key_required400This call needs an 'Idempotency-Key' header.
missing_parameter400A required field is missing.
unknown_parameter400A field is not known.
api_key_expired401This API key has expired.
api_key_invalid401This API key is not valid.
api_key_revoked401This API key was revoked.
authentication_required401No API key was sent. Send 'Authorization: Bearer <key>'.
quota_exceeded402The monthly message quota is used up.
account_blocked403This account is blocked.
insufficient_scope403This key lacks a required permission.
ip_not_allowed403This IP address is not allowed for this key.
subscription_locked403The subscription or payment state blocks this function.
contact_not_found404No contact with this ID exists in this account.
idempotency_in_progress409A request with this idempotency key is still running.
contact_not_confirmed422The contact has no confirmed opt-in.
contact_opted_out422The contact has unsubscribed.
idempotency_key_reused422This idempotency key was already used with a different request.
number_suppressed422The number is on the suppression list.
validation_failed422A field is not valid.
whatsapp_not_connected422No WhatsApp number is connected.
window_closed422The 24-hour window is closed. Free text is not possible.
rate_limited429Too many requests. Wait and try again.
internal_error500Something went wrong on our side.
upstream_error502A connected service (for example WhatsApp) reported an error.
service_unavailable503The service is temporarily unavailable.
suppression_check_unavailable503The suppression list cannot be read, so nothing was sent.

All errors use one format.