Send a Template - Popcorn Documentation

Use these endpoints to send a WhatsApp template message to a single recipient from an external system, for example an order confirmation from your ERP. Popcorn sends it from your connected WhatsApp number, creates or reopens the conversation in the Inbox, and optionally lets the AI agent handle the reply. There are two send endpoints. Use /api/v2/template/send for new integrations: it adds template lookup by name, async mode, your own tracking ID, and status webhooks. /template/send is the standard endpoint and stays supported.

Before you start

An API key from Settings → API Keys & Webhooks. See API Reference.
A template with Meta status Approved, created for a WhatsApp number that is still connected. Templates in any other status are rejected. See Templates.
The recipient’s number in international format with the country code and no +, for example 966501234567.

If the template body has placeholders and you omit variables, Popcorn sends the sample values entered when the template was created. Always pass variables for templates with placeholders.

List your templates

GET https://api.trypopcorn.ai/template returns every template in the workspace that has not been deleted, newest first, with the IDs you need for sending.

curl https://api.trypopcorn.ai/template \
  -H "POPCORN-API-KEY: sk-your_popcorn_api_key"

{
  "success": true,
  "data": {
    "templates": [
      {
        "id": "12345-abcd-6789-efgh",
        "metaTemplateName": "order_confirmation",
        "metaTemplateCategory": "UTILITY",
        "metaTemplateType": "TEXT",
        "metaTemplateLanguage": "en",
        "metaTemplateComponents": "[...]",
        "metaTemplateMetaId": "1234567890",
        "metaTemplateMetaStatus": "APPROVED",
        "createdAt": "2026-08-01T09:00:00.000Z",
        "updatedAt": "2026-08-02T09:00:00.000Z"
      }
    ],
    "count": 1
  }
}

Only templates whose metaTemplateMetaStatus is APPROVED can be sent. metaTemplateComponents is the template structure as a JSON string, including button texts, which you need for buttonValues.

V2 endpoint (recommended)

POST https://api.trypopcorn.ai/api/v2/template/send Authenticate with POPCORN-API-KEY: sk-... or Authorization: Bearer sk-.... Send Content-Type: application/json.

Parameter	Type	Required	Description
`templateId`	string	One of the two	The template ID from the list endpoint.
`templateName` + `templateLanguage`	string	One of the two	Look the template up by name and language code (`en`, `ar`, …). The name is matched case-insensitively, treating any non-alphanumeric character as `_`; the language must match exactly.
`toNumber`	string	Yes	Recipient number: 10 to 15 digits, optional leading `+`, spaces ignored.
`fromNumber`	string	No	One of your connected WhatsApp numbers (digits only). If omitted, or if the number is not connected to your workspace, the template’s own number is used. It must belong to the same WhatsApp Business account as the template.
`variables`	string[]	No	Values for the body placeholders `{{1}}`, `{{2}}`, … in order.
`buttonValues`	object	No	Values for URL buttons, keyed by the button’s text. See Dynamic URL buttons.
`autoPilot`	boolean	No	`true`: the AI agent bound to the sending number replies when the customer answers. `false` (default): the conversation is taken off Autopilot and placed in the Unassigned folder for your team.
`async`	boolean	No	`true`: respond `202` immediately and send in the background. Default `false`.
`messageId`	string	No	Your own ID for the message. Returned in the response and in every webhook. If omitted, Popcorn generates one in the form `msg-<timestamp>-<random>`.
`metadata`	object	No	Any JSON object, stored with the message’s tracking record. Not sent to the customer or included in webhooks.

curl -X POST https://api.trypopcorn.ai/api/v2/template/send \
  -H "POPCORN-API-KEY: sk-your_popcorn_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "templateName": "order_confirmation",
    "templateLanguage": "en",
    "toNumber": "966501234567",
    "variables": ["Sara", "ORD-4521"],
    "buttonValues": { "Track Order": "ORD-4521" },
    "autoPilot": true,
    "messageId": "order-4521-confirmation",
    "metadata": { "orderId": "ORD-4521" }
  }'

Responses

Synchronous (async omitted or false), HTTP 200, after WhatsApp accepted the message:

{
  "success": true,
  "messageId": "order-4521-confirmation",
  "conversationId": "3f2b7c1e-...",
  "timestamp": "2026-09-01T10:30:00.000Z"
}

Async (async: true), HTTP 202, before anything is sent:

{
  "success": true,
  "messageId": "order-4521-confirmation",
  "timestamp": "2026-09-01T10:30:00.000Z"
}

In async mode, validation, template lookup, and sender lookup still happen before the 202, so a wrong template or number is reported synchronously. A failure at WhatsApp itself is only logged: no error response and no webhook, because tracking starts once WhatsApp accepts the message. Use synchronous mode when you need to know that the send went through. If the request to WhatsApp fails at the network level (timeout, connection reset, DNS), Popcorn makes up to three attempts with a short backoff before giving up. Error responses from WhatsApp itself are not retried. This applies to both synchronous and async sends.

Errors

Errors use HTTP 400, 404, or 500 with this body:

{
  "success": false,
  "timestamp": "2026-09-01T10:30:00.000Z",
  "error": {
    "code": "TEMPLATE_NOT_FOUND",
    "message": "Template not found: order_confirmation",
    "details": { "templateName": "order_confirmation", "templateLanguage": "en" }
  }
}

HTTP	Code	When
`400`	`MISSING_REQUIRED_FIELD`	Neither `templateId` nor `templateName` + `templateLanguage`, or `toNumber` missing.
`400`	`INVALID_PHONE_NUMBER`	`toNumber` is not 10 to 15 digits.
`404`	`TEMPLATE_NOT_FOUND`	No template with that ID, or with that name and language, in your workspace.
`500`	`WABA_NOT_CONFIGURED`	`Template sender mapping is no longer active`: the number the template was created on has been disconnected.
`500`	`WHATSAPP_API_ERROR`	`message` says which: `Template is not approved for sending`, `No active Meta WhatsApp sender found` (including a `fromNumber` on a different WhatsApp Business account), `Customer cannot receive outbound messages` (the customer is blocked or unsubscribed), `This customer has no WhatsApp delivery identity. Ask them to message you first.`, or `Error sending template message` when WhatsApp rejected the request (for example a paused template or a variable count mismatch).
`500`	`INTERNAL_ERROR`	Unexpected failure. Retry later.

WhatsApp’s own error details are not returned in the response; check the message in the Inbox or your WhatsApp Business account for the reason. Authentication errors (401, 403) are listed in API Reference.

Health check

GET https://api.trypopcorn.ai/api/v2/template/health requires the same authentication and returns {"status": "ok", "service": "template-v2-api", "version": "2.0", "timestamp": "..."}. Use it to confirm a key works before going live.

Standard endpoint

POST https://api.trypopcorn.ai/template/send Authenticate with POPCORN-API-KEY only. This endpoint has no tracking, no webhooks, and no async mode.

Header	Required	Description
`POPCORN-API-KEY`	Yes	Your API key.
`Content-Type`	Yes	`application/json`.
`POPCORN-PHONE-NUMBER`	No	Send from a specific connected number (digits only). Omit to use the template’s own number. A number that is not connected to your workspace returns `403`.

Parameter	Type	Required	Description
`templateId`	string	Yes	The template ID from the list endpoint.
`recipientNumber`	string	Yes	Recipient number with country code, no `+`.
`variables`	string[]	No	Values for the body placeholders, in order.
`buttonValues`	object	No	Values for URL buttons, keyed by button text.
`enableAutoPilot`	boolean	No	Same as `autoPilot` above. Default `false`.

{
  "templateId": "12345-abcd-6789-efgh",
  "recipientNumber": "966501234567",
  "variables": ["Sara", "ORD-4521"],
  "buttonValues": { "Track Order": "ORD-4521" },
  "enableAutoPilot": true
}

Success returns HTTP 200 with {"success": true}. A send failure also returns HTTP 200, so check success rather than the status code:

{
  "success": false,
  "error": "Template is not approved for sending",
  "templateId": "12345-abcd-6789-efgh",
  "timestamp": "2026-09-01T10:30:00.000Z"
}

error is one of: Template not found, Template is not bound to an active Meta sender, Template sender mapping is no longer active, Template is not approved for sending, No active Meta WhatsApp sender found, Customer cannot receive outbound messages (blocked or unsubscribed), This customer has no WhatsApp delivery identity. Ask them to message you first., or Error sending template message when WhatsApp rejected the request. This endpoint does not retry network failures. A missing recipientNumber or templateId returns HTTP 400 with {"error": "Request error: recipientNumber is required"}.

The legacy form POST /template/{templateId}, with the template ID in the path and the same body without templateId, still works but is deprecated. Use /template/send or the V2 endpoint for new integrations.

Dynamic URL buttons

buttonValues fills URL buttons at send time. Keys must match the button text exactly as defined in the template.

Parameterized URL (the button URL contains a placeholder, for example https://example.com/track/{{1}}): pass only the value. {"Track Order": "ORD-4521"} produces https://example.com/track/ORD-4521. If you pass a full URL here, only its last path segment is used.
Static URL: pass a complete URL to replace it, for example {"Visit Website": "https://example.com/offer"}.

A static button you do not include keeps its template URL. A parameterized button you do not include is sent with an empty value in place of the placeholder, so always pass a value for every parameterized button.

What happens after a send

If the recipient’s number is not yet a customer in your workspace, Popcorn creates one.
The message appears in the conversation in the Inbox. With autoPilot: false the conversation is taken off Autopilot and placed in Unassigned; with true the AI agent connected to the sending number answers the customer’s replies. See Inbox overview.
V2 sends create a tracking record, so status webhooks follow if you configured them.

​Before you start

​List your templates

​V2 endpoint (recommended)

​Responses

​Errors

​Health check

​Standard endpoint

​Dynamic URL buttons

​What happens after a send

​Related

Before you start

List your templates

V2 endpoint (recommended)

Responses

Errors

Health check

Standard endpoint

Dynamic URL buttons

What happens after a send

Related