> ## Documentation Index
> Fetch the complete documentation index at: https://docs.beem.africa/llms.txt
> Use this file to discover all available pages before exploring further.

# Send template message

> Send approved WhatsApp templates with placeholders, media, and multiple recipients.

After a template has been approved, it can be sent using the **Send Template Message** endpoint.

This endpoint supports:

* Pre-approved WhatsApp templates
* Dynamic placeholders
* Images
* Videos
* Documents
* Interactive buttons
* Multiple recipients

<Info>
  Only templates approved by WhatsApp can be sent.
</Info>

### Sending workflow

```text theme={null}
Approved Template
        │
        ▼
Call Send Template API
        │
        ▼
Message Accepted
        │
        ▼
Delivered to Recipient
        │
        ▼
Delivery Reports Generated
```

***

### Personalize messages

Templates may contain placeholders such as:

```text theme={null}
Hello {{1}},

Your order {{2}} has been shipped.
```

Provide values using the **params** array.

| Placeholder | Example Value |
| ----------- | ------------- |
| `{{1}}`     | John Doe      |
| `{{2}}`     | ORD-10452     |

Values are substituted automatically in the order they appear.

***

### Template request structure

The request body differs slightly depending on the type of WhatsApp template being sent.

* **Marketing** and **Utility** templates support media attachments in addition to dynamic placeholders.
* **Authentication** templates are designed for one-time password (OTP) delivery and support only plain text verification messages.

<Tabs>
  <Tab title="Marketing / Utility">
    ```json theme={null}
    {
      "from_addr": "2557******45",
      "destination_addr": [
        {
          "phoneNumber": "2547******06",
          "params": [
            "TestParam1"
          ]
        },
        {
          "phoneNumber": "2547*****279",
          "params": [
            "TestParam1"
          ]
        }
      ],
      "channel": "whatsapp",
      "content": {
        "mediaUrl": "https://example.com/image.jpg"
      },
      "messageTemplateData": {
        "id": 1024
      }
    }
    ```

    <Info>
      Include `content.mediaUrl` only when your approved template contains an image, video, or document.
    </Info>
  </Tab>

  <Tab title="Authentication">
    ```json theme={null}
    {
      "from_addr": "2557******45",
      "destination_addr": [
        {
          "phoneNumber": "2547******06",
          "params": [
            "123456"
          ]
        }
      ],
      "channel": "whatsapp",
      "messageTemplateData": {
        "id": 1024
      }
    }
    ```

    <Info>
      Authentication templates only support plain text verification messages. Media, URLs, emojis, and promotional content are not supported.
    </Info>
  </Tab>
</Tabs>

### Request body fields

| Field                    | Description                                                                |
| ------------------------ | -------------------------------------------------------------------------- |
| `from_addr`              | WhatsApp-enabled sender configured on your Beem account.                   |
| `destination_addr`       | Array of recipients and their placeholder values.                          |
| `phoneNumber`            | Recipient phone number in international format.                            |
| `params`                 | Values used to replace placeholders such as `{{1}}`, `{{2}}`, and `{{3}}`. |
| `channel`                | Messaging channel. This value should always be `whatsapp`.                 |
| `content.mediaUrl`       | Public URL of the media attachment. Only required for media templates.     |
| `messageTemplateData.id` | Identifier of the approved WhatsApp template to send.                      |

<Info>
  Each object inside `destination_addr` can contain different placeholder values, allowing you to personalize the same template for multiple recipients in a single API request.
</Info>

***

### Multiple recipients

The `destination_addr` field accepts an array of recipients.

Each recipient includes:

* Phone number
* Placeholder values (`params`)

This allows one API request to deliver personalized messages to many recipients.

<Info>
  Each recipient can receive different placeholder values.
</Info>

***

### Media templates

Templates may include media such as:

* Images
* Videos
* PDF documents
* Other supported attachments

Provide the media using:

```text theme={null}
content.mediaUrl
```

The media URL must be publicly accessible.

***

### Interactive templates

Depending on the approved template, messages may include:

* Call-to-action buttons
* Quick Reply buttons
* URL buttons

These components are configured during template creation.

***

### API response

After submitting a template message, the API returns details including:

<CardGroup cols={2}>
  <Card title="Delivery Summary">
    * Valid recipients
    * Invalid recipients
    * Credits consumed
    * Processing status
  </Card>

  <Card title="Tracking Information">
    * Job ID
    * Campaign information
    * Request tracking details
  </Card>
</CardGroup>

<Info>
  The returned **jobId** can be used to track the message and correlate delivery report callbacks.
</Info>