Template Messages

Convers8 allows you to send pre-approved message templates to your WhatsApp contacts. This guide covers how to use the template messaging API.

Authentication

All API requests must include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Base URL

https://waba-v1.convers8.africa

About WhatsApp Templates

WhatsApp Business API requires that all outbound notifications to customers use pre-approved message templates. These templates:

• Must be created and approved in the WhatsApp Business Manager
• Can contain variables that are replaced with dynamic content
• Can include text, media, and interactive components
• Are subject to WhatsApp's content policy guidelines

Sending Template Messages

Endpoint

POST /whatsapp/message/template

Request Body

Property	Type	Description
to	string	The recipient's phone number in international format
name	string	The recipient's name
templateName	string	The name of the approved template
language	string	The language code for the template (e.g., "en_US")
components	array	An array of component objects

Each component object has the following properties:

Property	Type	Description
type	string	The component type ("header", "body", or "footer")
parameters	array	An array of parameter objects

Each parameter object has the following properties:

Property	Type	Description
type	string	The parameter type ("text", "image", "document", "video", or "currency")
text	string	The text value (for "text" type)
image	object	The image object (for "image" type)
document	object	The document object (for "document" type)
video	object	The video object (for "video" type)
currency	object	The currency object (for "currency" type)

Example Request

{
  "to": "+1234567890",
  "name": "Customer Name",
  "templateName": "order_confirmation",
  "language": "en_US",
  "components": [
    {
      "type": "header",
      "parameters": [
        {
          "type": "text",
          "text": "Order Confirmation"
        }
      ]
    },
    {
      "type": "body",
      "parameters": [
        {
          "type": "text",
          "text": "123456"
        },
        {
          "type": "text",
          "text": "Convers8 Store"
        },
        {
          "type": "text",
          "text": "$99.99"
        }
      ]
    }
  ]
}

cURL Example

curl --request POST \
     --url https://waba-v1.convers8.africa/whatsapp/message/template \
     --header 'Authorization: Bearer YOUR_API_KEY' \
     --header 'Content-Type: application/json' \
     --data '{
       "to": "+1234567890",
       "name": "Customer Name",
       "templateName": "order_confirmation",
       "language": "en_US",
       "components": [
         {
           "type": "header",
           "parameters": [
             {
               "type": "text",
               "text": "Order Confirmation"
             }
           ]
         },
         {
           "type": "body",
           "parameters": [
             {
               "type": "text",
               "text": "123456"
             },
             {
               "type": "text",
               "text": "Convers8 Store"
             },
             {
               "type": "text",
               "text": "$99.99"
             }
           ]
         }
       ]
     }'

Template with Media Header

You can include media in the header of your template message.

Example with Image Header

{
  "to": "+1234567890",
  "name": "Customer Name",
  "templateName": "product_update",
  "language": "en_US",
  "components": [
    {
      "type": "header",
      "parameters": [
        {
          "type": "image",
          "image": {
            "url": "https://example.com/product.jpg"
          }
        }
      ]
    },
    {
      "type": "body",
      "parameters": [
        {
          "type": "text",
          "text": "New Product"
        },
        {
          "type": "text",
          "text": "Now available"
        }
      ]
    }
  ]
}

Example with Document Header

{
  "to": "+1234567890",
  "name": "Customer Name",
  "templateName": "invoice_template",
  "language": "en_US",
  "components": [
    {
      "type": "header",
      "parameters": [
        {
          "type": "document",
          "document": {
            "url": "https://example.com/invoice.pdf",
            "filename": "Invoice.pdf"
          }
        }
      ]
    },
    {
      "type": "body",
      "parameters": [
        {
          "type": "text",
          "text": "INV-12345"
        },
        {
          "type": "text",
          "text": "May 8, 2025"
        }
      ]
    }
  ]
}

Template with Buttons

You can include buttons in your template message.

Example with URL Button

{
  "to": "+1234567890",
  "name": "Customer Name",
  "templateName": "appointment_reminder",
  "language": "en_US",
  "components": [
    {
      "type": "body",
      "parameters": [
        {
          "type": "text",
          "text": "May 10, 2025"
        },
        {
          "type": "text",
          "text": "2:00 PM"
        }
      ]
    },
    {
      "type": "button",
      "sub_type": "url",
      "index": 0,
      "parameters": [
        {
          "type": "text",
          "text": "appointment123"
        }
      ]
    }
  ]
}

Example with Quick Reply Button

{
  "to": "+1234567890",
  "name": "Customer Name",
  "templateName": "feedback_request",
  "language": "en_US",
  "components": [
    {
      "type": "body",
      "parameters": [
        {
          "type": "text",
          "text": "Convers8 Support"
        }
      ]
    },
    {
      "type": "button",
      "sub_type": "quick_reply",
      "index": 0,
      "parameters": [
        {
          "type": "text",
          "text": "Yes, I'm satisfied"
        }
      ]
    }
  ]
}

Response Format

All API endpoints return a JSON response with the following structure:

{
  "success": true,
  "message": "Message sent successfully",
  "data": {
    "messageId": "wamid.abcdefghijklmnopqrstuvwxyz"
  }
}

Error Handling

In case of an error, the response will look like:

{
  "success": false,
  "message": "Error message",
  "error": {
    "code": "error_code",
    "details": "Error details"
  }
}

Common error codes include:

• invalid_parameter: One or more parameters in the request are invalid
• unauthorized: Invalid or missing API key
• rate_limit_exceeded: Too many requests in a short period
• template_not_found: The specified template does not exist
• template_not_approved: The specified template has not been approved
• parameter_mismatch: The provided parameters do not match the template's variables

Template Approval Process

1. Create Templates: Create your message templates in the WhatsApp Business Manager.
2. Submit for Approval: Submit your templates for approval by WhatsApp.
3. Wait for Approval: WhatsApp will review your templates and either approve or reject them.
4. Use Approved Templates: Once approved, you can use your templates with the Convers8 API.

Best Practices

1. Template Design: Design templates that are clear, concise, and provide value to your customers.
2. Variable Placement: Use variables strategically to personalize your messages.
3. Approval Guidelines: Follow WhatsApp's guidelines to increase the chances of template approval.
4. Testing: Test your templates with different parameter values to ensure they render correctly.
5. Error Handling: Implement proper error handling to manage API errors gracefully.