> ## Documentation Index > Fetch the complete documentation index at: https://docs.connectly.ai/llms.txt > Use this file to discover all available pages before exploring further. # Send Session Messages > Send a free-form text, media, location, or interactive message within an active 24-hour WhatsApp session πŸ—ΊοΈ 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](/message-api/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 ```json theme={null} 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](https://developers.facebook.com/docs/whatsapp/guides/interactive-messages#list-messages). | | `message.replyButtonMessage` | object | No | An interactive message with up to 3 quick-reply buttons. See [WhatsApp docs](https://developers.facebook.com/docs/whatsapp/guides/interactive-messages#reply-buttons). | | `message.singleProductMessage` | object | No | Send a single product from your Meta catalog. Fields: `footer.text`, `catalogId`, `productItem.productRetailerId`. See [WhatsApp docs](https://developers.facebook.com/docs/whatsapp/cloud-api/guides/sell-products-and-services/share-products). | | `message.multiProductMessage` | object | No | Send multiple catalog products grouped into sections. Fields: `header`, `footer`, `catalogId`, `sections[].title`, `sections[].productItems[].productRetailerId`. See [WhatsApp docs](https://developers.facebook.com/docs/whatsapp/cloud-api/guides/sell-products-and-services/share-products). | | `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](https://developers.facebook.com/docs/whatsapp/cloud-api/webhooks/payload-examples). | | `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](#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 ```json theme={null} { "id": "01ARZ3NDEKTSV4RRFFQ69G5FAV" } ``` The `id` uniquely identifies the message. Use it to correlate [delivery status webhook events](/message-api/webhook-api). *** ## 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. ```json theme={null} { "recipient": { "id": "+16044441111", "channelType": "whatsapp" }, "message": { "text": "Your order is on its way!" }, "callbackData": { "order_id": "12345" } } ``` *** ## Examples ```bash cURL theme={null} curl --request POST \ --url https://api.connectly.ai/v1/businesses//send/messages \ --header 'Content-Type: application/json' \ --header 'X-API-Key: ' \ --data '{ "sender": { "id": "+14151111234", "channelType": "whatsapp" }, "recipient": { "id": "+16044441111", "channelType": "whatsapp" }, "message": { "text": "Hello, how can we help you today?" } }' ``` ```python Python theme={null} import requests payload = { "sender": { "id": "+14151111234", "channelType": "whatsapp" }, "recipient": { "id": "+16044441111", "channelType": "whatsapp" }, "message": { "text": "Hello, how can we help you today?" } } response = requests.post( "https://api.connectly.ai/v1/businesses//send/messages", headers={ "Content-Type": "application/json", "X-API-Key": "" }, json=payload ) print(response.json()) ``` ```json theme={null} { "sender": { "id": "+14151111234", "channelType": "whatsapp" }, "recipient": { "id": "+16044441111", "channelType": "whatsapp" }, "message": { "attachments": [ { "type": "image", "url": "https://example.com/image.jpg", "caption": "Check this out!" } ] } } ``` ```json theme={null} { "sender": { "id": "+14151111234", "channelType": "whatsapp" }, "recipient": { "id": "+16044441111", "channelType": "whatsapp" }, "message": { "attachments": [ { "type": "video", "url": "https://example.com/video.mp4", "caption": "Watch this!" } ] } } ``` ```json theme={null} { "sender": { "id": "+14151111234", "channelType": "whatsapp" }, "recipient": { "id": "+16044441111", "channelType": "whatsapp" }, "message": { "attachments": [ { "type": "audio", "url": "https://example.com/audio.mp3" } ] } } ``` ```json theme={null} { "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" } ] } } ``` ```json theme={null} { "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" } } } ``` Use `listMessage` to present a scrollable menu. See [WhatsApp interactive list docs](https://developers.facebook.com/docs/whatsapp/guides/interactive-messages#list-messages) for full spec. ```json theme={null} { "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: ```json theme={null} "header": { "attachment": { "type": "image", "url": "https://cdn.connectly.ai/your-image.png" } } ``` For a document header with a filename: ```json theme={null} "header": { "attachment": { "type": "document", "url": "https://example.com/menu.pdf", "filename": "menu.pdf" } } ``` Use `replyButtonMessage` for up to three quick-reply buttons. See [WhatsApp reply button docs](https://developers.facebook.com/docs/whatsapp/guides/interactive-messages#reply-buttons) for full spec. ```json theme={null} { "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" } ] } } } ``` Include the `sender` object when your business has more than one WhatsApp number. ```json theme={null} { "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)](/message-api/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](/message-api/error-codes) for the full list of error types and codes, including `ERROR_CODE_MESSAGE_OUTSIDE_OF_ELIGIBILITY_WINDOW`.