Campaigns

​

What a campaign is made of

• Audiences — one or more contact groups attached to the campaign. These are the recipients. A campaign with no audiences cannot be launched.
• Content — the message body or template for the campaign, one row per channel. SMS, voice, and WhatsApp each have their own content row. You cannot attach two content rows for the same channel to the same campaign.
• Runs — the scheduled executions of the campaign. A run can be single-shot (fire once at a specific time) or recurring (a cron-style schedule). A campaign with no run will never send anything, no matter how complete its audience and content are.

​

Dashboard vs API — when to use which

​

Lifecycle at a glance

draft → configured → ready → scheduled → running → completed
                                                 → failed
                                                 → cancelled
                                                 → paused (reversible)

1. Editing a ready or scheduled campaign drops it back to configured. Any change to audiences, content, or runs invalidates the pre-flight check. You must call /validate again (dashboard does this automatically when you re-open the launch panel) before you can launch.
2. cancelled is sticky. There is no un-cancel. Cancelling refunds unsent message reservations and closes the campaign permanently. If you need to send again, clone the campaign.

​

Run status

​

The dashboard walkthrough (high level)

1. Open your workspace at briq.tz/login and switch to the workspace that owns the campaign.
2. Click “New Campaign” and give it a name and description.
3. Add audiences by selecting one or more existing contact groups.
4. Add content for each channel you intend to use (SMS, voice, WhatsApp). The dashboard enforces the one-row-per-channel rule.
5. Schedule a run and click Launch. The dashboard runs validation behind the Launch button — if anything is missing or inconsistent it tells you exactly which field to fix — and then moves the campaign through the same lifecycle states described above.

​

The API walkthrough (high level)

1. POST /v1/campaign                              — create
2. POST /v1/campaign/{id}/audiences               — attach contact groups
3. POST /v1/campaign/{id}/content                 — attach message/template
4. POST /v1/campaign/{id}/runs                    — schedule a run
5. POST /v1/campaign/{id}/validate                — pre-flight check
6. POST /v1/campaign/{id}/launch                  — go live
7. GET  /v1/campaign/{id}/status                  — poll for progress

• Building a campaign — creating the campaign record and attaching audiences, content, and runs.
• Launch control — validating, launching, pausing, resuming, cancelling, and retrying.
• Observability — status polling, analytics, and run-level detail.

​

Authentication snapshot

• X-API-Key (required) — your developer API key. The key must be in ACTIVE state; revoked or expired keys return 401 UNAUTHORIZED.
• X-App-ID (optional but recommended) — the UUID of the developer app to attribute the call to. Send this when your API key is linked to multiple developer apps so Briq can disambiguate which one is calling.

​

Response envelope

{
  "success": true,
  "data": { },
  "errors": null,
  "request_id": "<uuid>"
}

• success mirrors HTTP status. true on 2xx, false on 4xx and 5xx. Branch on success rather than re-parsing the status code.
• On error, data is null and errors is an array of { code, message, field } objects. field is populated for validation errors so you can map the failure back to the specific input.
• Always log request_id. It is how Briq support correlates your call to internal traces. Include it in any support ticket.

​

Error codes at a glance

​

Best practices

• Use the dashboard for one-off sends. The API is for automation — every dashboard action has an API equivalent, but not every API workflow is worth the engineering cost when a human will only do it once.
• Always validate before launching. The dashboard does this automatically; via the API, call /validate before /launch so failures surface as actionable field errors instead of a launch-time CONFLICT.
• Treat cancelled as permanent. It refunds unsent message reservations and cannot be undone. Clone the campaign if you need to send again.
• Log every request_id. Support cannot trace a call without it. Persist it alongside whichever business object you correlate to the campaign.
• Poll /status no faster than every 5–15 seconds, and back off entirely once the campaign reaches a terminal state (completed, failed, cancelled). For real-time progress, prefer Webhooks over polling.