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

Headers

  • POPCORN-API-KEY (string, required) - API key provided by the Popcorn team.

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"

Example Request

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

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

Errors

  • 400 - Invalid request, e.g., missing recipientNumber or templateId.
  • 500 - Internal server error.