When to Use
- You want to send campaigns from your own system without opening the Cloud Chat interface.
- You want to estimate how many contacts an audience reaches before sending.
- You need to programmatically monitor the status of a campaign.
Prerequisites
Creating a campaign triggers sending. There is no draft mode in the API, unlike the interface. Do not use the creation endpoint to "assemble and review later".
- Account API key.
- Profile with permission for campaigns. The agent profile cannot send campaigns via API or interface.
How It Works
Check Reach Before Sending
There is an endpoint that determines the audience and returns the actual number of contacts reached. Use it before creating the campaign: this prevents discovering the actual size of the send after it has been dispatched.
Mandatory Recipient Confirmation
During creation, you must declare how many recipients you expect to reach. The system compares this number with the actual audience size:
- If they match, the campaign is created and queued for sending.
- If they differ, the response is a conflict error and nothing is created.
This is a safeguard against unintentional sends. It exists precisely because there is no draft: if your audience has grown since the last time you checked, the request fails instead of sending to more people than expected.
Available Channels
Creation covers the three channels also available in the interface: WhatsApp, email, and web widget.
Discover Templates and Variables
Since API callers do not see the interface, there are two discovery endpoints: one lists available templates in the account, and the other lists the variables you can use. Use them to compose the campaign body without relying on someone to check the panel.
Check Status Later
There is a read endpoint to monitor the created campaign.
Notes
- The full endpoint reference is in the public API documentation. The same capabilities are also available as an MCP tool.
- Campaigns created via API start in the same state as those created via the interface, and the same scheduler sends them. The API is the entry point, not a different sending path.
- There are recipient limits, both per total audience and per channel. If the request exceeds these limits, you receive a validation error and nothing is created.