Campaigns Overview

Broadcast targeted WhatsApp messaging and voice campaigns with Sayvy AI

Campaigns API

The Campaigns API enables you to programmatically create, schedule, monitor, and control bulk outbound campaigns across your organization’s contacts. Campaigns support targeted audience filtering, approved WhatsApp templates, automatic asynchronous dispatching via background task queues, real-time delivery telemetry, and executive PDF reporting.

+-------------------------------------------------------------+
|                      Sayvy AI Campaign                      |
|                                                             |
|   +-------------------+              +------------------+   |
|   |  Audience Filter  |              | Message Template |   |
|   | (All/Tags/Manual) |              |  (WhatsApp Meta) |   |
|   +---------+---------+              +--------+---------+   |
|             \                                /              |
|              \                              /               |
|               +------------+---------------+                |
|                            |                                |
|                            v                                |
|             +------------------------------+                |
|             |     Campaign Orchestrator    |                |
|             |  (Immediate / Redis TaskIQ)  |                |
|             +--------------+---------------+                |
|                            |                                |
|              +-------------+-------------+                  |
|              |                           |                  |
|              v                           v                  |
|     +-----------------+         +-----------------+         |
|     | Dispatch Queue  |         | Live Analytics  |         |
|     | (WhatsApp WABA) |         | (Sent/Delivered)|         |
|     +-----------------+         +-----------------+         |
+-------------------------------------------------------------+

---

Key Capabilities

Multi-Tier Audience Targeting

Broadcast to your full contact database, filter dynamically by contact tags, or pass specific recipient UUID lists.

Immediate & Scheduled Dispatch

Trigger delivery immediately upon creation or schedule a precise future UTC timestamp with automated TaskIQ background workers.

Interactive Execution Controls

Pause active or scheduled dispatches, resume delivery at will, or cancel campaigns safely before messages are sent.

Live Metrics & PDF Reports

Inspect live aggregated sent, delivered, read, and failed counts, and export branded PDF executive summary reports on demand.

---

Campaign Lifecycle & States

Every campaign progresses through well-defined operational states:

Status	Description	Permitted Actions
draft	Initial campaign draft before queueing	Update, delete
scheduled	Slotted in TaskIQ Redis schedule for future dispatch	Pause, cancel, delete, view metrics
sending	Currently dispatching messages to recipient contacts	Pause, cancel, view metrics, export PDF
paused	Temporarily halted dispatching	Resume, cancel, delete, view metrics
completed	All contacts processed and final delivery status recorded	View metrics, export PDF, delete
cancelled	Halted before all contacts were sent	View metrics, export PDF, delete

---

Audience Types

When creating a campaign, configure the audience_type parameter to control recipient resolution:

Audience Type	Description	Required Parameters
all	Dispatches to all contacts in the organization	None
tags	Filters contacts matching any specified tags	audience_tags: ["vip", "leads"]
manual	Sends only to explicitly listed contact IDs	audience_contact_ids: ["UUID1", "UUID2"]

---

Rate Limiting Tiers

Campaign operations are tiered to ensure infrastructure reliability:

• Create Campaign: RateLimitTier.EXPENSIVE — Protects dispatch worker queues.
• List / Get Campaign: RateLimitTier.READ — High-throughput cached telemetry.
• Pause / Resume / Cancel / Delete / PDF Export: RateLimitTier.WRITE — Fast mutation and on-the-fly PDF document generation.

---

Authentication

All Campaigns API endpoints require a valid organization API key or Bearer JWT token passed in the Authorization header:

Authorization: Bearer <your-api-key>

---

Available Endpoints

Method	Endpoint	Description
POST	/api/v1/campaigns	Create a new campaign (immediate or scheduled)
GET	/api/v1/campaigns	List paginated campaigns with live delivery metrics
GET	/api/v1/campaigns/{campaign_id}	Retrieve single campaign details and broadcast telemetry
POST	/api/v1/campaigns/{campaign_id}/pause	Pause a scheduled or sending campaign
POST	/api/v1/campaigns/{campaign_id}/resume	Resume a paused campaign
POST	/api/v1/campaigns/{campaign_id}/cancel	Cancel an active or scheduled campaign
DELETE	/api/v1/campaigns/{campaign_id}	Permanently delete a campaign
GET	/api/v1/campaigns/{campaign_id}/export/pdf	Download formatted campaign performance PDF report

---

‹ Previous

Create campaign

POST /api/v1/campaigns

Next ›