Placing calls
Your PBX sends a SIP INVITE to the trunk's SIP domain to place a call. Bird checks the request, routes it to a carrier, and relays the audio. This page covers the prerequisites, request fields, authentication, and cost.
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 enable outbound calling. Add your equipment's IP ranges, an allowed API key, or both. Clients that cannot hold a long-lived secret can use a session credential.
- A verified caller ID. Register the number you 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.
- Session credentials on. Bird challenges the call wherever it came from, even an address the allow list does not cover, and a credential it issued minutes earlier answers. Equipment already admitted by the allow list on a trunk with no allowed keys keeps connecting without a challenge.
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.
A preemptive Proxy-Authorization header is sent before the challenge, so your equipment must choose an algorithm that the trunk offers. If the trunk also has an IP allow list, the request must still come from a listed address.
Bird answers a failed handshake at the SIP layer, so the attempt is turned away before the platform creates a call 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. Carriers use this signature when labeling calls. Bird applies level B by default without additional configuration. Contact support to request level A.
When a call is refused
Bird checks the caller ID, destination, limits, and wallet balance before dialing a carrier. A refusal reaches your phone system as SIP 503; the specific cause stays on the authenticated call record. Open the call in the call log, or see rejected calls for each reason and resolution.
Resolve the recorded cause before retrying. For example, calls_per_second_exceeded continues until you slow the dial rate.
Emergency calls are not carried
Bird Voice does not carry calls to emergency services. A call to 112, 911, 999 or any other emergency number is refused, on every trunk, in every country. Your phone system must reach emergency services by another route.
This behavior does not depend on your plan, balance, or destinations. Configure your phone system to route emergency calls through a service that supports them, such as a local PSTN line, on-premises gateway, or another provider. Test that route. Bird returns 503 for a refused emergency call, allowing a phone system with another dial-plan route to try it.
Emergency services depend on the caller's registered location, which Bird does not store for a trunk. Do not rely on a Bird route for emergency calling.
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. Your rate card prices each country in the wallet's currency. A rate defines a minimum billed time and the increment used after that minimum. For example, a rate with a one-minute minimum and six-second increments bills a 10-second call as one 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 |