Skip to main content

​
Send Template Message

Method: POST
URL: https://api.trypopcorn.ai/template/send Send a WhatsApp template message to a recipient. This endpoint provides a single, unchanging URL that works for all your templates - perfect for integrations with automation tools like Zapier, Make, n8n, and custom applications.

​
Headers

  • POPCORN-API-KEY (string, required) - API key provided by the Popcorn team.
  • Content-Type (string, required) - Must be application/json.
  • POPCORN-PHONE-NUMBER (string, optional) - Specific WhatsApp phone number to send from. Include this only if your account has multiple WhatsApp numbers and you want to specify which one to use. Must be a phone number that belongs to your organization. If not provided, your default WhatsApp number will be used.

​
Body Parameters

  • templateId (string, required) - Unique ID of the template to send.
  • recipientNumber (string, required) - Phone number of the recipient.
  • variables (array, optional) - Custom variables to be used in the template body. Include this only if the template is dynamic and requires variables. The array of values should be ordered, with each variable corresponding sequentially to the placeholders in the template.
  • buttonValues (object, optional) - Key-value pairs for dynamic button URLs. The keys should match the button text in your template (e.g., “Learn More”, “Get Started”). For parameterized URLs with {{1}} placeholders, provide only the parameter value. For static URLs, provide the complete URL.
  • enableAutoPilot (boolean, optional) - If set to true, the AI agent will continue the conversation if the recipient responds. If set to false, the conversation will be assigned to a human agent. Defaults to false if not provided.

​
Example Request

POST https://api.trypopcorn.ai/template/send
Content-Type: application/json
POPCORN-API-KEY: sk-your_popcorn_api_key
POPCORN-PHONE-NUMBER: 971501234568

{
  "templateId": "12345-abcd-6789-efgh",
  "recipientNumber": "1234567890",
  "variables": ["John Doe"],
  "buttonValues": {
    "Learn More": "pricing",
    "Contact Us": "contact"
  },
  "enableAutoPilot": true
}

​
Example Response

{
  "success": true
}

​
Request & Response

​
Dynamic URL Buttons

If your template includes URL buttons, you can dynamically customize the destination URLs using the buttonValues parameter. For parameterized URLs (with {{1}} placeholders):
  • Provide just the parameter value, not the full URL
  • Example: If your button URL is https://trypopcorn.ai/{{1}} and you provide "Learn More": "pricing", the final URL will be https://trypopcorn.ai/pricing
For static URLs:
  • Provide the complete URL you want to use
  • Example: "Visit Website": "https://trypopcorn.ai/special-offer"

​
Multiple WhatsApp Numbers

If your account has multiple WhatsApp numbers:
  • Omit the POPCORN-PHONE-NUMBER header to use your default WhatsApp number
  • Include the POPCORN-PHONE-NUMBER header with a specific phone number to send from that number
  • The phone number format should include the country code (e.g., 971501234567) without +
  • An error will be returned if the specified phone number doesn’t belong to your organization

​
Errors

400 - Bad Request 
{
  "success": false,
  "error": "recipientNumber is required"
}
Or: 
{
  "success": false,
  "error": "templateId is required"
}
403 - Forbidden 
{
  "error": "Unauthorized",
  "message": "The specified phone number does not belong to this organization"
}
401 - Unauthorized 
{
  "error": "Unauthorized",
  "message": "invalid api key"
}
Or: 
{
  "error": "API Key not included in headers."
}
500 - Internal Server Error 
{
  "success": false,
  "error": "Error details here",
  "templateId": "12345-abcd-6789-efgh",
  "timestamp": "2024-11-12T10:30:00.000Z"
}

​
Backward Compatibility Note

Legacy Endpoint: If you have existing integrations using POST /template/:templateId (with template ID in the URL path), they will continue to work. However, we recommend migrating to the new /template/send endpoint for better flexibility and easier integration management. The legacy endpoint is maintained purely for backward compatibility.