Placing calls

​

Click-to-call

curl -X POST https://api.your-host/api/v1/calls \
  -H "authorization: Bearer $FIRETONE_KEY" -H 'content-type: application/json' \
  -H "Idempotency-Key: task-8812" \
  -d '{
    "from": { "user_email": "dana@acme.com.au" },
    "to": "+61412345678",
    "reference": "crm-task-8812",
    "callback_url": "https://crm.acme.com.au/firetone/calls"
  }'

1. Dana’s phone rings first. The response comes back once she answers (up to 30 seconds), with the call_uuid.
2. When she answers, the number is dialled.

​

An AI agent calls someone

curl -X POST https://api.your-host/api/v1/calls/ai \
  -H "authorization: Bearer $FIRETONE_KEY" -H 'content-type: application/json' \
  -d '{
    "profile_id": "7c1e…",
    "to": "+61412345678",
    "caller_id": "+61298765432",
    "variables": { "name": "Sam", "interest": "teeth whitening", "enquired": "yesterday" },
    "reference": "lead-5521",
    "callback_url": "https://crm.acme.com.au/firetone/calls"
  }'

• It answers 202 straight away, with a request_id. The call is dialled in the background.
• The agent follows its profile. It uses its role, SOP, knowledge and rules, and it knows it made the call. The variables are in its brief as what it knows about this call.
• caller_id must be one of your numbers. You can leave it out if you have only one.
• When the call ends, conversation.completed brings the summary and any review flags, and call.ended brings the outcome.
• If nobody answers, call.failed comes with the reason: no_answer, busy, invalid_number, and so on.

• the number is one of your own;
• no route reaches it;
• billing refuses it;
• no virtual agent uses the profile.

​

Try it first: dry_run

• the phone that should ring first is registered;
• the number resolves;
• a route reaches it;
• there’s credit for it;
• the agent exists.

{ "dry_run": true, "plan": { "to_e164": "+61412345678", "caller_id": "+61298765432", "agent": "Ava", "trunk": "Carrier A", "max_seconds": 3600 } }

​

Hearing how it went

​

Callbacks

• What every event carries: your reference and the request_id.
• How they’re signed: with your organisation’s callback secret. Create it once with POST /integration/callback-secret (the secret is shown once), and verify X-FireTone-Signature exactly as for webhooks. A callback_url sent before the secret exists is refused with 409 no_callback_secret.
• Delivery: retried like webhooks. GET /calls/{uuid}/callbacks lists what was sent.

​

Asking

• GET /call-requests/{request_id} returns dialing, connected (with the call_uuid), completed, or failed (with why).
• GET /calls/{call_uuid} returns the call itself: live while it lasts, and from its record afterwards. That includes your reference and the recording’s URL.