API reference

Messages

Send WhatsApp text, interactive, and media messages.

Messages are sent from a connected WhatsApp session.

Use your ChatKazi API key for message sends.

Send text message

POST /messages/text

Terminal

curl -X POST "$CHATKAZI_BASE_URL/messages/text" \
  -H "x-api-key: $CHATKAZI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "default",
    "to": "254712345678",
    "text": "Your order has been confirmed."
  }'

Body

Field	Type	Required	Notes
`sessionId`	string	No	Defaults to `default`.
`to`	string	Yes	International phone number without `+` or spaces.
`text`	string	Yes	Message body.

Response

{
  "message": "Message sent.",
  "data": {
    "key": {
      "remoteJid": "254712345678@s.whatsapp.net",
      "fromMe": true,
      "id": "..."
    }
  }
}

Send media message

POST /messages/media

Terminal

curl -X POST "$CHATKAZI_BASE_URL/messages/media" \
  -H "x-api-key: $CHATKAZI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "default",
    "to": "254712345678",
    "type": "image",
    "url": "https://example.com/invoice.png",
    "caption": "Your invoice is ready."
  }'

Body

Field	Type	Required	Notes
`sessionId`	string	No	Defaults to `default`.
`to`	string	Yes	International phone number without `+` or spaces.
`url`	string	Yes	Publicly reachable media URL.
`type`	string	No	`image`, `video`, `audio`, or `document`. Defaults to `image`.
`caption`	string	No	Caption for image, video, or document messages.
`mimetype`	string	No	Recommended for documents and custom file types.
`fileName`	string	No	Display name for document messages.

Send interactive message

POST /messages/interactive

Use interactive messages when the recipient should choose a known action instead of typing a free-form reply.

Terminal

curl -X POST "$CHATKAZI_BASE_URL/messages/interactive" \
  -H "x-api-key: $CHATKAZI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "default",
    "to": "254712345678",
    "text": "How can we help?",
    "footer": "ChatKazi Support",
    "actions": [
      {
        "type": "reply",
        "id": "track_order",
        "label": "Track order"
      },
      {
        "type": "url",
        "label": "Visit website",
        "url": "https://example.com"
      }
    ]
  }'

Body

Field	Type	Required	Notes
`sessionId`	string	No	Defaults to `default`.
`to`	string	Yes	International phone number or the exact `message.replyTo` value from a webhook.
`text`	string	Yes	Message body shown above the actions.
`title`	string	No	Optional message title.
`footer`	string	No	Optional text shown below the actions.
`actions`	array	Yes	One to ten interactive actions.

Action types

Type	Required fields	Behavior
`reply`	`id`, `label`	Sends the chosen ID back to your webhook.
`url`	`label`, `url`	Opens an HTTP or HTTPS URL. Optional `merchantUrl` is passed to WhatsApp as merchant metadata.
`copy`	`label`, `value`	Copies a value such as a coupon code.
`call`	`label`, `phoneNumber`	Opens the recipient's phone dialer.
`list`	`label`, `sections`	Opens a menu of selectable rows.
`catalog`	`businessPhoneNumber`	Experimental. Attempts to open the business catalog. Optional `label`.
`location_request`	`label`	Experimental. Requests the recipient's location.

Keep reply and list row IDs stable and meaningful. Your webhook receives the selected ID in message.interaction.id.

List menu example

List action

{
  "sessionId": "default",
  "to": "254712345678",
  "text": "Choose a service",
  "actions": [
    {
      "type": "list",
      "label": "View services",
      "sections": [
        {
          "title": "Services",
          "rows": [
            {
              "id": "delivery_updates",
              "title": "Delivery updates",
              "description": "Track an existing order"
            },
            {
              "id": "billing_support",
              "title": "Billing support"
            }
          ]
        }
      ]
    }
  ]
}

Interactive message availability and presentation can vary by WhatsApp client. Use reply action IDs, not button labels, as application commands.

Catalog and location-request actions use specialized WhatsApp native flows. WhatsApp may ignore them depending on the connected account, recipient client, region, or business configuration. A successful API response confirms that ChatKazi submitted the message, not that WhatsApp rendered the action.

catalog example:

Catalog action

{
  "type": "catalog",
  "label": "View catalog",
  "businessPhoneNumber": "254712345678"
}

location_request example:

Location request action

{
  "type": "location_request",
  "label": "Share location"
}

JavaScript example

send-order-confirmation.js

import { chatkazi } from './chatkazi.js'

export async function sendOrderConfirmation({ phone, orderNumber }) {
  return chatkazi('/messages/text', {
    method: 'POST',
    body: JSON.stringify({
      sessionId: 'default',
      to: phone,
      text: `Order ${orderNumber} has been confirmed. We will update you shortly.`
    })
  })
}

Delivery and usage

Successful message sends are counted in your usage. Failed sends are logged as errors so you can inspect them in the dashboard.

If the session is not connected, the API returns an error instead of silently queueing the message.

Edit this pageorReport an issue

Sessions

Manage WhatsApp connection sessions.

Webhooks

Receive inbound WhatsApp messages and verify webhook signatures.