Skip to main content
API Campaigns are long-lived, always-on pipelines that tie an approved template to a named campaign. Instead of broadcasting to a static list, you trigger sends programmatically — one contact at a time — making them the right tool for event-driven notifications (order confirmations, OTPs, appointment reminders), CRM-triggered outreach, and automated drip sequences. Each send call accepts personalization variables, contact attributes, and tags so your analytics stay clean and segmentable.
You can use the magic variables $Name and $FirstName in your template_params array and Convo will automatically substitute them with the contact’s stored name — no extra lookup needed.

​
Setting Up an API Campaign

1

Create the campaign

Create a named campaign and bind it to an approved template. You only need to do this once — the campaign stays LIVE indefinitely.
Response
Save the id — you’ll need it for analytics and audience queries.
2

Send to a contact

Trigger a send to any individual contact. Convo looks up or creates the contact, substitutes template_params into the template body in order, and dispatches the message.
3

Get campaign details

Retrieve metadata and current status for a specific campaign.
The response includes template_name, status, creation timestamps, and the cumulative send count.
4

View analytics

Pull aggregated delivery and engagement metrics for any date range.
See the Analytics Metrics section below for a full breakdown of the returned fields.
5

Fetch audience list

Retrieve a paginated list of contacts in a specific delivery category. Use category to filter by outcome and limit to control page size.
See Audience Categories for all valid category values.

​
Sending Media with Campaigns

If your template has a media header (IMAGE, VIDEO, or FILE), include a media object in your send request. Convo uses the url as the header media and filename as the display name shown to the recipient.
The url must be a publicly accessible HTTPS link. For PDFs and documents, set filename with the appropriate extension (e.g., "invoice.pdf") so the recipient sees a meaningful file name.

​
Audience Categories

When fetching your campaign audience, filter by one of the following category values:

​
Analytics Metrics

The analytics response contains the following key fields: Use the read rate (readChatCount / deliveredChatcount) and engagement rate (engagementCount / sentChatCount) as your primary campaign health indicators.