Skip to main content

​
🚀 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:
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:
1

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.
2

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.
3

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.
4

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)
5

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

​
Understanding Vambe Template Format

Based on the SendTemplateDto schema, here are the required and optional fields:
FieldTypeRequiredDescription
contactNamestringOptionalCustomer’s name for personalization
variablesstring[]RequiredArray of values for template variables in order
meta_dataobjectOptionalAdditional metadata (key-value pairs)
stageIdstringOptionalPipeline stage ID where to send the message
toPhoneNumberstringOptionalDestination phone number
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"].

​
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

{
  "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
{
  "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
{
  "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
{
  "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.