> For the complete documentation index, see [llms.txt](https://docs.connectly.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.connectly.ai/message-api/message-service-api/messageservice/send-session-message.md).

# Send session message

{% hint style="danger" %}
If you are trying to send a WhatsApp message and the number you are messaging has not messaged you within the last 24 hours, you will need to send a pre approved template message. See [here](/message-api/message-service-api/messageservice/send-template-message.md) for details.
{% endhint %}

{% openapi src="/files/Co61zoF5m8TmMptYkJKy" path="/v1/businesses/{businessId}/send/messages" method="post" %}
[service.swagger.json](https://1088238995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTPnSja6RkBiRLGAbuXVJ%2Fuploads%2FV9qAvavxfsFRbf0C65yA%2Fservice.swagger.json?alt=media\&token=018c17a7-d49f-43b0-b9b2-32ac6fa18564)
{% endopenapi %}

{% hint style="info" %}
**Targeting a customer by BSUID** — set `recipient.userId` to the customer's bare BSUID (e.g. `US.13491208655302741918`) instead of a phone number. Sending to phone-less (BSUID-only) customers is not available yet and currently returns a `400`. See Business-scoped user IDs (BSUID).
{% endhint %}

## 24 hour WhatsApp restriction

If the recipient has not initiated the conversation first within the last 24 hours you CAN NOT send the messages to them. In this case, you MUST use templated message API `/v1/businesses/{businessId}/send/whatsapp_templated_messages`.

* Generally, you use `/v1/businesses/{businessId}/send/messages` to reply to the customers who already messaged you first.
* You use `/v1/businesses/{businessId}/send/whatsapp_templated_messages` to initiate with the customer first.

## Select the WhatsApp number you want to send from

The endpoint supports an optional sender field in the body. If you have multiple WhatsApp phone numbers with Connectly you can choose which one you want to send the message from. The payload needs to contain the optional `sender` object specifying the phone number in the `id` section and `channelType` as `whatsapp`:

```javascript
{
  "sender": {
    "id": "+14151111234",
    "channelType": "whatsapp"
  },
  "recipient": {
    "id": "+16044441111",
    "channelType": "whatsapp"
  },
  "message": {
    "text": "Hello, this is a text message!"
  }
}
```

### Echo custom data back with `callbackData`

The endpoint supports an optional `callbackData` field. Set it to any JSON value (object, array, string, number) up to **1024 bytes**, and Connectly echoes it back at the top level of every webhook event tied to this message:

* **Delivery status** events — `sent`, `delivered`, `read`, and `delivery_failed`.
* **Inbound replies** that reference this message — quoted text/media replies, interactive button & list replies, and reactions.

Use it to correlate webhook events back to your own records (order id, ticket id, etc.) without keeping a separate mapping.

{% hint style="info" %}
Plain-text replies that don't quote the original message do **not** include `callbackData` — WhatsApp gives no server-side signal linking them. Exceeding 1024 bytes returns a `400` error.
{% endhint %}

```javascript
{
  "sender": {
    "id": "+14151111234",
    "channelType": "whatsapp"
  },
  "recipient": {
    "id": "+16044441111",
    "channelType": "whatsapp"
  },
  "message": {
    "text": "Hello, this is a text message!"
  },
  "callbackData": {
    "order_id": "12345"
  }
}
```

### Send a message with an attachment

You can include an attachment to the message. Currently, only a single attachment is supported.

**Image Attachment Message**

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

**Video Attachment Message**

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

**Audio Attachment Message**

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

```

**Document Attachment Message**

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

### Send l**ocation message**

![](/files/mgyls5H0zya8fZTDvMqm)

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

```

### Send interactive list message

Use `list_message` to send a WhatsApp interactive list message. For more information, see [WhatsApp documentation](https://developers.facebook.com/docs/whatsapp/guides/interactive-messages#list-messages).

```javascript
{
  "sender": {
    "id": "+14151111234",
    "channelType": "whatsapp"
  },
  "recipient": {
    "id": "+16044441111",
    "channelType": "whatsapp"
  },
  "message": {
    "listMessage": {
      "header": {
        "text": "Check out this list of items!"
      },
      "footer": {
        "text": "Choose an option from the list."
      },
      "button": {
        "text": "Select"
      },
      "sections": [
        {
          "title": "Section 1",
          "rows": [
            {
              "id": "1",
              "text": "Item 1",
              "description": "Description for Item 1"
            },
            {
              "id": "2",
              "text": "Item 2",
              "description": "Description for Item 2"
            }
          ]
        },
        {
          "title": "Section 2",
          "rows": [
            {
              "id": "3",
              "text": "Item 3",
              "description": "Description for Item 3"
            }
          ]
        }
      ]
    }
  }
}

```

### Send interactive reply buttons message

Use `reply_button_message` to send interactive reply button message. For more information, see [WhatsApp documentation](https://developers.facebook.com/docs/whatsapp/guides/interactive-messages#reply-buttons).

```javascript
{
  "sender": {
    "id": "+14151111234",
    "channelType": "whatsapp"
  },
  "recipient": {
    "id": "+16044441111",
    "channelType": "whatsapp"
  },
  "message": {
    "text": "This is a reply button message",
    "replyButtonMessage": {
      "header": {
        "text": "Header"
      },
      "footer": {
        "text": "Footer"
      },
      "buttons": [
        {
          "id": "b1",
          "text": "Button 1"
        },
        {
          "id": "b2",
          "text": "Button 2"
        },
        {
          "id": "b3",
          "text": "Button 3"
        }
      ]
    }
  }
}
```

### Header Media

Both list and quick reply messages use the same header parameter structure. Here is an example of an image header:

```
"header": {
    "attachment": {
        "type": "image",
        "url": "https://cdn.connectly.ai/26fa/26fa1308-d328-41c9-a6a1-d5f4225a3768",
    }
},
```

This is an example of a document header with a filename:

```
"header": {
    "attachment": {
        "type": "document",
        "url": "https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf",
        "filename": "feeeelsss"
    }
},
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.connectly.ai/message-api/message-service-api/messageservice/send-session-message.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.