WhatsApp API 🟡 BETA

Send and receive WhatsApp messages via the WhatsApp Business API integration.

Base URL

/api/whatsapp

Authentication

All endpoints require a valid session token via Authorization: Bearer <token> header. The webhook verification endpoint is exempt from authentication.

Overview

The WhatsApp API provides integration with the WhatsApp Business Platform (Meta). It enables:

  • Receiving inbound messages via webhooks
  • Sending outbound text messages
  • Monitoring connection status
  • Managing active WhatsApp sessions
  • Automatic session management with user lookup and creation
  • Audio message transcription (when available)

Feature Flag: This API is only available when the whatsapp feature is enabled at compile time (included in default features). The integration follows the same ChannelState dependency injection pattern as Telegram, Instagram, and Microsoft Teams channels.

Endpoints

Webhook (Receive Messages)

POST /api/whatsapp/webhook

Receive incoming WhatsApp messages and status updates from Meta. This endpoint is called by the WhatsApp Business Platform whenever a message is delivered or a status changes.

ParameterTypeRequiredDescription
bodyobjectYesWhatsApp webhook payload (see Meta documentation)

Request Body (Meta Verification):

{
  "object": "whatsapp_business_account",
  "entry": [...]
}

Response:

{
  "status": "ok"
}

Webhook Verification

GET /api/whatsapp/webhook

Verify the webhook URL with Meta during setup. Meta sends a GET request with hub.mode, hub.verify_token, and hub.challenge query parameters. The endpoint responds with the challenge value to confirm ownership.

Query Parameters:

ParameterTypeRequiredDescription
hub.modestringYesMust be "subscribe"
hub.verify_tokenstringYesVerification token configured in Meta
hub.challengestringYesChallenge string to echo back

Response:

ok

Send Message

POST /api/whatsapp/send

Send a text message to a WhatsApp user.

ParameterTypeRequiredDescription
tostringYesRecipient phone number (E.164 format, e.g., +5511999990000)
messagestringYesText message content

Request Body:

{
  "to": "+5511999990000",
  "message": "Hello from BotServer!"
}

Response:

{
  "status": "ok",
  "to": "+5511999990000"
}

Get Status

GET /api/whatsapp/status

Check the current status of the WhatsApp integration.

Response:

{
  "status": "ok"
}

Get Sessions

GET /api/whatsapp/sessions

List all active WhatsApp sessions.

Response:

{
  "sessions": []
}

Examples

Send a Message

curl -X POST http://localhost:8080/api/whatsapp/send \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+5511999990000",
    "message": "Your order #1234 has been shipped!"
  }'

Check WhatsApp Status

curl -X GET http://localhost:8080/api/whatsapp/status \
  -H "Authorization: Bearer $TOKEN"

List Active Sessions

curl -X GET http://localhost:8080/api/whatsapp/sessions \
  -H "Authorization: Bearer $TOKEN"

Test Webhook Verification

curl -X GET "http://localhost:8080/api/whatsapp/webhook?hub.mode=subscribe&hub.verify_token=MY_TOKEN&hub.challenge=CHALLENGE_VALUE"

Response Codes

CodeDescription
200Success
400Bad Request (invalid phone number or payload)
401Unauthorized
500Internal Server Error

Configuration

The WhatsApp integration requires the following credentials in the bot’s config.csv:

KeyDescription
whatsapp-api-keyAPI key from Meta Business Suite
whatsapp-verify-tokenCustom token for webhook verification
whatsapp-phone-number-idPhone Number ID from Meta
whatsapp-business-account-idBusiness Account ID from Meta

See Also