Quickstart

1. Make an integration key

In your panel, open Developer → API keys → New key:

Kind: Integration. The key belongs to your organisation and keeps working when staff change.
What it may do: Click-to-call.
Allowed IP addresses: the public address your code will call from. Add my current address fills in yours if you’re running the code from where you are now.

Copy the secret; it’s shown once.

export FIRETONE_KEY=ft_…
export API=https://api.firet.one/api/v1

2. Ask who you are

curl $API/auth/me -H "authorization: Bearer $FIRETONE_KEY"

You get your organisation and the permissions the key holds.

403 ip_not_allowed: the request came from an address the key doesn’t list.
401: the key was copied wrongly.

3. Get somewhere to receive callbacks

Developer → Callback inbox → New inbox gives you a URL that keeps what it’s sent.
Developer → Webhooks & callbacks → Callback signing secret → Create creates the secret callbacks are signed with.

4. Place a call, dry first

curl -X POST "$API/calls?dry_run=true" \
  -H "authorization: Bearer $FIRETONE_KEY" -H 'content-type: application/json' \
  -d '{ "from": { "extension": "1001" }, "to": "+61412345678" }'

The dry run checks everything a real call would, and places nothing:

the extension has a phone that can ring;
the number resolves;
a route reaches it;
there’s credit.

Then drop dry_run and add your own id and the inbox:

curl -X POST $API/calls \
  -H "authorization: Bearer $FIRETONE_KEY" -H 'content-type: application/json' \
  -H "Idempotency-Key: quickstart-1" \
  -d '{ "from": { "extension": "1001" }, "to": "+61412345678",
        "reference": "quickstart-1", "callback_url": "<your inbox URL>" }'

Extension 1001 rings. When it answers, the number is dialled.

5. Watch it arrive

The inbox shows call.started, call.answered and call.ended, each with "reference": "quickstart-1" and marked signed: callback secret. That’s exactly what your receiver will get. Check the signature the same way:

const crypto = require("crypto");
function verified(secret, header, rawBody) {
  const { t, v1 } = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const mac = crypto.createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
  return Math.abs(Date.now() / 1000 - Number(t)) < 300 && v1?.length === mac.length &&
    crypto.timingSafeEqual(Buffer.from(mac), Buffer.from(v1));
}

Placing calls: AI calls and following a call.
Running campaigns from your system.
Webhooks for everything else that happens.
Errors and what to do about each.

Start

Building

Tools

API reference

1. Make an integration key

2. Ask who you are

3. Get somewhere to receive callbacks

4. Place a call, dry first

5. Watch it arrive

Next

​1. Make an integration key

​2. Ask who you are

​3. Get somewhere to receive callbacks

​4. Place a call, dry first

​5. Watch it arrive

​Next

1. Make an integration key

2. Ask who you are

3. Get somewhere to receive callbacks

4. Place a call, dry first

5. Watch it arrive

Next