> ## 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 Template Messages

> Send a pre-approved WhatsApp template to any customer, including those outside the 24-hour session window ✅

Template messages are pre-approved formats managed in your WhatsApp Manager (inside Facebook Business Manager). Because Meta approves them in advance, you can send them to any customer at any time — including first-time contacts and customers whose 24-hour session has expired.

<Info>
  Your template must be created and approved in [WhatsApp Manager](https://business.facebook.com) before you can reference it here. Contact the Connectly team if you need help getting a template approved.
</Info>

<Warning>
  Template messages can only be sent to **personal WhatsApp accounts** — not to WhatsApp API (business) accounts. When testing, use your personal WhatsApp number and make sure it has accepted all WhatsApp app and privacy updates.
</Warning>

## Endpoint

```text theme={null}
POST /v1/businesses/{businessId}/send/whatsapp_templated_messages
```

```json theme={null}
POST https://api.connectly.ai/v1/businesses/{businessId}/send/whatsapp_templated_messages
```

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

***

## Request body

| Field          | Type   | Required | Description                                                                                                                                       |
| -------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `number`       | string | Yes      | Recipient's WhatsApp number in E.164 format (e.g. `+16502223333`). To target a BSUID customer, use the prefixed form `bsuid:US.…`.                |
| `templateName` | string | Yes      | Exact name of the approved template in your WhatsApp Manager.                                                                                     |
| `language`     | string | Yes      | Language code for the template translation (e.g. `en`, `en_US`, `pt_BR`, `es`). The template must have an approved translation for this language. |
| `parameters`   | array  | No       | Variable substitution objects. See [Template parameters](#template-parameters) below.                                                             |
| `sender`       | string | No       | Your WhatsApp sender number in E.164 format. Only required when you have more than one WhatsApp number registered with Connectly.                 |
| `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 send with a campaign name for analytics.                                                                                                |

## Response

```json theme={null}
{ "id": "01ARZ3NDEKTSV4RRFFQ69G5FAV" }
```

The `id` uniquely identifies the message. Use it to correlate [delivery status webhook events](/message-api/webhook-api) (`sent`, `delivered`, `read`, `delivery_failed`).

***

## Template parameters

The `parameters` array substitutes variables in your template's header, body, and buttons. Each object has a `name` and `value`, plus an optional `filename` for document headers.

```json theme={null}
"parameters": [
  { "name": "header_document", "value": "https://example.com/invoice.pdf", "filename": "invoice.pdf" },
  { "name": "body_1", "value": "John" },
  { "name": "body_2", "value": "Order #98765" }
]
```

**Available `name` values:**

| Category | Name                        | Description                                                                                                              |
| -------- | --------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| Header   | `header_text`               | Substitutes a text variable in the template header.                                                                      |
| Header   | `header_image`              | Sets a header image — `value` must be a public image URL.                                                                |
| Header   | `header_document`           | Sets a header document — `value` must be a public document URL. Pair with `filename` to control the displayed file name. |
| Body     | `body_1` … `body_15`        | Substitutes the 1st through 15th variable in the template body, in order.                                                |
| Buttons  | `button_1_url_suffix`       | Appended to the base URL of button 1.                                                                                    |
| Buttons  | `button_2_url_suffix`       | Appended to the base URL of button 2.                                                                                    |
| Buttons  | `button_3_url_suffix`       | Appended to the base URL of button 3.                                                                                    |
| Carousel | `card.N.header.image`       | Image URL for carousel card N (zero-indexed).                                                                            |
| Carousel | `card.N.body.M`             | Body variable M of carousel card N (both zero-indexed).                                                                  |
| Carousel | `card.N.button.M.urlSuffix` | URL suffix for button M of carousel card N.                                                                              |

***

## 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}
{
  "number": "+16044441234",
  "templateName": "order_confirmation",
  "language": "en",
  "parameters": [{ "name": "body_1", "value": "John" }],
  "callbackData": { "order_id": "12345" }
}
```

***

## Examples

<AccordionGroup>
  <Accordion title="Text header + body variables">
    ```json theme={null}
    {
      "number": "+16044441234",
      "templateName": "my_template_name",
      "language": "en",
      "parameters": [
        { "name": "header_text", "value": "Hello" },
        { "name": "body_1", "value": "John" },
        { "name": "body_2", "value": "red" }
      ]
    }
    ```
  </Accordion>

  <Accordion title="Image header + body variables (Brazilian Portuguese)">
    ```json theme={null}
    {
      "number": "+16044441234",
      "templateName": "external_header_test2",
      "language": "pt_BR",
      "parameters": [
        { "name": "header_image", "value": "https://i.picsum.photos/id/695/200/300" },
        { "name": "body_1", "value": "Connectly.ai" },
        { "name": "body_2", "value": "John" },
        { "name": "body_3", "value": "a new party" },
        { "name": "body_4", "value": "McDonald's" },
        { "name": "body_5", "value": "celebrate" }
      ]
    }
    ```
  </Accordion>

  <Accordion title="Document header">
    ```json theme={null}
    {
      "number": "+16044441234",
      "templateName": "external_header_document",
      "language": "en",
      "parameters": [
        {
          "name": "header_document",
          "value": "https://example.com/invoice.pdf",
          "filename": "invoice.pdf"
        }
      ]
    }
    ```
  </Accordion>

  <Accordion title="Link button with URL suffix (Spanish)">
    The `value` is appended to the button's configured base URL — e.g. a base of `www.facebook.com/` becomes `www.facebook.com/connectlyai`.

    ```json theme={null}
    {
      "number": "+16044441234",
      "templateName": "external_link_button",
      "language": "es",
      "parameters": [
        { "name": "button_1_url_suffix", "value": "connectlyai" }
      ]
    }
    ```
  </Accordion>

  <Accordion title="Carousel template">
    Create the carousel template first using the [Template Management API](/business-management/template-management), then reference it here with per-card parameters.

    ```json theme={null}
    {
      "number": "+16044441234",
      "templateName": "carousel_demo_1",
      "language": "en_US",
      "parameters": [
        { "name": "card.0.header.image", "value": "https://example.com/card1.png" },
        { "name": "card.0.body.0", "value": "Summer Sale" },
        { "name": "card.0.button.0.urlSuffix", "value": "summer2024" },
        { "name": "card.1.header.image", "value": "https://example.com/card2.png" },
        { "name": "card.1.body.0", "value": "Up to 50% off" },
        { "name": "card.1.button.0.urlSuffix", "value": "sale50" }
      ]
    }
    ```

    <Note>
      To receive events when recipients tap carousel buttons, subscribe to the [Webhook API](/message-api/webhook-api).
    </Note>
  </Accordion>

  <Accordion title="Send from a specific number (multi-sender)">
    Include `sender` when your business has more than one WhatsApp number registered with Connectly.

    ```json theme={null}
    {
      "sender": "+14151111234",
      "number": "+16044441111",
      "templateName": "order_confirmation",
      "language": "en",
      "parameters": []
    }
    ```
  </Accordion>
</AccordionGroup>

***

## Template languages

Your template can have multiple approved language translations. Specify the correct code in the `language` field — the template must have an approved translation for the language you request. See [Meta's language list](https://developers.facebook.com/docs/whatsapp/api/messages/message-templates/#message-templates) for all supported codes.

| Language             | Code    |
| -------------------- | ------- |
| English              | `en`    |
| English (US)         | `en_US` |
| Brazilian Portuguese | `pt_BR` |
| Spanish              | `es`    |

***

## Targeting by BSUID

To target a customer identified by a Business-Scoped User ID, set `number` to the prefixed form `bsuid:US.…` (e.g. `bsuid:US.13491208655302741918`). See [Business-scoped user IDs (BSUID)](/message-api/bsuid) for full details.

<Warning>
  Sending to phone-less (BSUID-only) customers is not yet available and currently returns a `400` error. Authentication templates (one-tap, zero-tap, copy-code) cannot use BSUIDs — they require a phone number.
</Warning>

***

## Error responses

| Status | Meaning                                                                    |
| ------ | -------------------------------------------------------------------------- |
| `400`  | Malformed body, unapproved template, 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.