POST /v1/messages

curl --request POST \
  --url https://api.keebai.com/v1/messages \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "channel": "whatsapp",
  "to": "+5491155555555",
  "message": {
    "type": "text",
    "body": "Hola Juan, ¿pudiste revisar la propuesta?",
    "preview_url": true
  }
}
'

{
  "message_id": "<string>",
  "status": "sent",
  "sent_at": "<string>"
}

POST

messages

curl --request POST \
  --url https://api.keebai.com/v1/messages \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "channel": "whatsapp",
  "to": "+5491155555555",
  "message": {
    "type": "text",
    "body": "Hola Juan, ¿pudiste revisar la propuesta?",
    "preview_url": true
  }
}
'

{
  "message_id": "<string>",
  "status": "sent",
  "sent_at": "<string>"
}

One endpoint sends everything. The channel field decides where the message goes, and the type inside message decides what it looks like — text, media, a location pin, an approved template, an interactive block, or a WhatsApp Flow.

Endpoint

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

Required scope

messages:send

Headers

Header	Required	Value
`Authorization`	Yes	`Bearer kbai_pk_<token>`
`Content-Type`	Yes	`application/json`

Envelope

Field	Type	Required	Description
`channel`	`string`	Yes	`whatsapp`, `whatsapp_qr`, `instagram` or `messenger`.
`channel_id`	`string`	No	Keebai channel id. Only needed when the project has more than one active channel of that type — otherwise the single one is resolved automatically. List them with `GET /v1/channels`.
`phone_number_id`	`string`	No	WhatsApp-only alias for `channel_id`: the numeric `phone_number_id` Meta issues for the sending number. List yours with `GET /v1/whatsapp/numbers`.
`to`	`string`	Yes	Recipient. E.164 phone number on `whatsapp` and `whatsapp_qr`; the Meta-scoped id (IGSID on Instagram, PSID on Messenger) on the other channels — the same value the inbound webhook delivered as `from`.
`context.message_id`	`string`	No	Provider message id (`wamid.*` on WhatsApp) this message quotes as a reply.
`meta_data`	`object`	No	Free-form metadata persisted with the message and returned on webhooks for correlation.
`message`	`object`	Yes	The message itself, discriminated by `type`. See below.

Passing channel_id and phone_number_id together is fine — channel_id wins. Passing neither is fine too, as long as the project has exactly one active channel of that type. With more than one, the request fails with 400 CHANNEL_AMBIGUOUS and the response lists the candidate ids.

Message types

Every value of message.type, and which channels can deliver it:

`type`	WhatsApp	WhatsApp QR	Instagram	Messenger	Payload fields
`text`	✅	✅	✅	✅	`body` (max 4096), `preview_url?`
`image`	✅	✅	✅	✅	`link?` \| `media_id?`, `caption?`
`video`	✅	✅	✅	✅	`link?` \| `media_id?`, `caption?`
`audio`	✅	✅	✅	✅	`link?` \| `media_id?`, `voice?`
`document`	✅	✅	✅	✅	`link?` \| `media_id?`, `filename?`, `caption?`
`sticker`	✅	✅	✅	✅	`link?` \| `media_id?`
`location`	✅	—	—	—	`latitude`, `longitude`, `name?`, `address?`
`contacts`	✅	—	—	—	`contacts[]` (1–20 vCards)
`reaction`	✅	—	✅	✅	`message_id`, `emoji`
`template`	✅	—	—	—	`name`, `language`, `variables?`, `flow?`
`buttons`	✅	✅	✅	✅	`body_text`, `buttons[]` (1–3), `header?`, `footer_text?`
`list`	✅	✅	✅	✅	`body_text`, `button_text`, `sections[]`, `header?`, `footer_text?`
`cta_url`	✅	—	✅	—	`body_text`, `display_text`, `url`, `header?`, `footer_text?`
`catalog`	✅	—	—	—	`body_text`, `thumbnail_product_retailer_id?`, `footer_text?`
`carousel`	✅	—	✅	—	`body_text`, `cards[]` (1–10), `header?`, `footer_text?`
`flow`	✅	—	—	—	`flow_id`, `flow_token`, `flow_cta`, `body_text`, `flow_action?`, `flow_action_payload?`, `mode?`, `header_text?`, `footer_text?`

A combination outside this table fails with 422 MESSAGE_TYPE_NOT_SUPPORTED_FOR_CHANNEL, and the response lists the types that channel does accept. WhatsApp QR flattens buttons and list into a plain text message — the options are rendered as text, not as tappable controls. For media, link and media_id are mutually exclusive: exactly one is required. Upload a file with POST /v1/media/upload to get a media_id.

Example requests

curl -X POST https://api.keebai.com/v1/messages \
  -H "Authorization: Bearer kbai_pk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "whatsapp",
    "to": "+5491155555555",
    "message": {
      "type": "text",
      "body": "Hola Juan, ¿pudiste revisar la propuesta?"
    }
  }'

curl -X POST https://api.keebai.com/v1/messages \
  -H "Authorization: Bearer kbai_pk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "whatsapp",
    "phone_number_id": "109876543210987",
    "to": "+5491155555555",
    "message": {
      "type": "image",
      "link": "https://cdn.example.com/promo.png",
      "caption": "Promo de marzo"
    }
  }'

curl -X POST https://api.keebai.com/v1/messages \
  -H "Authorization: Bearer kbai_pk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "whatsapp",
    "to": "+5491155555555",
    "message": {
      "type": "template",
      "name": "welcome_v2",
      "language": "es",
      "variables": { "nombre": "Juan", "monto": "1500" }
    }
  }'

curl -X POST https://api.keebai.com/v1/messages \
  -H "Authorization: Bearer kbai_pk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "whatsapp",
    "to": "+5491155555555",
    "message": {
      "type": "buttons",
      "body_text": "¿Confirmas tu reserva para el viernes?",
      "buttons": [
        { "id": "confirm", "title": "Confirmar" },
        { "id": "reschedule", "title": "Reprogramar" }
      ],
      "footer_text": "Restaurante La Mela"
    }
  }'

curl -X POST https://api.keebai.com/v1/messages \
  -H "Authorization: Bearer kbai_pk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "instagram",
    "to": "17841400000000000",
    "message": {
      "type": "text",
      "body": "¡Gracias por escribirnos!"
    }
  }'

JavaScript

async function send(message, extra = {}) {
  const res = await fetch("https://api.keebai.com/v1/messages", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.KEEBAI_API_TOKEN}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      channel: "whatsapp",
      to: "+5491155555555",
      message,
      ...extra,
    }),
  });
  if (!res.ok) throw new Error(await res.text());
  return res.json();
}

await send({ type: "text", body: "Hola Juan" });
await send({ type: "location", latitude: -33.4489, longitude: -70.6693, name: "Sucursal Centro" });

Python

import os, requests

def send(message, **extra):
    resp = requests.post(
        "https://api.keebai.com/v1/messages",
        headers={"Authorization": f"Bearer {os.environ['KEEBAI_API_TOKEN']}"},
        json={"channel": "whatsapp", "to": "+5491155555555", "message": message, **extra},
        timeout=10,
    )
    resp.raise_for_status()
    return resp.json()

send({"type": "text", "body": "Hola Juan"})
send({"type": "document", "media_id": "1234567890", "filename": "factura.pdf"})

One body per type

Copy any of these into the message field. The envelope (channel, to, …) is the same for all of them, and every one is also available as a named example in the playground.

text

{ "type": "text", "body": "Hola Juan, ¿pudiste revisar la propuesta?", "preview_url": true }

image

{ "type": "image", "link": "https://cdn.example.com/promo.png", "caption": "Promo de marzo" }

Swap link for media_id to use a file uploaded through POST /v1/media/upload. Exactly one of the two.

video

{ "type": "video", "link": "https://cdn.example.com/demo.mp4", "caption": "Cómo activar tu cuenta" }

audio

{ "type": "audio", "link": "https://cdn.example.com/nota.ogg", "voice": true }

voice: true sends a voice note (PTT). Omit it for a plain audio file.

document

{
  "type": "document",
  "media_id": "1234567890123456",
  "filename": "factura-A-1042.pdf",
  "caption": "Tu factura de marzo"
}

sticker

{ "type": "sticker", "link": "https://cdn.example.com/gracias.webp" }

Must be WebP.

location — WhatsApp only

{
  "type": "location",
  "latitude": -33.4489,
  "longitude": -70.6693,
  "name": "Sucursal Centro",
  "address": "Av. Libertador 1234, Santiago"
}

contacts — WhatsApp only

{
  "type": "contacts",
  "contacts": [
    {
      "name": { "formatted_name": "Camila Rojas", "first_name": "Camila", "last_name": "Rojas" },
      "phones": [{ "phone": "+56912345678", "type": "WORK" }],
      "emails": [{ "email": "camila@example.com", "type": "WORK" }],
      "org": { "company": "Keebai", "title": "Account Manager" }
    }
  ]
}

Shares a contact card in the chat. It does not create a contact in Keebai — that is POST /v1/contacts.

reaction

{ "type": "reaction", "message_id": "wamid.HBgLNTQ5MTE1NTU1NTU1FQIAERgSN0EyRjc4", "emoji": "👍" }

An empty emoji clears a previous reaction.

template — WhatsApp only

{
  "type": "template",
  "name": "welcome_v2",
  "language": "es",
  "variables": { "nombre": "Juan", "monto": "1500" }
}

The only type that reaches a closed 24-hour window. Add a flow block to bind one of its FLOW buttons:

{
  "type": "template",
  "name": "encuesta_post_visita",
  "language": "es",
  "flow": { "flow_token": "csat-8f21c4", "button_index": 0, "flow_action_data": { "ticket_id": "A-1042" } }
}

buttons

{
  "type": "buttons",
  "body_text": "¿Confirmas tu reserva para el viernes a las 21:00?",
  "buttons": [
    { "id": "confirm", "title": "Confirmar" },
    { "id": "reschedule", "title": "Reprogramar" },
    { "id": "cancel", "title": "Cancelar" }
  ],
  "header": { "type": "text", "text": "Restaurante La Mela" },
  "footer_text": "Responde antes de las 18:00"
}

Max 3 buttons, titles up to 20 characters.

list

{
  "type": "list",
  "body_text": "Elige el horario que te acomode.",
  "button_text": "Ver horarios",
  "sections": [
    {
      "title": "Viernes 2",
      "rows": [
        { "id": "fri-20", "title": "20:00", "description": "Mesa junto a la ventana" },
        { "id": "fri-21", "title": "21:00", "description": "Salón principal" }
      ]
    },
    { "title": "Sábado 3", "rows": [{ "id": "sat-20", "title": "20:00" }] }
  ]
}

Max 10 sections, 10 rows each.

cta_url

{
  "type": "cta_url",
  "body_text": "Dejaste productos en tu carrito. Retoma la compra cuando quieras.",
  "display_text": "Ir al carrito",
  "url": "https://tienda.example.com/checkout/abc123",
  "footer_text": "El carrito expira en 24 horas"
}

catalog — WhatsApp only

{
  "type": "catalog",
  "body_text": "Mira nuestro catálogo de otoño.",
  "thumbnail_product_retailer_id": "SKU-1042",
  "footer_text": "Envíos a todo el país"
}

Requires a product catalog connected to the WhatsApp Business Account.

carousel

{
  "type": "carousel",
  "body_text": "Novedades de la semana",
  "cards": [
    {
      "header": { "type": "image", "link": "https://cdn.example.com/producto-1.png" },
      "body_text": "Zapatillas running — 20% off",
      "action": { "display_text": "Ver", "url": "https://tienda.example.com/p/1" }
    },
    {
      "header": { "type": "image", "link": "https://cdn.example.com/producto-2.png" },
      "body_text": "Mochila urbana — 15% off",
      "action": { "display_text": "Ver", "url": "https://tienda.example.com/p/2" }
    }
  ]
}

Max 10 cards. Meta rejects .webp images on carousel headers — those cards are dropped.

flow — WhatsApp only

{
  "type": "flow",
  "flow_id": "1234567890123456",
  "flow_token": "reserva-8f21c4",
  "flow_cta": "Reservar",
  "body_text": "Reserva tu mesa en menos de un minuto.",
  "header_text": "Restaurante La Mela",
  "footer_text": "Cupos limitados",
  "flow_action": "navigate",
  "flow_action_payload": { "screen": "WELCOME", "data": { "customer_name": "Juan" } }
}

Create and publish the Flow first. Add "mode": "draft" to test an unpublished one against a registered WABA tester.

Quoting a message

Reply to a specific message by passing its provider id in context:

{
  "channel": "whatsapp",
  "to": "+5491155555555",
  "context": { "message_id": "wamid.HBgLNTQ5MTE1NTU1NTU1FQIAERgSN0EyRjc4..." },
  "message": { "type": "text", "body": "Sí, ese mismo pedido." }
}

If the quoted message is too old for the provider to reference, Keebai retries once without the quote rather than failing the send.

Response

202 Accepted

{
  "message_id": "wamid.HBgLNTQ5MTE1NTU1NTU1FQIAERgSN0EyRjc4...",
  "status": "sent",
  "sent_at": "2026-07-27T14:31:07.221Z"
}

400 Bad Request

`code`	Meaning
`UNKNOWN_MESSAGE_TYPE`	`message.type` is not one of the 16 supported values. The response lists them in `supported_types`.
`INVALID_MESSAGE_PAYLOAD`	The payload does not match the schema for that `type`. The response lists the offending field paths.
`MEDIA_REFERENCE_REQUIRED`	A media message carried neither `link` nor `media_id`.
`MEDIA_REFERENCE_AMBIGUOUS`	A media message carried both `link` and `media_id`.
`CHANNEL_AMBIGUOUS`	More than one active channel of that type. Pass `channel_id`; candidates are in `channel_ids`.
`CHANNEL_TYPE_MISMATCH`	The `channel_id` belongs to a different channel type than `channel`.
`CHANNEL_MISSING_ACCESS_TOKEN`	The channel is connected but its provider token is missing or expired. Reconnect it in the dashboard.
`PHONE_NUMBER_ID_NOT_APPLICABLE`	`phone_number_id` was used with a non-WhatsApp channel.

401 Unauthorized

Missing, invalid, revoked, or expired token.

403 Forbidden

The token does not have the messages:send scope.

404 Not Found

CHANNEL_NOT_FOUND — the project has no active channel matching the selector.

422 Unprocessable Entity

MESSAGE_TYPE_NOT_SUPPORTED_FOR_CHANNEL — the channel cannot carry that message type. supported_types lists what it accepts.

Operational notes

24-hour window: free-form messages (everything except template) only reach a recipient whose last inbound message is under 24 hours old. Keebai attempts the send regardless; a closed window surfaces as the provider’s own error passed through.
The message lands in the Keebai inbox: every send is persisted against the recipient’s contact and pushed to the portal in realtime, on all four channels. It shows up with the agent role, since a PAT send is an integrator acting on the tenant’s behalf rather than the AI assistant.
meta_data round-trips: whatever you put there is stored with the message and echoed back on delivery and read webhooks, which is the intended way to correlate a send with your own records.
Markdown: WhatsApp interprets *text* as bold, _text_ as italic and ~text~ as strikethrough. A backslash escapes them.

Authorizations

Authorization

string

header

required

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

Body

application/json

channel

enum<string>

required

Channel the message is delivered through.

Available options:

whatsapp,

whatsapp_qr,

instagram,

messenger

Example:

"whatsapp"

string

required

Recipient. E.164 phone number on whatsapp and whatsapp_qr; the Meta-scoped id (IGSID / PSID) on instagram and messenger.

Example:

"+5491155555555"

message

object

required

Show child attributes

channel_id

string

Keebai channel id. Optional when the tenant has exactly one active channel of the given type; required to disambiguate otherwise.

Example:

"665f1a2b3c4d5e6f70819234"

phone_number_id

string

WhatsApp-only alias for channel_id: the Meta phone_number_id of the sending number. Ignored on other channels.

Example:

"100000000000001"

context

object

Show child attributes

meta_data

object

Free-form metadata persisted with the message. Returned on webhooks for correlation.

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.

DELETE contacts/{id}POST messages/mark-read

Get started

Contacts

WhatsApp

WhatsApp Flows

Templates

Channels

POST /v1/messages

Endpoint

Required scope

Headers

Envelope

Message types

Example requests

One body per type

Quoting a message

Response

202 Accepted

400 Bad Request

401 Unauthorized

403 Forbidden

404 Not Found

422 Unprocessable Entity

Operational notes

Authorizations

Body

Response

​Endpoint

​Required scope

​Headers

​Envelope

​Message types

​Example requests

​One body per type

​Quoting a message

​Response

​202 Accepted

​400 Bad Request

​401 Unauthorized

​403 Forbidden

​404 Not Found

​422 Unprocessable Entity

​Operational notes

Authorizations

Body

Response

Endpoint

Required scope

Headers

Envelope

Message types

Example requests

One body per type

Quoting a message

Response

202 Accepted

400 Bad Request

401 Unauthorized

403 Forbidden

404 Not Found

422 Unprocessable Entity

Operational notes