API Documentation
Send Template
Endpoint to send a template message to a recipient.
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 totrue
, the AI agent will continue the conversation if the recipient responds. If set tofalse
, the conversation will be assigned to a human agent. Defaults tofalse
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 behttps://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
Example Response
If there’s an error, the response may look like:
Or for phone number errors:
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.