Send a message

Send a WhatsApp message to a recipient.

Use to for phone numbers. Use recipient for a BSUID or parent BSUID. If both are present, the phone number in to takes precedence.

Supports all WhatsApp message types:

• text: Plain text messages with optional URL preview
• image: Images with optional caption
• video: Videos with optional caption
• audio: Audio files
• document: Documents with optional caption and filename
• sticker: Stickers
• location: Location sharing
• contacts: Contact cards
• interactive: Interactive messages (buttons, lists, flows)
• template: Message templates
• reaction: Emoji reactions to messages

On a shared number, regular messages need Kapso to handle the conversation. Templates can always be sent.

POST /{phone_number_id}/messages

cURL

text_message

curl --request POST \ --url https://api.kapso.ai/meta/whatsapp/v24.0/{phone_number_id}/messages \ --header 'Content-Type: application/json' \ --header 'X-API-Key: <api-key>' \ --data ' { "messaging_product": "whatsapp", "recipient_type": "individual", "to": "15551234567", "type": "text", "text": { "body": "Hello! Your order #12345 has been shipped." } } '

200

success

{ "messaging_product": "whatsapp", "contacts": [ { "input": "15551234567", "wa_id": "15551234567" } ], "messages": [ { "id": "wamid.HBgNMTU1NTE0OTU5Nzg1FQIAERgSMDhGRjdBMDEyOTcxQzFFQkFBAA==" } ] }

Authorizations

ApiKeyAuthBearerAuth

X-API-Key · string · header · required

Project API key for authentication. This is the recommended authentication method.

Get your API key from the Kapso dashboard under Integrations > API keys.

Headers

X-Kapso-Take-Control · enum<string>

Shared numbers only. Set to true to send even though another app handles the conversation. Meta accepts it only when Kapso is your escalation app, and the send takes the conversation.

Available options: true

Path Parameters

phone_number_id · string · required

WhatsApp Business Phone Number ID

Body

application/json

Option 1

Option 2

Option 3

messaging_product · enum<string> · required

Always "whatsapp"

Available options: whatsapp

Example:

"whatsapp"

to · string · required

Recipient phone number or group ID. Use recipient for BSUID sends.

Example:

"15551234567"

type · enum<string> · required

Type of WhatsApp message

Available options: text, image, video, audio, document, sticker, location, contacts, interactive, template, reaction

recipient_type · enum<string> · default: individual

Recipient type. Use individual for 1:1, group for group messages. When group, to must be a Group ID obtained via the Groups API.

Available options: individual, group

biz_opaque_callback_data · string

Arbitrary string for tracking (echoed in webhooks)

Maximum string length: 512

messaging_account_id · string

Optional Messaging Account (WhatsApp Business Account) ID to send from. Must match the account the phone_number_id is configured with, otherwise the request is rejected with messaging_account_mismatch.

Example:

"102290129340398"

paid_messaging_account_id · string · deprecated

Deprecated alias for messaging_account_id. Ignored when messaging_account_id is also present.

Example:

"102290129340398"

recipient · string

Recipient BSUID or parent BSUID. If to is also present, the phone number in to takes precedence.

Example:

"US.13491208655302741918"

context · object

Reply context

Show child attributes

text · object

Show child attributes

image · object

Show child attributes

video · object

Show child attributes

audio · object

Show child attributes

document · object

Show child attributes

sticker · object

Show child attributes

location · object

Show child attributes

contacts · object[]

Show child attributes

interactive · object

Show child attributes

template · object

Show child attributes

reaction · object

Show child attributes

Response

200

application/json

Message sent successfully

messaging_product · enum<string> · required

Available options: whatsapp

Example:

"whatsapp"

contacts · object[] · required

Show child attributes

messages · object[] · required

Show child attributes