Placing calls
Your equipment places a Bird Voice call directly: your PBX (the system that places your calls) sends a call setup request, a SIP INVITE, to your trunk's SIP domain. Bird checks it and hands it to a carrier, and the two ends talk. This page covers what to have in place first, what Bird reads off the INVITE, and what the call costs.
Before you place a call
Four things have to be ready, in any order, and three of them are yours to set:
- A trunk that accepts your traffic. Create a SIP trunk and give it your equipment's IP ranges, an allowed API key, or both.
- A verified caller ID. Register the number you will present and complete its verification call, which is how a workspace proves it owns the numbers it presents.
- The destination country enabled. Turn on the countries you serve on the Destinations page.
- Routing attached to your workspace. Bird sets this up for you, choosing which carriers serve which destinations. Until it is in place, calls are refused with routing_not_configured, one of the reasons Rejected calls covers.
What Bird expects on the INVITE
Send the request to your trunk's SIP domain on one of its supported ports. Two headers carry everything Bird needs:
| Header | What Bird does with it |
|---|---|
| To | The number being called. Bird reads its country to choose a carrier and to price the call |
| From | The number you are presenting as the caller. It must be a verified caller ID in this workspace |
Use full international numbers in E.164 format, a leading + followed by the country code and national number, on both headers. That is the form Bird records on the call and the form its destination matching expects.
Beyond those two headers, this is an ordinary SIP call, with no custom headers either way.
Authenticating each call
What a call goes through depends on how the trunk is opened:
- IP allow list only. One request. Bird matches the source address against the list and routes the call, with no challenge to answer.
- Allowed API keys only. Bird asks the call for a password first, through the SIP Digest exchange.
- Both. The source address is checked before Bird challenges at all, so a call from an unlisted address is refused whatever credentials it carries.
Where the trunk has allowed API keys, your phone system answers with a hash of the API key secret rather than the secret itself, which is what SIP Digest authentication does:
- Your PBX sends the INVITE.
- Bird answers 407 Proxy Authentication Required with one challenge line per algorithm the trunk offers, SHA-256 then MD5 by default.
- Your PBX re-sends the INVITE with a Proxy-Authorization header computed with username bird and the API key's secret as the password.
- Bird verifies the answer and continues routing.
One detail catches people out: a pre-emptive Proxy-Authorization (sent before any challenge) never sees the offer, so the algorithm your equipment picked has to be one the trunk offers, and on a trunk that also has an allow list it still has to come from a listed address.
Bird answers a failed handshake at the SIP layer, so the attempt is turned away before there is a call to record. If your calls are absent from the Call log entirely, look at the credentials rather than the routing.
Call attestation
Calls to the United States and France carry STIR/SHAKEN attestation, the signature carriers in those countries use when deciding whether to put a call through unlabeled. It applies to every such call with nothing for you to configure. Calls carry level B by default. Level A, the strongest attestation, is available on request: contact support.
When a call is refused
Bird checks the caller ID, the destination, your limits, and your balance before dialing a carrier. Those refusals reach your phone system as a plain SIP 503, so the details never travel back to a caller Bird has not authenticated. The specific reason lands on the call record, where you can read it: open the call in the Call log, or see Rejected calls for the full list and what to change for each.
Retrying a refused call only helps once the cause is gone, so read the reason before you retry: a call refused for calls_per_second_exceeded gets the same answer until you slow the dial rate.
Cost and billing
Voice is prepaid from your organization's wallet, like the other channels:
- Billable time runs from answer to end, however long a call rang first. The call record shows it alongside Total duration, which runs from the moment Bird received the call.
- The rate depends on the destination country. Calls are priced per country from your rate card, in your wallet's currency. Each rate carries a billing increment: a minimum billed time, then the step it rounds up to after that. A rate with a one-minute minimum and six-second steps charges a 10-second call for a full minute.
- The wallet is checked before the carrier is dialed. A call your balance cannot cover is refused with insufficient_balance up front rather than billed to you afterwards. Keep a buffer, or turn on automatic top-ups.
- A daily voice spend limit applies. Past it, calls are refused with daily_spend_exceeded until the next UTC day starts. The amount depends on your plan.
- Cost appears on the call once it has been rated, at full precision, net of tax.
To total spend across calls, export the filtered call list as CSV from the Calls page, or read your invoices and usage.
Next steps
| Page | What it covers |
|---|---|
| Call log | Browsing, filtering, and exporting your call records |
| Voice events | Getting call outcomes pushed to your own systems |
| Payment methods & wallet | Topping up, automatic top-ups, and how the wallet is drawn down |