Running campaigns

A campaign can be run entirely from your system (a CRM, a lead database) and report each person’s outcome back to it, filed under your own ids.

1. Create it, with somewhere to send results

curl -X POST https://api.your-host/api/v1/campaigns \
  -H "authorization: Bearer $FIRETONE_KEY" -H 'content-type: application/json' \
  -d '{
    "name": "Spring reactivation",
    "kind": "voice_broadcast",
    "message_text": "Hi {{name}}, your {{plan}} plan renews next week...",
    "caller_id": "+61298765432",
    "reference": "crm-campaign-77",
    "result_callback_url": "https://crm.acme.com.au/firetone/results"
  }'

result_callback_url needs your organisation’s callback secret to exist, because results are signed with it.

2. Load people, with your ids and data

curl -X POST https://api.your-host/api/v1/campaigns/$ID/contacts \
  -H "authorization: Bearer $FIRETONE_KEY" -H 'content-type: application/json' \
  -H "Idempotency-Key: load-77-batch-1" \
  -d '{ "items": [
    { "e164": "+61412345678", "name": "Sam", "reference": "lead-1001", "variables": { "plan": "Gold" } },
    { "contact_id": "3f2a…", "reference": "lead-1002" }
  ] }'

A number FireTone doesn’t know becomes a new contact.
variables are the call’s own:
- {{plan}} in the message or in the campaign’s workflow;
- what an AI agent knows about the person;
- and they come back with the result.
Do-not-call contacts are loaded as suppressed and never rung.
Up to 10,000 items per request. Send more in batches, each with its own Idempotency-Key.

3. Start, pause, resume, stop

Call	Allowed when	What happens
`POST /campaigns/{id}/start`	`draft`	Dialling starts inside the calling window
`POST /campaigns/{id}/pause`	`running`	No new calls; calls in progress finish
`POST /campaigns/{id}/resume`	`paused`	Dialling carries on
`POST /campaigns/{id}/stop`	any but `completed`	Completed now, with totals so far

Wrong status: 409 wrong_status, naming the status the campaign must be in.
Can’t run: 422 not_ready, saying why (for example, no message or nobody left to call).

4. Results

A contact’s outcome is final when nothing more will be done. Either the call reached an end, or every attempt was used. Each final outcome is sent once, as campaign.contact.completed, to result_callback_url and to any webhook subscribed to it:

{
  "event": "campaign.contact.completed",
  "data": {
    "campaign_id": "…", "campaign_reference": "crm-campaign-77",
    "contact_id": "…", "reference": "lead-1001", "e164": "+61412345678", "name": "Sam",
    "outcome": "reached", "disposition": "message_played", "attempts": 1,
    "variables": { "plan": "Gold" },
    "disposition_answers": { "interested": "yes" },
    "summary": "Sam will renew; asked for a call about the family plan."
  }
}

`outcome`	Meaning
`reached`	A person or a machine got the message, or an agent took the call
`not_reached`	No answer, busy, rejected, or they hung up waiting
`bad_number`	The number doesn’t exist or can’t be routed
`suppressed`	Do-not-call
`failed`	Something on our side (no credit, no message)

disposition gives the exact result. An agent’s disposition form answers arrive as disposition_answers, and for an AI agent the conversation summary.

When nobody is left to call, the campaign completes and sends campaign.completed with the totals by outcome and by disposition.
Missed a callback? GET /campaigns/{id}/results pages through the same results, filtered by outcome, disposition, reference or since.

Start

Building

Tools

API reference

Running campaigns

1. Create it, with somewhere to send results

2. Load people, with your ids and data

3. Start, pause, resume, stop

4. Results

​1. Create it, with somewhere to send results

​2. Load people, with your ids and data

​3. Start, pause, resume, stop

​4. Results

1. Create it, with somewhere to send results

2. Load people, with your ids and data

3. Start, pause, resume, stop

4. Results