Method: POST
URL: https://api.trypopcorn.ai/template/:templateId

​
Headers

  • POPCORN-API-KEY (string, required) - API key provided by the Popcorn team.
  • 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.

​
Parameters

  • Path Parameter:

    • templateId (string) - Unique ID of the template to send.

  • Body Parameters:

    • 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.

​
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

​
Example Request

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

{
  "recipientNumber": "1234567890",
  "variables": ["John Doe"],
  "buttonValues": {
    "Learn More": "pricing",
    "Contact Us": "contact"
  },
  "enableAutoPilot": true
}

​
Example Response

{
  "success": true
}

If there’s an error, the response may look like:

{
  "success": false,
  "error": "recipientNumber is required"
}

Or for phone number errors:

{
  "error": "Unauthorized",
  "message": "The specified phone number does not belong to this organization"
}

​
Errors

  • 400 - Invalid request, e.g., missing recipientNumber or templateId.
  • 403 - Unauthorized, e.g., specified phone number doesn’t belong to your organization.
  • 500 - Internal server error.