API Reference - Popcorn Documentation

The Popcorn API lets your own systems send approved WhatsApp template messages through your connected WhatsApp number and receive delivery status updates back. It is meant for developers integrating an order system, CRM, or automation tool with Popcorn. Everything else, from campaigns to inbox triage, is done in the dashboard or through AI assistants.

What the API covers

Endpoint	What it does
`POST /api/v2/template/send`	Send a template to one phone number, with tracking, async mode, and webhook callbacks. See Send a template.
`POST /template/send`	The standard send endpoint without tracking. See Send a template.
`GET /template`	List the templates in your workspace with their IDs, languages, and approval status.
`GET /api/v2/template/health`	Check that the API is up and your key is accepted.
Message Status Webhook	Popcorn calls your URL when a tracked message is sent, delivered, read, or fails. See Message status webhooks.

Base URL: https://api.trypopcorn.ai

Before you start

A WhatsApp number connected under Integrations and at least one template approved by Meta. See Connect a WhatsApp number and Templates.
A role that can manage API keys. By default the Owner and Admin roles can create and revoke keys; the Manager role can only view the list. See Team and roles.

Create an API key

Open the developer settings

Go to Settings → API keys and webhooks (in the Developer group). The API keys panel reads “Use a key when your own server calls Popcorn AI.”

Create the key

Click Create API key (with no keys yet the page reads No API keys yet, with the same button), enter a Name (optional) such as Production, and click Create key. You see API key created. A key with no name is called Default.

Copy it now

Copy your API key shows the full key once: “You won’t see this key again. Store it somewhere safe.” Click Copy, then Done. The dialog closes only with Done. After that the list shows only a masked form, such as sk-...abcd.

Keys start with sk-. The table shows each key’s Name, Created date, Last used date (or Never used), and Status (Active or Revoked). To remove a key, click Revoke, then Revoke key on “Revoke name?” (“Apps using this key lose access right away. This can’t be undone.”). You see API key revoked; the key cannot be restored, and revoked keys stay in the list.

Keep API keys for backend integrations, where your own server calls Popcorn. To let ChatGPT, Claude, or Codex work in your workspace, use AI assistants instead; that connection needs no API key.

Authenticate requests

Send the key in the POPCORN-API-KEY header on every request:

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

{
  "status": "ok",
  "service": "template-v2-api",
  "version": "2.0",
  "timestamp": "2026-09-01T10:30:00.000Z"
}

The /api/v2 endpoints also accept Authorization: Bearer sk-your_popcorn_api_key. The /template endpoints accept only POPCORN-API-KEY. Each key belongs to one workspace, the one you were in when you created it. Requests act on that workspace’s templates, WhatsApp numbers, and Inbox; you cannot address another workspace with a key.

Authentication errors

HTTP status	Response	Cause
`401`	`{"error": "API Key not included in headers."}`	No `POPCORN-API-KEY` header on a `/template` endpoint.
`401`	`{"success": false, "error": {"code": "UNAUTHORIZED", "message": "API Key or Authorization header required"}}`	No key on an `/api/v2` endpoint.
`401`	`{"error": "Unauthorized", "message": "invalid api key"}`	The key does not exist or has been revoked.
`401`	`{"error": "Unauthorized", "message": "api key must start with sk-"}`	The header value is not a Popcorn key.
`401`	`{"error": "Unauthorized", "message": "organization suspended"}`	The workspace is suspended, for example after a lapsed subscription. See Top-ups and renewal.
`403`	`{"error": "Unauthorized", "message": "The specified phone number does not belong to this organization"}`	A `POPCORN-PHONE-NUMBER` header names a number that is not connected to your workspace.

Choosing between the API and AI assistants

Use the API when	Use AI assistants when
Another system needs to send a template automatically, for example an order confirmation from your ERP.	A person wants to run the workspace in natural language from ChatGPT, Claude, or Codex.
You need delivery status pushed to your server.	You need campaigns, inbox triage, customers, products, orders, agents, or knowledge, none of which the API exposes.
You are building a backend integration with a long-lived key.	You want access tied to a user, their role, and an approval screen instead of a key.

Send a template

Request and response formats for both send endpoints, and how to list templates.

Message status webhooks

Configure the webhook URL, token, and events, and read the payload.

Templates

Create templates and get them approved by Meta before sending.

AI assistants

Run your workspace from ChatGPT, Claude, or Codex without an API key.

​What the API covers

​Before you start

​Create an API key

​Authenticate requests

​Authentication errors

​Choosing between the API and AI assistants

​Related

Send a template

Message status webhooks

Templates

AI assistants

What the API covers

Before you start

Create an API key

Authenticate requests

Authentication errors

Choosing between the API and AI assistants

Related