# FireTone

- [FireTone](https://docs.firetone.com.au/index.md): A multi-tenant cloud phone system: inbound services, outbound campaigns, and AI that answers, assists and is billed for.
- [What FireTone is](https://docs.firetone.com.au/guides/what-is-firetone.md): The model the whole product is built on, in one page.
- [Signing in](https://docs.firetone.com.au/guides/signing-in.md): Two doors, on purpose: one for staff, one for the people on the phones.
- [Roles](https://docs.firetone.com.au/guides/roles.md): Four roles on one axis, and what each is deliberately kept away from.
- [Your first campaign](https://docs.firetone.com.au/guides/first-campaign.md): From an empty tenant to a broadcast that has rung somebody, end to end.
- [Processes](https://docs.firetone.com.au/tenant/inbound/processes.md): One named inbound service: its numbers, its hours, its workflow and where a caller lands when the workflow does not take them.
- [Phone numbers](https://docs.firetone.com.au/tenant/inbound/numbers.md): The numbers you own, what each one reaches, and the wizard that sets one up.
- [Queues](https://docs.firetone.com.au/tenant/inbound/queues.md): Where an inbound caller waits, and who is offered the call.
- [Conference rooms](https://docs.firetone.com.au/tenant/inbound/conferences.md): Dial-in bridges your organisation owns: a number, a PIN, and a moderator who can run the room.
- [Voice broadcasting](https://docs.firetone.com.au/tenant/outbound/voice-broadcasting.md): Play a message to whoever answers. No agent, so nobody is ever left holding.
- [Automatic dialler](https://docs.firetone.com.au/tenant/outbound/automatic-dialer.md): Call a list and connect whoever answers to a free agent, at a pace that matches how many are actually free.
- [Contacts](https://docs.firetone.com.au/tenant/outbound/contacts.md): Everyone who has called or been called, and what you know about them.
- [Segments](https://docs.firetone.com.au/tenant/outbound/segments.md): A named group of contacts, reusable across campaigns.
- [IVR flows](https://docs.firetone.com.au/tenant/design/ivr-flows.md): The graph that answers a call: greetings, menus, time checks, actions and destinations.
- [Outbound routing](https://docs.firetone.com.au/tenant/design/routing.md): Which carrier an outgoing call uses, and in what order.
- [Extensions](https://docs.firetone.com.au/tenant/phone-system/extensions.md): The handsets and softphones that register with FireTone.
- [Dialling out](https://docs.firetone.com.au/tenant/phone-system/dialling.md): How FireTone reads the number somebody dials, and what it refuses.
- [Integrations](https://docs.firetone.com.au/tenant/phone-system/integrations.md): Look callers up in your own system during a call, and receive call events as they happen.
- [SMS](https://docs.firetone.com.au/tenant/phone-system/sms.md): Text messages through your own FireFlo account: sender IDs, templates, and what was sent.
- [Teams & agents](https://docs.firetone.com.au/tenant/phone-system/teams-and-agents.md): Who takes calls, and what a team actually is.
- [Trunks](https://docs.firetone.com.au/tenant/phone-system/trunks.md): The carriers that carry your calls.
- [Virtual agents](https://docs.firetone.com.au/tenant/ai/virtual-agents.md): An AI that answers the phone, holds the conversation and can act.
- [Knowledge base](https://docs.firetone.com.au/tenant/ai/knowledge-base.md): What your AI agents may tell callers, and nothing else.
- [Live assist](https://docs.firetone.com.au/tenant/ai/live-assist.md): An AI that listens to a call between two people and writes suggestions to the agent's screen.
- [What AI costs](https://docs.firetone.com.au/tenant/ai/what-ai-costs.md): Tokens, where they are counted, and how to read a figure that is approximate.
- [Signing in](https://docs.firetone.com.au/agent/signing-in.md): Your extension and your PIN, at the start of a shift.
- [Your desk](https://docs.firetone.com.au/agent/your-desk.md): What is on screen while you work.
- [The phone in your browser](https://docs.firetone.com.au/agent/the-phone.md): Answering, dialling and handling calls without a handset.
- [Who you are talking to](https://docs.firetone.com.au/agent/who-you-are-talking-to.md): The customer's details, the moment the call connects.
- [What the AI already asked them](https://docs.firetone.com.au/agent/before-you-picked-up.md): When a call is handed to you by an AI, read this first.
- [Recording an outcome](https://docs.firetone.com.au/agent/recording-an-outcome.md): What came of the call, in the form your organisation designed.
- [Organisations](https://docs.firetone.com.au/operator/organisations.md): The tenants on your platform.
- [Email](https://docs.firetone.com.au/operator/email.md): Your SMTP server, the templates every email uses, and what was sent.
- [Mobile push](https://docs.firetone.com.au/operator/mobile-push.md): Waking the FireTone app for an incoming call when the phone is in a pocket
- [Trunks and rate cards](https://docs.firetone.com.au/operator/trunks-and-rates.md): Carriers, what they cost you, and what you charge for them.
- [Outbound routing](https://docs.firetone.com.au/operator/outbound-routing.md): Which carrier an organisation's outgoing call uses, in the order the switch decides it.
- [AI pricing](https://docs.firetone.com.au/operator/ai-pricing.md): What a model costs per million tokens, and who is charged.
- [Billing](https://docs.firetone.com.au/operator/billing.md): Balances, what a period came to, and reading a figure that is withheld.
- [The fleet](https://docs.firetone.com.au/operator/fleet.md): The machines carrying calls, the limits that protect them, and what happens at each.
- [Blocking addresses](https://docs.firetone.com.au/operator/blocking.md): What the Bans page shows, the one list that is never blocked, and the blocks the platform places on its own.
- [Choosing table columns](https://docs.firetone.com.au/operator/table-columns.md): Every list in the panel shows the columns you pick.
- [Installing FireTone](https://docs.firetone.com.au/operator/installing.md): What runs where, and the order to bring it up in.
- [Every setting](https://docs.firetone.com.au/operator/settings.md): The FIRETONE_* environment the daemon reads.
- [Quickstart](https://docs.firetone.com.au/api/quickstart.md): From nothing to a signed callback in about ten minutes.
- [Authentication](https://docs.firetone.com.au/api/authentication.md): Getting a token, and what a token can do.
- [Conventions](https://docs.firetone.com.au/api/conventions.md): Paging, filtering, money, and the difference between absent and zero.
- [Errors and limits](https://docs.firetone.com.au/api/errors.md): Every error code, what it means, and whether to retry.
- [Placing calls](https://docs.firetone.com.au/api/calls.md): Click-to-call from your CRM, an AI agent ringing a lead, and hearing how each call went.
- [Conference rooms](https://docs.firetone.com.au/api/conferences.md): Create dial-in rooms, put people in them, and run a room while it is up: mute, kick, lock, record, end.
- [Running campaigns](https://docs.firetone.com.au/api/campaigns.md): Load contacts from your system, start and stop the campaign, and get each contact's result back.
- [Contacts and call data](https://docs.firetone.com.au/api/contacts-and-data.md): Screen-pop by number, keep contacts in step with your CRM, and export calls.
- [Webhooks](https://docs.firetone.com.au/api/webhooks.md): Every event, what it carries, how it's signed and delivered.
- [Live events](https://docs.firetone.com.au/api/events.md): A WebSocket of what happens as it happens: for wallboards and screen-pops.
- [Recipes](https://docs.firetone.com.au/api/recipes.md): The common integrations, end to end.
- [The Developer section](https://docs.firetone.com.au/api/developer.md): Keys, the console, the callback inbox, the request log and test numbers, in your panel.
- [Reference](https://docs.firetone.com.au/api/reference.md): The public API's OpenAPI document, and where it lives.
- [Changelog](https://docs.firetone.com.au/api/changelog.md): What changed in the public API, and how changes are made.
- [List agents](https://docs.firetone.com.au/api-reference/provisioning/list-agents.md): Sort keys: created_at, kind, name, number, status. An unknown sort key is a 400.
- [List extensions](https://docs.firetone.com.au/api-reference/provisioning/list-extensions.md): SIP passwords are never included. Sort keys: caller_id_name, created_at, enabled, number. An unknown sort key is a 400.
- [List virtual agent profiles](https://docs.firetone.com.au/api-reference/provisioning/list-virtual-agent-profiles.md): Sort keys: created_at, name, provider. An unknown sort key is a 400.
- [Resolved scope for the current token](https://docs.firetone.com.au/api-reference/auth/resolved-scope-for-the-current-token.md)
- [A call request's progress](https://docs.firetone.com.au/api-reference/live/a-call-requests-progress.md): What an API-placed call is doing: dialing, connected (with call_uuid), completed, or failed (with failure). Requires calls:read.
- [Click to call](https://docs.firetone.com.au/api-reference/live/click-to-call.md): Answers once the agent has picked up (up to 30 seconds); ?dry_run=true checks instead -- the extension has a phone registered to ring, the number resolves, an outside number has a route and credit -- and returns the plan, placing nothing. Rings the agent first, then dials the destination when they a…
- [Live channels](https://docs.firetone.com.au/api-reference/live/live-channels.md): Read from FreeSWITCH on every request, never cached: the switch is the only thing that knows, and a cached copy is wrong the moment a call ends.
- [An AI agent calls a number](https://docs.firetone.com.au/api-reference/live/an-ai-agent-calls-a-number.md): The profile's virtual agent rings `to` from `caller_id` (one of your numbers; optional when you have exactly one) and talks to whoever answers, with `variables` in its brief as what it knows about this call. Answers 202 at once: the dial happens in the background, and how it went is posted to callba…
- [One call](https://docs.firetone.com.au/api-reference/live/one-call.md): state live (from the switch, while it lasts) or ended (from its record): who, when, the hangup cause, your reference, and the recording's URL when there is one. Requires calls:read.
- [Hang up a live call](https://docs.firetone.com.au/api-reference/live/hang-up-a-live-call.md)
- [What was posted to a call's callback URL](https://docs.firetone.com.au/api-reference/live/what-was-posted-to-a-calls-callback-url.md): The call's callback deliveries, as the webhook delivery log shows them. The call uuid or its request id. Requires calls:read.
- [Put a live call on hold](https://docs.firetone.com.au/api-reference/live/put-a-live-call-on-hold.md): States the wanted state rather than toggling. uuid_hold toggles by default, which is the wrong shape for an API: two clients disagreeing about the current state would flip it back and forth. Requires calls:control.
- [Transfer a live call to an extension or queue](https://docs.firetone.com.au/api-reference/live/transfer-a-live-call-to-an-extension-or-queue.md): Blind transfer. NEVER external, and that is a policy rather than an omission: an agent transferring a customer to a premium-rate number is toll fraud billed to their own employer, and a blind transfer hands the call away entirely, so unlike a conference leg there is nothing left to observe. The same…
- [Take a live call off hold](https://docs.firetone.com.au/api-reference/live/take-a-live-call-off-hold.md): States the wanted state rather than toggling. uuid_hold toggles by default, which is the wrong shape for an API: two clients disagreeing about the current state would flip it back and forth. Requires calls:control.
- [WebSocket event stream](https://docs.firetone.com.au/api-reference/live/websocket-event-stream.md): Upgrade to a WebSocket. Events are filtered by the same scope as REST, so a panel never receives an organisation it could not query. The server pings every 30 seconds; reconnect on close. Events travel through Redis pub/sub, so a panel connected to one instance still sees calls handled by another.
- [List campaigns](https://docs.firetone.com.au/api-reference/campaigns/list-campaigns.md): Orchestrated outbound. Manual dial is deliberately NOT a campaign: an agent dialling a number is ad-hoc, and forcing it into this table would create a row for every click-to-call. Sort keys: created_at, dialed, kind, name, status.
- [Create a campaign](https://docs.firetone.com.au/api-reference/campaigns/create-a-campaign.md): A campaign is created in `draft`. It cannot be started: see PATCH.
- [Get one campaign](https://docs.firetone.com.au/api-reference/campaigns/get-one-campaign.md)
- [Update a campaign](https://docs.firetone.com.au/api-reference/campaigns/update-a-campaign.md): Partial. Setting `status` to `running` starts the dialer, and is refused with 422 when the runtime could not honour it: a campaign with no contacts left to call, a voice broadcast with no recorded message (text-to-speech and AI scripts are not built), or a kind with no handler. The checks are about…
- [The campaign's call list](https://docs.firetone.com.au/api-reference/campaigns/the-campaigns-call-list.md): Paged, sortable and searchable, because this is what an operator reads BEFORE launching a campaign rather than a diagnostic dump afterwards. It was capped at 500 with no paging, no sort and no filter: a list of fifty thousand showed the first five hundred by state and gave no way to find anybody, wh…
- [Load contacts into a campaign](https://docs.firetone.com.au/api-reference/campaigns/load-contacts-into-a-campaign.md): Takes contact ids, not numbers: a campaign must not conjure customer records as a side effect of being filled in. Idempotent -- a contact already on the list is skipped. At most 10,000 per request.
- [What agents recorded about this campaign's calls](https://docs.firetone.com.au/api-reference/campaigns/what-agents-recorded-about-this-campaigns-calls.md): Paged. An agent reads back what THEY recorded rather than the floor's; a supervisor sees their teams. The campaign's form supplies the field ORDER -- the answers cannot, because they are a jsonb object and jsonb does not preserve key order, a defect this codebase has already paid for once on the age…
- [Pause a campaign](https://docs.firetone.com.au/api-reference/campaigns/pause-a-campaign.md): Running to paused: no new calls; calls in progress finish. 409 wrong_status names the status it must be in; 422 not_ready says what is missing. Requires campaigns:write.
- [Each contact's final outcome](https://docs.firetone.com.au/api-reference/campaigns/each-contacts-final-outcome.md): Newest first. A contact's outcome is final when nothing more will be done: done, or every attempt used. outcome is reached, not_reached, bad_number, suppressed, failed or unknown; disposition is the exact result. The same data campaign.contact.completed carried -- read this to catch up after a misse…
- [Resume a campaign](https://docs.firetone.com.au/api-reference/campaigns/resume-a-campaign.md): Paused to running. 409 wrong_status names the status it must be in; 422 not_ready says what is missing. Requires campaigns:write.
- [Start a campaign](https://docs.firetone.com.au/api-reference/campaigns/start-a-campaign.md): From draft to running: the dialer starts within seconds, inside the calling window. Refused while it cannot run (no message, no contacts left, a kind without its pieces). 409 wrong_status names the status it must be in; 422 not_ready says what is missing. Requires campaigns:write.
- [What a campaign is doing right now](https://docs.firetone.com.au/api-reference/campaigns/what-a-campaign-is-doing-right-now.md): Meant to be polled while a campaign runs. In flight is counted from leased contacts rather than from live channels: the dialer sets a campaign id as a channel variable, but the switch's channel listing does not surface custom variables, so it cannot be filtered by campaign.
- [Stop a campaign](https://docs.firetone.com.au/api-reference/campaigns/stop-a-campaign.md): To completed, whatever is left: campaign.completed is sent with why=stopped and the totals so far. 409 wrong_status names the status it must be in; 422 not_ready says what is missing. Requires campaigns:write.
- [List call detail records](https://docs.firetone.com.au/api-reference/reporting/list-call-detail-records.md): Newest first. A team_supervisor or agent is restricted to their own team regardless of filters. Sort keys: billsec, caller_number, destination_number, direction, ended_at, sell_amount, started_at. An unknown sort key is a 400.
- [Export a period's calls](https://docs.firetone.com.au/api-reference/reporting/export-a-periods-calls.md): Streamed, oldest first: CSV (a header row, then one row per call) or NDJSON (one JSON object per line). At most 31 days per request. Columns: call_uuid, organisation_id, direction, caller_number, destination_number, dialled_number, started_at, answered_at, ended_at, duration_sec, billsec, hangup_cau…
- [Get one call](https://docs.firetone.com.au/api-reference/calls/get-one-call.md): One CDR, including the contact it was with. Cost and margin are withheld unless the caller holds billing:margin, exactly as in the list.
- [Download the recording](https://docs.firetone.com.au/api-reference/calls/download-the-recording.md): The audio itself, streamed, with Content-Disposition set so a browser saves it. Separate from /recording, which returns metadata for a list and is cheap; this streams megabytes. Supports Range requests so an audio player can seek without fetching the whole file. The stored path is confined to the re…
- [The conversation for a call](https://docs.firetone.com.au/api-reference/conversations/the-conversation-for-a-call.md): Keyed on the call rather than the conversation, for the call-detail screen. Scoped through the CDR.
- [List conversations](https://docs.firetone.com.au/api-reference/conversations/list-conversations.md): One per call, whoever handled it: provider and model are null for a human-handled call, which is what keeps this from being an AI log with a general-sounding name. Read-only — a conversation is a record of what happened, and an editable transcript is not one. assembled_context is omitted here and re…
- [One conversation with its transcript](https://docs.firetone.com.au/api-reference/conversations/one-conversation-with-its-transcript.md): Includes assembled_context: exactly what the agent was told before it spoke. Stored verbatim because the prompt is built at runtime from the profile, the contact, past summaries, open tickets and memory rows, and cannot be reconstructed once any of those have moved on.
- [List contacts](https://docs.firetone.com.au/api-reference/contacts/list-contacts.md): Customers, one per external number per organisation. Base architecture rather than an app: a tenant who disables tickets still has customers, so there is no enablement gate. Default sort is last_seen descending. Sort keys: last_seen, first_seen, e164, name, created_at.
- [Create a contact](https://docs.firetone.com.au/api-reference/contacts/create-a-contact.md): The number is normalised exactly as the call path normalises it, so a contact created here and one created by a call from the same number are the same customer. Anonymous, withheld and extension-length numbers are refused: they are not external customers, and recording them would produce one shared…
- [Create or update a contact by your id](https://docs.firetone.com.au/api-reference/contacts/create-or-update-a-contact-by-your-id.md): Keyed on your own id for the contact. Found by it and updated; or, when it is new, the contact that already has the number takes the reference; or it is created (201, contact.created). attributes MERGE into the contact's. 409 when the number belongs to a contact with a different reference. Requires…
- [Who is this number](https://docs.firetone.com.au/api-reference/contacts/who-is-this-number.md): For a screen-pop: the contact behind a number in any form it is typed (national or international), with its open tickets, the last five conversation summaries and the last call. 404 when nobody has the number. Requires contacts:read.
- [One contact](https://docs.firetone.com.au/api-reference/contacts/one-contact.md): Includes call_count across every call tied to this customer.
- [Delete a contact](https://docs.firetone.com.au/api-reference/contacts/delete-a-contact.md): CDRs survive with contact_id nulled: a CDR is a financial record of a call that happened, a contact is a customer profile, and they have different lifetimes on purpose.
- [Update a contact](https://docs.firetone.com.au/api-reference/contacts/update-a-contact.md): e164 is deliberately NOT patchable: it is the identity every call, CDR and memory row was matched on, and changing it would silently reassign one customer's history to another number.
- [Whether the callback secret is set](https://docs.firetone.com.au/api-reference/integrations/whether-the-callback-secret-is-set.md): Never the secret itself. Requires integrations:read.
- [Create or rotate the callback secret](https://docs.firetone.com.au/api-reference/integrations/create-or-rotate-the-callback-secret.md): Returns the new secret ONCE. Every POST to a request's callback_url is signed with it (X-FireTone-Signature, exactly as webhooks). The old secret stops signing at once. Requires integrations:write.
- [List webhooks](https://docs.firetone.com.au/api-reference/integrations/list-webhooks.md): Requires integrations:read.
- [Create a webhook](https://docs.firetone.com.au/api-reference/integrations/create-a-webhook.md): Generates the signing secret and returns it once. Delivery: a bounded queue, three attempts over about five minutes, each recorded (GET /webhooks/{id}/deliveries). Body: WebhookEvent. Requires integrations:write.
- [The events a webhook can subscribe to](https://docs.firetone.com.au/api-reference/integrations/the-events-a-webhook-can-subscribe-to.md): Each event with what it means. Requires integrations:read.
- [Delete a webhook](https://docs.firetone.com.au/api-reference/integrations/delete-a-webhook.md)
- [Update a webhook](https://docs.firetone.com.au/api-reference/integrations/update-a-webhook.md)
- [A webhook's deliveries](https://docs.firetone.com.au/api-reference/integrations/a-webhooks-deliveries.md): Newest first, paged, kept 14 days. Every event is written here before it is sent, so this is also the outbox: status queued (waiting, or being retried at next_attempt_at), sending, delivered, failed. Retries after 30 s, 5 min, 30 min, 2 h and 12 h; a webhook whose deliveries have all failed for thre…
- [One delivery, with the exact body sent](https://docs.firetone.com.au/api-reference/integrations/one-delivery-with-the-exact-body-sent.md): payload is the body byte-for-byte as signed; absent for a test ping. Requires integrations:read.
- [Send a delivery again](https://docs.firetone.com.au/api-reference/integrations/send-a-delivery-again.md): Queues the same body with the same delivery id (so a receiver that de-duplicates on X-FireTone-Delivery still can) as a new row with its own attempts. 409 webhook_disabled when the webhook is switched off. Requires integrations:write.
- [Send a test event](https://docs.firetone.com.au/api-reference/integrations/send-a-test-event.md): Sends a webhook.test event, signed exactly as real ones, and reports the receiver's answer. Always 200; ok says whether it worked.
- [List tickets](https://docs.firetone.com.au/api-reference/tickets/list-tickets.md): Requires tickets:read AND the tickets app enabled for the organisation. A disabled app answers 403 rather than an empty list — absent, not merely hidden in the nav. Sort keys: created_at, updated_at, ref, status, priority.
- [Raise a ticket](https://docs.firetone.com.au/api-reference/tickets/raise-a-ticket.md): Always recorded with source 'human'. Nothing may claim that except this path: the action handler records 'agent' or 'flow', and the distinction tells whoever picks the ticket up how much to trust the wording. A contact or team outside the caller's scope is refused — the foreign key proves the row ex…
- [One ticket](https://docs.firetone.com.au/api-reference/tickets/one-ticket.md)
- [Update a ticket](https://docs.firetone.com.au/api-reference/tickets/update-a-ticket.md): resolved_at follows status rather than being set by the caller: two fields that must agree, only one of which anyone remembers to update.
- [Ticket history](https://docs.firetone.com.au/api-reference/tickets/ticket-history.md): Newest first. This is the record an agent reads back to the customer on their next call.
- [Add a note](https://docs.firetone.com.au/api-reference/tickets/add-a-note.md): Append-only: there is no PATCH and no DELETE for an update, because an edited history is not a history.
- [List voicemail messages](https://docs.firetone.com.au/api-reference/voicemail/list-voicemail-messages.md): Messages left when nobody could take the call. Recorded by FireTone rather than mod_voicemail, so a message carries the call it came from and the customer who left it. Transcription happens after the call and may lag by seconds; status is new, transcribing, ready or failed, and a failed message stil…
- [Get one voicemail message](https://docs.firetone.com.au/api-reference/voicemail/get-one-voicemail-message.md): The message with its transcript and summary, if transcription has finished.
- [Play a voicemail recording](https://docs.firetone.com.au/api-reference/voicemail/play-a-voicemail-recording.md): The WAV as recorded by the switch. Gated on voicemail:listen rather than voicemail:read: a transcript and a person's recorded voice are different disclosures.

## OpenAPI Specs

- [openapi-public](/api-reference/openapi-public.json)