Send a template message

🚀 What you’ll build

You’ll send your first WhatsApp template message using the Vambe API with the correct 3-step flow to gather required IDs.

Template messages allow you to reach customers outside the 24-hour window and send structured, pre-approved content for notifications and marketing.

Prerequisites

Before sending template messages, ensure you have:

✅ Connected WhatsApp Business API
✅ Created and approved templates
✅ Valid Vambe API key from developers page
✅ Customer phone numbers (must have opted in to receive messages)

Important: Only send template messages to customers who have explicitly opted in. Sending unsolicited messages violates WhatsApp’s policies and can result in account suspension.

Complete API Flow for Sending Templates

To send a template message, you need to make 3 API calls in sequence to get the required IDs:

Get Channel Information

First, retrieve your channel details:

curl -X GET \
  -H "x-api-key: YOUR_API_KEY" \
  https://api.vambe.me/api/public/channels/whatsapp

Sample Response:

{
  "phone_number": "56211111111",
  "client_id": "339e9487-8168-4e14-b1d8-3dce22d07760",
  "id": 1951,
  "name": "Test"
}

This endpoint retrieves the channel configuration by type. Use whatsapp, instagram, web-whatsapp, or playground as channel types. Save the phone_number and client_id for the template call.

Get Pipeline and Stage IDs

Retrieve your pipeline configuration to get stage IDs:

curl -X GET \
  -H "x-api-key: YOUR_API_KEY" \
  https://api.vambe.me/api/public/pipeline

Sample Response:

[
  {
    "id": "6c9804e2-0b8d-4df1-98f7-7e5be7f69ddb",
    "name": "Support Iris",
    "description": "Este embudo califica leads que ten",
    "stages": [
      {
        "id": "72ba8482-5c1c-4bed-8a6e-16fdb1495776",
        "name": "Inicial",
        "description": "En esta etapa la IA de Vambe i"
      },
      {
        "id": "3690b160-3c79-45f2-b88f-b640d96a36aa",
        "name": "Asistencia Humana",
        "description": "Si es que en cualquier punto d"
      }
    ]
  }
]

Save the stage ID where you want to send the message. You’ll need this stageId parameter for the template call.

Get Template ID

Find your approved template ID:

curl -X GET \
  -H "x-api-key: YOUR_API_KEY" \
  https://api.vambe.me/api/public/templates

Look for your template name and copy its ID for the final call.

Send the Template Message

Now send your template using the collected IDs:

curl -X POST \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contactName": "John Doe",
    "variables": ["John Doe", "ORD-12345", "89.99"],
    "meta_data": {},
    "stageId": "72ba8482-5c1c-4bed-8a6e-16fdb1495776",
    "toPhoneNumber": "+1234567890"
  }' \
  https://api.vambe.me/api/public/whatsapp/message/send/template/{templateId}

Required fields based on Vambe API:

contactName: Customer name
variables: Array of values for template variables (in order)
stageId: Stage ID from pipeline response
toPhoneNumber: Destination number
meta_data: Additional metadata object (can be empty)

Handle the Response

Process the API response to confirm delivery:

{
  "success": true,
  "message_id": "wamid.HBgMNTU1MjM...",
  "status": "sent",
  "timestamp": "2025-01-15T10:30:00Z"
}

Response codes:

201: Message sent successfully
400: Bad request (check required fields)
401: Unauthorized (verify API key)

Vambe Template Examples

Simple Template (No Variables)

curl -X POST \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contactName": "John Doe",
    "variables": [],
    "meta_data": {},
    "stageId": "72ba8482-5c1c-4bed-8a6e-16fdb1495776",
    "toPhoneNumber": "+1234567890"
  }' \
  https://api.vambe.me/api/public/whatsapp/message/send/template/welcome_message_id

Template with Variables

curl -X POST \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contactName": "Sarah Johnson",
    "variables": ["Sarah Johnson", "ORD-12345", "$159.99", "December 28, 2024"],
    "meta_data": {
      "order_id": "ORD-12345",
      "customer_type": "premium",
      "payment_method": "credit_card"
    },
    "stageId": "72ba8482-5c1c-4bed-8a6e-16fdb1495776",
    "toPhoneNumber": "+1234567890"
  }' \
  https://api.vambe.me/api/public/whatsapp/message/send/template/order_confirmation_id

Carousel Template

Carousel templates allow you to send multiple product cards with images, descriptions, and action buttons in a single message.

The from-phone-number query parameter specifies which WhatsApp Business number to send from. This is useful when you have multiple phone numbers connected to your account.

curl -X POST \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "variables": ["Customer Name", "Store Name"],
    "meta_data": {},
    "carouselVariables": [
      {
        "cardIndex": 0,
        "headerVariable": "https://example.com/product1.jpg",
        "bodyVariables": ["15000"],
        "buttonVariables": ["https://store.com/product1"]
      },
      {
        "cardIndex": 1,
        "headerVariable": "https://example.com/product2.jpg",
        "bodyVariables": ["16000"],
        "buttonVariables": ["https://store.com/product2"]
      },
      {
        "cardIndex": 2,
        "headerVariable": "https://example.com/product3.jpg",
        "bodyVariables": ["13000"],
        "buttonVariables": ["https://store.com/product3"]
      }
    ]
  }' \
  "https://api.vambe.me/api/public/whatsapp/message/send/+1234567890/template/{templateId}?from-phone-number=+1987654321"

Understanding Vambe Template Format

Based on the SendTemplateDto schema, here are the required and optional fields:

Field	Type	Required	Description
`contactName`	string	Optional	Customer’s name for personalization
`variables`	string[]	Required	Array of values for template variables in order
`meta_data`	object	Optional	Additional metadata (key-value pairs)
`stageId`	string	Optional	Pipeline stage ID where to send the message
`toPhoneNumber`	string	Optional	Destination phone number
`carouselVariables`	object[]	Optional	Variables for carousel template cards (see below)

Variable Order: The variables array must match the order of variables in your template. If your template has {{1}} for name and {{2}} for order number, then variables: ["John Doe", "ORD-123"].

Carousel Card Variables

When sending carousel templates, each card in the carouselVariables array has the following structure:

Field	Type	Required	Description
`cardIndex`	number	Required	Zero-based index of the carousel card (0, 1, 2, …)
`headerVariable`	string	Required	URL for the card’s header image or video
`bodyVariables`	string[]	Optional	Array of variables for the card’s body text
`buttonVariables`	string[]	Optional	Array of variables for the card’s buttons (e.g., URLs)

Carousel Templates allow you to send multiple cards with images/videos in a single message. Each card can have its own header media, body text variables, and button actions. Cards are indexed starting from 0.

Alternative Endpoint: Body-based V2

There’s an alternative endpoint that accepts all parameters in the request body, including the phone number and template name: Endpoint: POST /api/public/whatsapp/message/send

V2 Request Body Schema

Field	Type	Required	Description
`phone`	string	Required	Phone number to send the template to
`template_name`	string	Required	Name of the template to send
`contact_name`	string	Optional	Customer’s name for personalization
`variables`	string[]	Required	Array of values for template variables in order
`meta_data`	object	Optional	Additional metadata (key-value pairs)
`stage_id`	string	Optional	Pipeline stage ID where to send the message
`agent_id`	string	Optional	Agent ID to assign to the conversation
`from_phone_number`	string	Optional	Phone number to send the template from
`carouselVariables`	object[]	Optional	Variables for carousel template cards (same as above)

V2 Carousel Template Example

curl -X POST \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+1234567890",
    "template_name": "product_carousel",
    "contact_name": "John Doe",
    "variables": ["John Doe", "Store Name"],
    "meta_data": {},
    "from_phone_number": "+1987654321",
    "carouselVariables": [
      {
        "cardIndex": 0,
        "headerVariable": "https://example.com/product1.jpg",
        "bodyVariables": ["15000"],
        "buttonVariables": ["https://store.com/product1"]
      },
      {
        "cardIndex": 1,
        "headerVariable": "https://example.com/product2.jpg",
        "bodyVariables": ["16000"],
        "buttonVariables": ["https://store.com/product2"]
      }
    ]
  }' \
  https://api.vambe.me/api/public/whatsapp/message/send

The V2 endpoint uses template_name instead of templateId in the URL path, and uses snake_case for field names (contact_name, stage_id, from_phone_number) instead of camelCase.

Advanced Use Cases

Bulk Template Sending

Send templates to multiple customers efficiently:

const customers = [
  { name: "John Doe", phone: "+1234567890", orderId: "ORD-001" },
  { name: "Jane Smith", phone: "+1987654321", orderId: "ORD-002" },
  { name: "Bob Johnson", phone: "+1555123456", orderId: "ORD-003" }
];

const results = await Promise.allSettled(
customers.map(async (customer) => {
const response = await fetch(
'https://api.vambe.me/api/public/whatsapp/message/send/template/order_confirmation_id',
{
method: 'POST',
headers: {
'x-api-key': process.env.VAMBE_API_KEY,
'Content-Type': 'application/json'
},
body: JSON.stringify({
contactName: customer.name,
variables: [customer.name, customer.orderId],
meta_data: { order_id: customer.orderId },
stageId: '72ba8482-5c1c-4bed-8a6e-16fdb1495776',
toPhoneNumber: customer.phone
})
}
);
return { customer: customer.name, result: await response.json() };
})
);

console.log('Bulk send results:', results);

Error Handling

Common Error Responses

Template Not Found (404)

{
  "error": "Template not found",
  "code": "TEMPLATE_NOT_FOUND",
  "details": "Template ID 'invalid_template_id' does not exist or is not approved"
}

Solutions:

Verify template ID is correct
Check template approval status in Vambe dashboard
Ensure template exists for your account

Invalid Stage ID (400)

{
  "error": "Invalid stage ID",
  "code": "INVALID_STAGE_ID",
  "details": "Stage ID does not exist in your pipelines"
}

Solutions:

Check stage ID from pipeline API response
Verify stage belongs to your account
Ensure pipeline is active and configured

Invalid Phone Number (400)

{
  "error": "Invalid recipient",
  "code": "INVALID_PHONE_NUMBER",
  "details": "Phone number must include country code"
}

Solutions:

Include country code (e.g., +1 for US)
Validate phone number format
Ensure number is active on WhatsApp

Rate Limit Exceeded (429)

{
  "error": "Rate limit exceeded",
  "code": "RATE_LIMIT_EXCEEDED",
  "retry_after": 3600
}

Solutions:

Implement exponential backoff retry logic
Check your messaging tier limits
Spread messages over longer time periods

Robust Error Handling Example

async function sendVambeTemplate(contactName, variables, stageId, toPhoneNumber, templateId) {
  try {
    const response = await fetch(
      `https://api.vambe.me/api/public/whatsapp/message/send/template/${templateId}`,
      {
        method: 'POST',
        headers: {
          'x-api-key': process.env.VAMBE_API_KEY,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          contactName,
          variables,
          meta_data: {},
          stageId,
          toPhoneNumber
        })
      }
    );

    if (!response.ok) {
      const error = await response.json();
      throw new Error(`API Error: ${error.code} - ${error.details}`);
    }

    const result = await response.json();
    console.log('Message sent successfully:', result.message_id);
    return result;

  } catch (error) {
    console.error('Failed to send template message:', error.message);

    // Handle specific error cases
    if (error.message.includes('RATE_LIMIT_EXCEEDED')) {
      console.log('Rate limit hit, retrying in 1 hour...');
      // Implement retry logic
    } else if (error.message.includes('TEMPLATE_NOT_FOUND')) {
      console.log('Template needs to be created or approved');
    }

    throw error;
  }

}

// Usage with error handling
try {
await sendVambeTemplate(
"John Doe",
["John Doe", "ORD-12345"],
"72ba8482-5c1c-4bed-8a6e-16fdb1495776",
"+1234567890",
"order_confirmation_template_id"
);
} catch (error) {
console.error('Template message failed:', error);
}

Best Practices

Message Timing

Respect time zones - Send during business hours
Consider urgency - Use appropriate delivery timing
Batch wisely - Spread bulk sends over time
Avoid peak hours - Prevent rate limiting

Content Optimization

Personalize content - Use customer data effectively - Keep variables relevant - Don’t include unnecessary data - Test thoroughly - Verify all variable combinations - Monitor performance - Track delivery and engagement

Compliance

Verify opt-ins - Only message consenting customers - Honor opt-outs
Respect unsubscribe requests - Follow policies - Adhere to WhatsApp guidelines - Document consent - Keep records of permissions

Technical Excellence

Handle errors gracefully - Implement proper error handling
Use rate limiting - Respect API limits
Monitor delivery - Track message status
Log thoroughly - Maintain audit trails

Next Steps

Congratulations! You’ve successfully sent your first WhatsApp template message.

Now you can:

Automate with Pipelines

Integrate template messages into automated conversation flows

Track Performance

Monitor delivery rates, engagement, and customer responses

Webhook Integration

Set up real-time notifications for message status updates

Channel Management

Connect additional channels for multi-platform messaging

Remember: Template messages are powerful tools for customer communication. Use them responsibly and always prioritize customer value and consent.

Getting started

WhatsApp Integration

WhatsApp QR

Webchat Integration

Ecommerce

Advanced Integration

Send a template message

🚀 What you’ll build

Prerequisites

Complete API Flow for Sending Templates

Vambe Template Examples

Simple Template (No Variables)

Template with Variables

Carousel Template

Understanding Vambe Template Format

Carousel Card Variables

Alternative Endpoint: Body-based V2

V2 Request Body Schema

V2 Carousel Template Example

Advanced Use Cases

Bulk Template Sending

Error Handling

Common Error Responses

Robust Error Handling Example

Best Practices

Message Timing

Content Optimization

Compliance

Technical Excellence

Next Steps

Automate with Pipelines

Track Performance

Webhook Integration

Channel Management

Getting started

WhatsApp Integration

WhatsApp QR

Webchat Integration

Ecommerce

Advanced Integration

​🚀 What you’ll build

​Prerequisites

​Complete API Flow for Sending Templates

​Vambe Template Examples

​Simple Template (No Variables)

​Template with Variables

​Carousel Template

​Understanding Vambe Template Format

​Carousel Card Variables

​Alternative Endpoint: Body-based V2

​V2 Request Body Schema

​V2 Carousel Template Example

​Advanced Use Cases

​Bulk Template Sending

​Error Handling

​Common Error Responses

​Robust Error Handling Example

​Best Practices

Message Timing

Content Optimization

Compliance

Technical Excellence

​Next Steps

Automate with Pipelines

Track Performance

Webhook Integration

Channel Management

🚀 What you’ll build

Prerequisites

Complete API Flow for Sending Templates

Vambe Template Examples

Simple Template (No Variables)

Template with Variables

Carousel Template

Understanding Vambe Template Format

Carousel Card Variables

Alternative Endpoint: Body-based V2

V2 Request Body Schema

V2 Carousel Template Example

Advanced Use Cases

Bulk Template Sending

Error Handling

Common Error Responses

Robust Error Handling Example

Best Practices

Next Steps