Skip to main content
POST
/
send-whatsapp-template
curl -X POST "https://api.magpipe.ai/functions/v1/send-whatsapp-template" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "d920763c-59d8-490e-ad69-b6a3295e23a8",
    "to": "+16045628647",
    "template_name": "upcoming_site_report",
    "components": [
      {
        "type": "body",
        "parameters": [
          { "type": "text", "text": "John" },
          { "type": "text", "text": "Site Super" },
          { "type": "text", "text": "March 20" },
          { "type": "text", "text": "2:00 PM" }
        ]
      }
    ]
  }'

{
  "success": true,
  "message_id": "wamid.HBgLMTYwNDU2Mjg2NDcVAgARGBJFNDc0NDJDNTA2QUY4OTRDNzYA"
}

​
Overview

Sends a pre-approved WhatsApp message template to a recipient using your agent’s connected WhatsApp Business number. Use this to initiate conversations outside the 24-hour messaging window.
Templates must be approved by Meta before use. Your template must comply with Meta’s template guidelines — templates that don’t conform will be rejected or recategorized. Manage your templates in Meta Business Manager → WhatsApp Manager → Message Templates.

​
Request

​
Headers

​
Authorization
string
required
Bearer token for authentication.
​
Content-Type
string
required
Must be application/json

​
Body Parameters

​
agent_id
string
required
The UUID of the agent whose connected WhatsApp number will send the message.Example: "d920763c-59d8-490e-ad69-b6a3295e23a8"
​
to
string
required
The recipient’s phone number in E.164 format.Example: "+16045628647"
​
template_name
string
required
The exact name of your approved Meta template. Must match a template approved in your WhatsApp Business account.See Meta’s template guidelines for categorization rules.Example: "upcoming_site_report"
​
language
string
The language code for the template. Defaults to en_US.Example: "en_US"
​
components
array
Optional array of template component objects for passing variable values. Required if your template has dynamic variables.Each component maps to a section of your template (body, header, or button). Parameters are positional — the first parameter fills {{1}}, the second fills {{2}}, and so on, in the order they appear in your approved template.Body variables example — for a template with Hello {{1}}, your report for {{2}} on {{3}} is ready:
[
  {
    "type": "body",
    "parameters": [
      { "type": "text", "text": "John" },
      { "type": "text", "text": "Site Super" },
      { "type": "text", "text": "March 20" }
    ]
  }
]
With header and body variables:
[
  {
    "type": "header",
    "parameters": [
      { "type": "text", "text": "Site Report" }
    ]
  },
  {
    "type": "body",
    "parameters": [
      { "type": "text", "text": "John" },
      { "type": "text", "text": "March 20" }
    ]
  }
]
With a URL button variable — buttons require sub_type and index (zero-based position of the button in the template):
[
  {
    "type": "body",
    "parameters": [
      { "type": "text", "text": "John" },
      { "type": "text", "text": "Site Super" },
      { "type": "text", "text": "March 20" },
      { "type": "text", "text": "2:00 PM" }
    ]
  },
  {
    "type": "button",
    "sub_type": "url",
    "index": "0",
    "parameters": [
      { "type": "text", "text": "report/a8f3k2m9" }
    ]
  }
]
See Meta’s template component docs for the full component structure including quick reply buttons, images, and documents.

​
Response

​
success
boolean
Whether the template was sent successfully.
​
message_id
string
The WhatsApp message ID returned by Meta.

​
Example Request

curl -X POST "https://api.magpipe.ai/functions/v1/send-whatsapp-template" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "d920763c-59d8-490e-ad69-b6a3295e23a8",
    "to": "+16045628647",
    "template_name": "upcoming_site_report",
    "components": [
      {
        "type": "body",
        "parameters": [
          { "type": "text", "text": "John" },
          { "type": "text", "text": "Site Super" },
          { "type": "text", "text": "March 20" },
          { "type": "text", "text": "2:00 PM" }
        ]
      }
    ]
  }'

​
Example Response

{
  "success": true,
  "message_id": "wamid.HBgLMTYwNDU2Mjg2NDcVAgARGBJFNDc0NDJDNTA2QUY4OTRDNzYA"
}

​
Error Responses

{
  "error": "agent_id, to, and template_name are required",
  "docs": "https://developers.facebook.com/docs/whatsapp/message-templates/guidelines"
}

{
  "error": "to must be a valid E.164 phone number"
}

{
  "error": "Unauthorized"
}

{
  "error": "No active WhatsApp account found for this agent"
}

{
  "error": "Failed to send template",
  "detail": "Meta API error details",
  "docs": "https://developers.facebook.com/docs/whatsapp/message-templates/guidelines"
}