Ctrl K

API Reference

Send Template Message

Send a WhatsApp message using an approved template

Updated 24 Mar 2026

On this page

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.

This endpoint is rate-limited to 5 requests per second per user.

Request Body

sender_idintegerrequired

The ID of the WhatsApp sender to send from (obtained from the Get Senders endpoint)

template_idintegerrequired

The ID of the message template to use (obtained from the Get Templates endpoint)

recipient_phonestringrequired

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

recipient_namestring

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

variablesobject

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.

1string

  Value for the first template variable

2string

  Value for the second template variable

Response Fields

successboolean

Whether the message was sent successfully

conversation_idinteger

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

message_idinteger

The ID of the conversation message record

whatsapp_message_idinteger

The ID of the WhatsApp message record

message_sidstring

The Twilio message SID for tracking delivery

statusstring

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

Error Responses

402 Insufficient Balance

successboolean

false

errorstring

Insufficient balance. Please top up your account.

error_codestring

INSUFFICIENT_BALANCE

404 Not Found

successboolean

false

errorstring

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

error_codestring

SENDER_NOT_FOUND or TEMPLATE_NOT_FOUND

422 Unprocessable Entity

successboolean

false

errorstring

Detailed error message

error_codestring

  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`

curl -X POST "https://app.voxlink.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"
    }
  }'

curl -X POST "https://app.voxlink.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"
  }'

const response = await fetch(
  'https://app.voxlink.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);

import requests

response = requests.post(
    'https://app.voxlink.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())

{
  "success": true,
  "conversation_id": 1234,
  "message_id": 567,
  "whatsapp_message_id": 890,
  "message_sid": "SMxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "status": "queued"
}

{
  "success": false,
  "error": "Insufficient balance. Please top up your account.",
  "error_code": "INSUFFICIENT_BALANCE"
}

{
  "success": false,
  "error": "Sender not found or does not belong to you",
  "error_code": "SENDER_NOT_FOUND"
}

{
  "success": false,
  "error": "Template not found or does not belong to this sender",
  "error_code": "TEMPLATE_NOT_FOUND"
}

{
  "success": false,
  "error": "Template is not approved. Current status: pending",
  "error_code": "TEMPLATE_NOT_APPROVED"
}

{
  "success": false,
  "error": "Invalid phone number format. Use E.164 format (e.g., +14155551234).",
  "error_code": "INVALID_PHONE"
}

{
  "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 (credits for tenant users, minutes for direct users).
After sending a template message, a 24-hour messaging window opens. During this window, you can send freeform messages 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.