POST WhatsApp Template Message

This article contains essential information and usage guidelines for sending WhatsApp Template Messages through the BotPenguin API.

When should you use this?

Use this API when:

• You want to send approved WhatsApp template messages programmatically

• You need to trigger WhatsApp notifications from an external application

• You are trying to automate WhatsApp communication using approved Meta templates

---

What is the POST WhatsApp Template Message API?

The POST WhatsApp Template Message API allows you to send approved WhatsApp templates directly to users through BotPenguin.

This API supports:

• Template variables

• Media headers

• Agent assignment

• Conversation tagging

• Dynamic personalization

---

Benefits of the WhatsApp Template Message API

• 🚀 Automates WhatsApp outreach at scale

• 📩 Supports approved Meta template messages

• 🎯 Enables personalized communication using variables

• 🏷️ Allows automatic conversation tagging

• 👥 Supports assigning conversations to agents

---

Expected Outcome

After using this API:

• Approved WhatsApp templates will be delivered to users

• Template variables will be dynamically populated

• Conversations can be automatically tagged

• Chats can be assigned to specific agents

Tip: Ensure that the template is approved by Meta before attempting to send messages through this API.

---

API Endpoint

POST https://api.v7.botpenguin.com/whatsapp-automation/wa/send-template?apiKey={API_KEY}

---

Request Headers

Header	Value
authType	Key
Content-Type	application/json

---

Query Parameters

Parameter	Description
apiKey	Your BotPenguin API Key

---

Request Parameters

Parameter	Description
userName	Name of the recipient
wa_id	WhatsApp number including country code without + sign
templateId	Approved WhatsApp Template ID
assignTo	Email address of the assigned agent or custom user
params	Variables used inside the template
tags	Labels used to organize conversations

---

Template Variable Types

1. Name-Based Variables

Select "Name" while creating the template if your variables are named.

Example variables:

• customer_name

• lead_name

• industry

• meeting_day

For Name-based variables, every parameter must include a parameter_name field matching the exact variable name configured in the template.

Example Parameter

{
  "type": "text",
  "text": "John",
  "parameter_name": "customer_name"
}

Example Request Body

{
  "userName": "John Doe",
  "wa_id": "919876543210",
  "templateId": "TEMPLATE_ID",
  "params": [
    {
      "type": "body",
      "parameters": [
        {
          "type": "text",
          "text": "John Doe",
          "parameter_name": "customer_name"
        },
        {
          "type": "text",
          "text": "Healthcare",
          "parameter_name": "domain"
        },
        {
          "type": "text",
          "text": "Monday",
          "parameter_name": "meeting_day"
        }
      ]
    }
  ]
}

---

2. Number-Based Variables

Select "Number" while creating the template if your variables are positional.

Examples:

• Variable 1

• Variable 2

• Variable 3

For Number-based variables, parameter_name is not required.

Values are mapped based on their order within the template.

Example Request Body

{
  "params": [
    {
      "type": "header",
      "parameters": [
        {
          "type": "document",
          "document": {
            "link": "https://your-file-url.pdf"
          }
        }
      ]
    },
    {
      "type": "body",
      "parameters": [
        {
          "type": "text",
          "text": "Value 1"
        },
        {
          "type": "text",
          "text": "Value 2"
        }
      ]
    }
  ],
  "assignTo": "[e-mail]",
  "tags": ["tag1"]
}

---

Complete API Example

Request

curl --location --request POST 'https://api.v7.botpenguin.com/whatsapp-automation/wa/send-template?apiKey=YOUR_API_KEY' \
--header 'authType: Key' \
--header 'Content-Type: application/json' \
--data-raw '{
  "userName": "Test",
  "wa_id": "91885917XXXX",
  "templateId": "63dba1617XXXX52face07078",
  "params": [
    {
      "type": "header",
      "parameters": [
        {
          "type": "document",
          "document": {
            "link": "https://www.africau.edu/images/default/sample.pdf"
          }
        }
      ]
    },
    {
      "type": "body",
      "parameters": [
        {
          "type": "text",
          "text": "Abc"
        },
        {
          "type": "text",
          "text": "Def"
        },
        {
          "type": "text",
          "text": "Monday"
        }
      ]
    }
  ],
  "assignTo": "[e-mail]",
  "tags": [
    "test"
  ]
}'

---

Response Headers

Header	Details
X-Powered-By	Express
Vary	Origin
Access-Control-Allow-Credentials	true
_user	User ID
_bot	Bot ID
whatsAppId	WhatsApp Account ID
Content-Type	application/json; charset=utf-8
Content-Length	Response Length
Etag	Response ETag
Date	Response Date
Connection	keep-alive
Keep-Alive	timeout=5

---

Best Practices

💡 Always use approved WhatsApp templates before sending messages.

⚠️ Ensure the WhatsApp number includes the country code and excludes the "+" symbol.

🚀 Use meaningful tags to organize conversations efficiently.

🎯 Validate template variables before making the API request.

---

Troubleshooting

Message is not being delivered

Verify that:

• The template is approved by Meta.

• The recipient WhatsApp number is correct.

• The API key is valid and active.

• The WhatsApp channel is properly connected.

Invalid templateId error

Ensure the template ID exists and belongs to the connected WhatsApp Business Account.

Also verify that the template has not been deleted or rejected by Meta.

Variables are not populating correctly

For Name-based variables, verify that each parameter contains the correct parameter_name matching the template variable.

For Number-based variables, ensure values are passed in the exact order expected by the template.

Agent assignment is not working

Ensure the email address provided in assignTo belongs to an existing BotPenguin user or agent.

Authentication failed

Verify:

• The API key is correct.

• The API key has not expired.

• The apiKey query parameter is included in the endpoint URL.

---

FAQs

Does the template need Meta approval before sending?

Yes. Only approved WhatsApp templates can be sent using this API.

Can I send media inside template messages?

Yes. Media such as documents, images, and videos can be sent through template headers if configured in the template.

What is the difference between Name and Number variables?

Name variables use explicit variable names and require parameter_name. Number variables use positional mapping and do not require parameter_name.

Can I assign a conversation to an agent while sending the template?

Yes. Use the assignTo field and provide the email address of the desired agent.

Can I add tags to conversations?

Yes. Use the tags array to automatically apply labels to the conversation.

Is the country code required in wa_id?

Yes. The country code is mandatory and must be included without the "+" sign.

Can I send a template without variables?

Yes. For templates without variables, send an empty params array.

---

Support

If you still have questions for our team, write to us at [e-mail]. We'll get back to you within 48 hours.