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.
​
metadata
object
Optional arbitrary JSON object (must be a plain object — arrays are ignored) stored against this message. When the recipient replies to the conversation this template opens, Magpipe echoes this metadata back on the inbound event so you can attribute the reply to your own record (e.g. a schedule, project, or ticket). Because the template is the conversation opener, attaching metadata here is the recommended way to tag the whole thread.Example: { "schedule_id": "sch_123", "project_id": "proj_456" }

​
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"
}