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

# Send Template Message

> Send a WhatsApp message using an approved template

This endpoint sends a WhatsApp message using a pre-approved template. Template messages are required when initiating a conversation with a user for the first time or when messaging outside the 24-hour messaging window.

> [!NOTE]
>
> This endpoint is rate-limited to **5 requests per second** per user.

### Request Body

**sender\_id** `integer` *required*

The ID of the WhatsApp sender to send from (obtained from the [Get Senders](https://docs.lacy.ai/api-reference/whatsapp/get-senders.md) endpoint)

**template\_id** `integer` *required*

The ID of the message template to use (obtained from the [Get Templates](https://docs.lacy.ai/api-reference/whatsapp/get-templates.md) endpoint)

**recipient\_phone** `string` *required*

The recipient's phone number in international format (e.g., `+1234567890`)

**recipient\_name** `string`

The recipient's name, max 255 characters (used for conversation tracking and CRM purposes)

**variables** `object`

Key-value pairs for template variables. Keys should match the variable names from the template. If the template has variables `{{1}}`, `{{2}}`, etc., provide them as `{"1": "value1", "2": "value2"}` or using the named keys from the template's `variables` array.

**Example variables**

**1** `string`

Value for the first template variable

**2** `string`

Value for the second template variable

### Response Fields

**success** `boolean`

Whether the message was sent successfully

**conversation\_id** `integer`

The ID of the conversation (new or existing) associated with this message

**message\_id** `integer`

The ID of the conversation message record

**whatsapp\_message\_id** `integer`

The ID of the WhatsApp message record

**message\_sid** `string`

The Twilio message SID for tracking delivery

**status** `string`

The initial message delivery status (e.g., `queued`, `sent`)

### Error Responses

**402 Insufficient Balance**

**Error Response**

**success** `boolean`

`false`

**error** `string`

`Insufficient balance. Please top up your account.`

**error\_code** `string`

`INSUFFICIENT_BALANCE`

**404 Not Found**

**Error Response**

**success** `boolean`

`false`

**error** `string`

`Sender not found or does not belong to you` or `Template not found or does not belong to this sender`

**error\_code** `string`

`SENDER_NOT_FOUND` or `TEMPLATE_NOT_FOUND`

**422 Unprocessable Entity**

**Error Response**

**success** `boolean`

`false`

**error** `string`

Detailed error message

**error\_code** `string`

One of: `SENDER_OFFLINE`, `TEMPLATE_NOT_APPROVED`, `TEMPLATE_NOT_SYNCED`, `TEMPLATE_MISMATCH`, `NO_ASSISTANT_CONFIGURED`, `INVALID_PHONE`, `MESSAGING_LIMIT_UNAVAILABLE`, `VOICE_CALL_LIMIT_NOT_MET`, `TWILIO_ERROR_{code}`, `UNKNOWN_ERROR`

```bash cURL theme={null}
curl -X POST "https://app.lacy.ai/api/user/whatsapp/send" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sender_id": 12,
    "template_id": 45,
    "recipient_phone": "+1234567890",
    "recipient_name": "John Doe",
    "variables": {
      "1": "John",
      "2": "January 15, 2026",
      "3": "2:00 PM"
    }
  }'
```

```bash Template without variables theme={null}
curl -X POST "https://app.lacy.ai/api/user/whatsapp/send" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sender_id": 12,
    "template_id": 46,
    "recipient_phone": "+1234567890"
  }'
```

```javascript JavaScript theme={null}
const response = await fetch(
  'https://app.lacy.ai/api/user/whatsapp/send',
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      sender_id: 12,
      template_id: 45,
      recipient_phone: '+1234567890',
      recipient_name: 'John Doe',
      variables: {
        '1': 'John',
        '2': 'January 15, 2026',
        '3': '2:00 PM'
      }
    })
  }
);

const data = await response.json();
console.log(data);
```

```python Python theme={null}
import requests

response = requests.post(
    'https://app.lacy.ai/api/user/whatsapp/send',
    headers={
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    json={
        'sender_id': 12,
        'template_id': 45,
        'recipient_phone': '+1234567890',
        'recipient_name': 'John Doe',
        'variables': {
            '1': 'John',
            '2': 'January 15, 2026',
            '3': '2:00 PM'
        }
    }
)

print(response.json())
```

```json 200 Success theme={null}
{
  "success": true,
  "conversation_id": 1234,
  "message_id": 567,
  "whatsapp_message_id": 890,
  "message_sid": "SMxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "status": "queued"
}
```

```json 402 Insufficient Balance theme={null}
{
  "success": false,
  "error": "Insufficient balance. Please top up your account.",
  "error_code": "INSUFFICIENT_BALANCE"
}
```

```json 404 Sender Not Found theme={null}
{
  "success": false,
  "error": "Sender not found or does not belong to you",
  "error_code": "SENDER_NOT_FOUND"
}
```

```json 404 Template Not Found theme={null}
{
  "success": false,
  "error": "Template not found or does not belong to this sender",
  "error_code": "TEMPLATE_NOT_FOUND"
}
```

```json 422 Template Not Approved theme={null}
{
  "success": false,
  "error": "Template is not approved. Current status: pending",
  "error_code": "TEMPLATE_NOT_APPROVED"
}
```

```json 422 Invalid Phone theme={null}
{
  "success": false,
  "error": "Invalid phone number format. Use E.164 format (e.g., +14155551234).",
  "error_code": "INVALID_PHONE"
}
```

```json 422 Sender Offline theme={null}
{
  "success": false,
  "error": "Sender is not online. Current status: Offline",
  "error_code": "SENDER_OFFLINE"
}
```

### Notes

* Template messages must use **approved** templates. Templates with `pending` or `rejected` status will fail.
* The sender must be `online`. Offline senders cannot send messages.
* Message costs are automatically deducted from your account balance.
* After sending a template message, a 24-hour messaging window opens. During this window, you can send [freeform messages](https://docs.lacy.ai/api-reference/whatsapp/send-freeform.md) without needing a template.
* If a conversation already exists with the recipient, the message is added to the existing conversation.
* Rate limit: 5 requests per second per user.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.