Skip to main content
POST
/
v1
/
messages
/
text
Send a free-form text message
curl --request POST \
  --url https://api.keebai.com/v1/messages/text \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "to": "+5491155555555",
  "phone_number_id": "100000000000001",
  "text": "Hola, ¿cómo estás?",
  "preview_url": true,
  "meta_data": {}
}
'
{
  "message_id": "<string>",
  "status": "sent",
  "sent_at": "<string>"
}
Sends a free-form text message to a recipient. WhatsApp only allows free-form text inside the 24-hour window since the user’s last inbound message; if the window is closed, Meta will reject the message and the broadcast ends in FAILED. For sends outside the window, use POST /v1/messages/template.

​
Endpoint

POST https://api.keebai.com/v1/messages/text

​
Required scope

messages:send

​
Headers

HeaderRequiredValue
AuthorizationYesBearer kbai_pk_<token>
Content-TypeYesapplication/json

​
Body

FieldTypeRequiredDescription
tostringYesRecipient phone number in E.164 format.
channel_idstringYesObjectId of the sending WhatsApp channel.
textstringYesMessage body. Up to 4096 characters.
meta_dataobjectNoFree-form metadata persisted with the message.

​
Example request

curl -X POST https://api.keebai.com/v1/messages/text \
  -H "Authorization: Bearer kbai_pk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+5491155555555",
    "channel_id": "65a1f2b3c4d5e6f7a8b9c0d1",
    "text": "Hola Lucio, ¿pudiste revisar la propuesta?"
  }'

​
Response

​
202 Accepted

{
  "broadcast_id": "65f4b5c6d7e8f9a0b1c2d3e4",
  "status": "PENDING",
  "total_recipients": 1,
  "scheduled_at": null
}
Same shape as POST /v1/messages/template.

​
400 Bad Request

Invalid body (empty text, longer than 4096 characters, malformed phone number).

​
401 Unauthorized

Missing, invalid, revoked, or expired token.

​
403 Forbidden

The token does not have the messages:send scope.

​
Operational notes

  • 24-hour window: Keebai does not reject the request if the window is closed — the send is attempted and, if Meta rejects it, the broadcast ends in FAILED. Check status with GET /v1/messages/bulk/:broadcastId.
  • No special emoji handling: WhatsApp supports full UTF-8, including emojis. Keebai performs no extra sanitization.
  • No native Markdown formatting: WhatsApp interprets *text* as bold, _text_ as italic, and ~text~ as strikethrough. A backslash escapes these characters.

Authorizations

​
Authorization
string
header
required

Personal Access Token con prefijo kbai_pk_. Generar desde el portal con permiso developer.manage_tokens.

Body

application/json
​
to
string
required
Example:

"+5491155555555"

​
phone_number_id
string
required

WhatsApp Business phone_number_id (numeric identifier issued by Meta for the sending number).

Example:

"100000000000001"

​
text
string
required
Example:

"Hola, ¿cómo estás?"

​
preview_url
boolean

Render link previews for URLs in the text body.

​
meta_data
object

Response

202 - application/json
​
message_id
string
required

Meta message_id (wamid.*) of the sent WhatsApp message.

​
status
string
required
Example:

"sent"

​
sent_at
string
required

ISO-8601 timestamp of the dispatch.