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 Channels and at least one template approved by Meta. See 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 & Webhooks (in the Developer group).

Create the key

Click Create New API Key, enter a Key Description (optional) such as Production, and click Generate API Key.

Copy it now

The full key is shown once, in a banner with a Copy button. After you dismiss the banner, the list only shows the last four characters.

Keys start with sk-. The table shows each key’s Description, Created date, Last Used date (or Never used), and Status (Active or Revoked). Click Revoke and confirm (“Are you sure you want to revoke this API key? This action cannot be undone.”); any application using it loses access immediately and the key cannot be restored. Revoked keys stay in the list.

The settings page describes these as manual keys that “bypass OAuth consent”, so keep them for backend integrations. 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. 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