Send Session Messages

Session messages are free-form messages — no pre-approval required. You can send text, attachments, location pins, and interactive messages (list menus, reply buttons). The only constraint is WhatsApp’s 24-hour eligibility window.

The 24-hour rule

You can only send a session message if the recipient has messaged your business within the last 24 hours. If the window has closed, use Send template message to re-engage them instead.

Situation	Endpoint to use
Customer messaged you within 24 hours	`POST …/send/messages` (this endpoint)
No message from customer in over 24 hours	`POST …/send/whatsapp_templated_messages`
First-ever contact with a customer	`POST …/send/whatsapp_templated_messages`

Endpoint

POST https://api.connectly.ai/v1/businesses/{businessId}/send/messages

Rate limit: 200 requests/second. Exceeding this returns 429 Too Many Requests.

Request body

Field	Type	Required	Description
`recipient`	object	Yes	The customer to send to.
`recipient.id`	string	Yes	Customer’s WhatsApp number in E.164 format (e.g. `+16044441111`), or bare BSUID.
`recipient.channelType`	string	Yes	Set to `whatsapp`.
`recipient.name`	string	No	Customer’s display name.
`message`	object	Yes	The message content. Provide exactly one content type: `text`, `attachments`, `location`, `listMessage`, `replyButtonMessage`, `singleProductMessage`, or `multiProductMessage`.
`message.id`	string	No	Optional message identifier (e.g. `01FPW47QF69Y5JZH24605VAKQB`).
`message.text`	string	No	Plain text body. Required when sending `multiProductMessage`; optional for `singleProductMessage`; standalone text for all other messages.
`message.attachments`	array	No	Up to one attachment per message. Each item has `type` (`image`, `video`, `audio`, `document`), `url` (public URL), optional `caption`, and optional `filename` (document only).
`message.location`	object	No	A location pin. Fields: `latitude`, `longitude`, `name`, `address`.
`message.listMessage`	object	No	An interactive list message with sections and selectable rows. See WhatsApp docs.
`message.replyButtonMessage`	object	No	An interactive message with up to 3 quick-reply buttons. See WhatsApp docs.
`message.singleProductMessage`	object	No	Send a single product from your Meta catalog. Fields: `footer.text`, `catalogId`, `productItem.productRetailerId`. See WhatsApp docs.
`message.multiProductMessage`	object	No	Send multiple catalog products grouped into sections. Fields: `header`, `footer`, `catalogId`, `sections[].title`, `sections[].productItems[].productRetailerId`. See WhatsApp docs.
`message.referral`	object	No	Read-only. Populated on inbound messages triggered by a Click-to-WhatsApp ad. Fields: `sourceUrl`, `sourceId`, `sourceType`, `headline`, `body`, `mediaType`, `imageUrl`, `videoUrl`, `thumbnailUrl`, `ctwaClid`. See WhatsApp docs.
`message.isEcho`	boolean	No	Set to `true` if the message was sent from the business itself.
`sender`	object	No	Specifies which of your WhatsApp numbers to send from. Omit if you only have one number.
`sender.id`	string	No	Your WhatsApp sender number in E.164 format (e.g. `+14151111234`).
`sender.channelType`	string	No	Set to `whatsapp`.
`sender.name`	string	No	Display name for the sender.
`callbackData`	any	No	Up to 1024 bytes of JSON echoed back in webhook events for this message. See callbackData.
`campaignName`	string	No	Tags this message with a campaign name for analytics (e.g. `test_campaign_2022-03-12`).
`order`	object	No	Optional config to control event dispatching order.
`order.parentId`	string	No	ID of the parent message this event depends on.
`order.strategy`	string	No	Dispatch strategy. One of `independent` or `short_circuit`. Defaults to `strategy_unspecified`.

Response

{ "id": "01ARZ3NDEKTSV4RRFFQ69G5FAV" }

The id uniquely identifies the message. Use it to correlate delivery status webhook events.

callbackData

Set callbackData to any JSON value up to 1024 bytes. Connectly echoes it back in every webhook event tied to this message:

Delivery status events — sent, delivered, read, delivery_failed
Inbound replies that reference this message — quoted replies, button & list replies, reactions

Plain-text replies that don’t quote the original message do not include callbackData. Exceeding 1024 bytes returns a 400 error.

{
  "recipient": { "id": "+16044441111", "channelType": "whatsapp" },
  "message": { "text": "Your order is on its way!" },
  "callbackData": { "order_id": "12345" }
}

Examples

Plain text message

curl --request POST \
  --url https://api.connectly.ai/v1/businesses/<business_id>/send/messages \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <YOUR_KEY_HERE>' \
  --data '{
    "sender": { "id": "+14151111234", "channelType": "whatsapp" },
    "recipient": { "id": "+16044441111", "channelType": "whatsapp" },
    "message": { "text": "Hello, how can we help you today?" }
  }'

Image attachment

{
  "sender": { "id": "+14151111234", "channelType": "whatsapp" },
  "recipient": { "id": "+16044441111", "channelType": "whatsapp" },
  "message": {
    "attachments": [
      { "type": "image", "url": "https://example.com/image.jpg", "caption": "Check this out!" }
    ]
  }
}

Video attachment

{
  "sender": { "id": "+14151111234", "channelType": "whatsapp" },
  "recipient": { "id": "+16044441111", "channelType": "whatsapp" },
  "message": {
    "attachments": [
      { "type": "video", "url": "https://example.com/video.mp4", "caption": "Watch this!" }
    ]
  }
}

Audio attachment

{
  "sender": { "id": "+14151111234", "channelType": "whatsapp" },
  "recipient": { "id": "+16044441111", "channelType": "whatsapp" },
  "message": {
    "attachments": [
      { "type": "audio", "url": "https://example.com/audio.mp3" }
    ]
  }
}

Document attachment

{
  "sender": { "id": "+14151111234", "channelType": "whatsapp" },
  "recipient": { "id": "+16044441111", "channelType": "whatsapp" },
  "message": {
    "attachments": [
      {
        "type": "document",
        "url": "https://example.com/invoice.pdf",
        "caption": "Your invoice",
        "filename": "invoice.pdf"
      }
    ]
  }
}

Location message

{
  "sender": { "id": "+14151111234", "channelType": "whatsapp" },
  "recipient": { "id": "+16044441111", "channelType": "whatsapp" },
  "message": {
    "location": {
      "latitude": 37.7749,
      "longitude": -122.4194,
      "name": "Connectly HQ",
      "address": "123 Main St, San Francisco"
    }
  }
}

Interactive list message

Use listMessage to present a scrollable menu. See WhatsApp interactive list docs for full spec.

{
  "sender": { "id": "+14151111234", "channelType": "whatsapp" },
  "recipient": { "id": "+16044441111", "channelType": "whatsapp" },
  "message": {
    "listMessage": {
      "header": { "text": "How can we help?" },
      "footer": { "text": "Choose an option below." },
      "button": { "text": "Select" },
      "sections": [
        {
          "title": "Support",
          "rows": [
            { "id": "1", "text": "Track my order", "description": "Get your order status" },
            { "id": "2", "text": "Returns & refunds", "description": "Start a return" }
          ]
        },
        {
          "title": "Sales",
          "rows": [
            { "id": "3", "text": "Talk to sales", "description": "Speak with our team" }
          ]
        }
      ]
    }
  }
}

You can also use a media header instead of text. Both list and reply-button messages share the same header structure:

"header": {
  "attachment": {
    "type": "image",
    "url": "https://cdn.connectly.ai/your-image.png"
  }
}

For a document header with a filename:

"header": {
  "attachment": {
    "type": "document",
    "url": "https://example.com/menu.pdf",
    "filename": "menu.pdf"
  }
}

Interactive reply-button message

Use replyButtonMessage for up to three quick-reply buttons. See WhatsApp reply button docs for full spec.

{
  "sender": { "id": "+14151111234", "channelType": "whatsapp" },
  "recipient": { "id": "+16044441111", "channelType": "whatsapp" },
  "message": {
    "text": "Would you like to confirm your appointment?",
    "replyButtonMessage": {
      "header": { "text": "Appointment reminder" },
      "footer": { "text": "Tap a button to respond." },
      "buttons": [
        { "id": "confirm", "text": "Confirm ✓" },
        { "id": "reschedule", "text": "Reschedule" },
        { "id": "cancel", "text": "Cancel" }
      ]
    }
  }
}

Send from a specific number (multi-sender)

Include the sender object when your business has more than one WhatsApp number.

{
  "sender": { "id": "+14151111234", "channelType": "whatsapp" },
  "recipient": { "id": "+16044441111", "channelType": "whatsapp" },
  "message": { "text": "Hello from our support line!" }
}

Targeting by BSUID

To target a customer identified by a Business-Scoped User ID, set recipient.userId to the bare BSUID (e.g. US.13491208655302741918). See Business-scoped user IDs (BSUID) for full details.

Sending to phone-less (BSUID-only) customers is not yet available and currently returns a 400 error.

Error responses

Status	Meaning
`400`	Malformed body, session window expired, or `callbackData` exceeds 1024 bytes.
`401`	Missing or invalid `X-API-Key`.
`429`	Rate limit exceeded (200 req/s).
`500`	Internal server error.

See Error codes for the full list of error types and codes, including ERROR_CODE_MESSAGE_OUTSIDE_OF_ELIGIBILITY_WINDOW.

​The 24-hour rule

​Endpoint

​Request body

​Response

​callbackData

​Examples

​Targeting by BSUID

​Error responses

The 24-hour rule

Endpoint

Request body

Response

callbackData

Examples

Targeting by BSUID

Error responses