Voice API FAQ

Bird Voice lets you place calls to phone numbers over a SIP trunk. Your phone system connects to Bird, and Bird routes each call through a carrier to the public telephone network (the PSTN). You bring your own PBX or softphone; Bird handles the carrier leg.

About ten minutes. Create a SIP trunk, verify a caller ID, enable the destination country, and point your phone system at the trunk address. The first-call guide walks through the whole thing.

Three things on your side: a SIP trunk with your equipment allowed on it (by IP range or API key), a verified caller ID (the number you present as the caller), and the destination country enabled. Bird attaches routing to your workspace, which is the fourth prerequisite and happens on Bird's side.

No. Any SIP-capable phone system works: a softphone like Zoiper or Linphone on a laptop, a PBX like Asterisk or FreeSWITCH, or a commercial system like 3CX or FreePBX. Bird issues you a SIP domain, and you point your equipment at it.

Not yet. Browser-based calling over WebRTC is coming soon. Today, calls are placed from your own SIP equipment to Bird's trunk.

Per call, at a rate that depends on the destination country. 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.

Billable time runs from the moment the called number picks up to the moment the call ends. Ring time is not billed, so a call nobody answers costs nothing.

Prepaid, from your organization's wallet. Bird checks your balance before dialing the carrier, so a call your wallet cannot cover is refused up front with insufficient_balance rather than billed afterwards.

Yes. A daily voice spend ceiling applies per organization, resetting at the start of each UTC day. Past it, calls are refused with daily_spend_exceeded. The amount depends on your plan, and Bird can raise it on request.

Open the call in the call log. Cost appears on the record once it has been rated, at full precision, net of tax. For totals across calls, export the filtered call list as CSV from the Calls page, or check your invoices and usage.

Three ceilings: how many calls you may have in progress at once (concurrent calls), how many new calls you may start per second (calls per second), and how much you may spend on voice in a UTC day (daily spend). Each is set per organization, and the amounts depend on your plan.

The call is refused at setup, before a carrier is ever dialed. The call record names which limit was hit: concurrent_calls_exceeded, calls_per_second_exceeded, or daily_spend_exceeded. Your phone system sees a SIP 503.

Yes. Contact support to request a higher concurrent-call or calls-per-second ceiling. The daily spend ceiling depends on your plan and can also be raised.

Check which reason the call record carries. A dialer can hit calls_per_second_exceeded while nowhere near the concurrent-call ceiling, because the two limits are independent. Slow the dial rate and retry; retrying immediately gets the same answer.

A SIP trunk is the connection between your phone system and Bird. SIP (Session Initiation Protocol) is the language phone systems speak to set up calls, and a trunk is the line those calls travel over. Bird issues your workspace a trunk address, and you point your phone system at it.

Most workspaces need only one. Create more when you want separate access rules per site or per system, since the IP allow list, the allowed API keys, and the Digest settings are all per trunk.

The trunk's SIP domain (copied from the trunk page), the username bird, and the password (the secret of an API key allowed on the trunk). Send calls to the SIP domain on port 5060 (UDP), 5061 (TLS), or 5062 (TCP).

Yes, with an IP allow list, allowed API keys, or both. Add the public addresses your equipment sends SIP from, or require each call to authenticate with an API key via SIP Digest. Both take effect on the next call.

The trunk's SIP domain stops accepting new calls immediately. Calls already in progress continue, and the call records made through the trunk stay in your call log.

Your PBX sends the call, Bird answers with a 407 challenge, and your PBX re-sends the call with a Proxy-Authorization header computed from username bird and your API key's secret as the password. Your PBX sends a hash of the password, never the password itself.

SHA-256 and MD5. Bird offers SHA-256 first and MD5 second by default, and your PBX picks the first one it supports. If your equipment only handles MD5 and mishandles a challenge that leads with SHA-256, set the trunk to MD5 only.

Yes. When a trunk has both, the source address is checked before Bird challenges for a password, so a call from an unlisted address is refused regardless of the credentials it carries.

Add the new key to the trunk first, move your equipment over, then revoke the old one. Revoking or deleting a key removes its ability to authenticate immediately on every trunk that allowed it.

A caller ID is a phone number your workspace is allowed to present as the caller on outbound calls. Bird checks the calling number your equipment puts in the SIP From header against this list on every call, so calls go out only under numbers you have verified.

Add the number on the Trust page in E.164 format. Bird places a verification call to it immediately. Answer the call, hear a six-digit code, and enter it in the dashboard. You get five attempts, and the number becomes usable as soon as one is accepted.

Delete the caller ID entry and add the number again for a fresh verification call. That works whether the first call never arrived, the code went stale, or the attempts ran out.

Point it at a phone you can pick up for the minute the verification takes, then move it back. For a number that receives no calls at all, contact support.

From that moment, any call presenting that number is refused with caller_id_not_verified. Calls already in progress continue, and the call records that used the number stay as they are.

Toll fraud works by dialing expensive countries you never meant to call. The countries you enable are the ones you can run up a bill in, so leaving everything else off limits your exposure if someone breaks into your phone system.

Find the country on the Destinations page using the search box (matches by name or two-letter code) and switch its toggle on. The change applies from that moment.

Calls to high-risk countries are expensive, and whoever operates the number you dial earns a share of the cost. These are the countries an attacker targets if they break into a phone system. Leave them off unless you have business there, and check the rate before you enable one.

Contact support to have it opened for your account. Available means you can enable it; Not supported means Bird cannot currently place calls to that country from your account.

An available country can still have specific destinations inside it that routing does not reach yet. Send the call ID to support and they will extend the routing to cover it.

Two headers: To (the number being called) and From (the number you present as the caller, which must be a verified caller ID). Both must be full international numbers in E.164 format, a leading + followed by the country code and national number. No custom headers are needed.

STIR/SHAKEN is a signature carriers use when deciding whether to put a call through unlabeled. Calls to the United States and France carry it automatically with nothing for you to configure. Calls carry level B by default; level A (the strongest) is available on request.

Open the call in the call log. Your phone system sees a plain SIP 503, but the specific reason lands on the call record where only you can read it. A panel above the details names the cause and links to the setting that fixes it.

Only once the cause is gone. A call refused for calls_per_second_exceeded gets the same answer until you slow the dial rate. Read the rejection reason before retrying.

Five: Answered (the called number picked up), No answer (it rang out), Failed (the call did not complete, either Bird refused it or a carrier failed it), Rejected (the carrier declined the call outright), and Unknown (the outcome could not be determined).

Both appear as Failed. The rejection reason is what separates them: only a Bird refusal carries one. A failed call with a rejection reason points at a setting on your side or Bird's; one without a rejection reason usually points at the number you dialed.

Yes. The Live tab on the Calls page lists the calls on your trunks right now, with a count. A live call shows as either Ringing (waiting for the other side to pick up) or In progress (connected). The tab refreshes every few seconds.

Total duration runs from the moment Bird received the call to hangup. Billable time runs from answer to hangup. The gap is ring time nobody picked up, so a large gap is worth a look at what you are dialing. A call nobody answered costs nothing.

Three ways: download CSV from the Calls page (exports every record matching your current filters, not only the visible page), read them over the API with an API key scoped to voice:read, or use the Bird CLI with bird voice list.

Three: voice_call.initiated (Bird accepted the call and started routing), voice_call.answered (the called number picked up), and voice_call.ended (the call is over, with the outcome). An unanswered call never emits the answered event.

A call Bird refuses after accepting the INVITE still ends with voice_call.ended, carrying status failed and sip_response_code 503. So every call you hear about opening also closes. A call Bird cannot admit at all (turned away at the SIP layer) never produces any events.

Yes. Deliveries are not ordered, so answered can reach you after ended. Sort by the timestamp field, and let a later-arriving event with an earlier timestamp lose.

Deduplicate on the webhook-id HTTP header. Bird delivers at least once, and a call's initiated event can be published more than once when a signaling retry replays. Same call, same stage, same webhook-id.

They live on the call record, not in the event. A failed status on voice_call.ended does not tell you whether Bird or a carrier caused it. Open the call in the call log for the rejection reason, and the cost appears there once the call has been rated.

A call Bird cannot admit is turned away at the SIP layer, before a record exists. Check four things: the trunk has an IP range or API key allowing your equipment, the call arrived from an address on the trunk's IP allow list (behind NAT, that is the router's public address), the Digest credentials are correct (username bird, the right API key secret, an algorithm the trunk offers), and the SIP domain matches the trunk's domain exactly.

Open the call in the call log. The panel above the details names the cause and links to the setting that fixes it. The seven reasons you can fix are source_not_allowed, caller_id_not_verified, destination_not_enabled, insufficient_balance, daily_spend_exceeded, concurrent_calls_exceeded, and calls_per_second_exceeded.

Some equipment mishandles a challenge that leads with SHA-256. Set the trunk's Digest algorithm to MD5 only, and your PBX will get a challenge it understands.

Your client is behind NAT (a router or firewall that rewrites addresses) and the media is going to a private address the far side cannot reach. Turn on your client's NAT or STUN handling so it advertises its public address in the media offer.

It can be. Bird supports TLS on port 5061 for SIP signaling, so the call setup is encrypted in transit. UDP on 5060 and TCP on 5062 are unencrypted. Choose the transport your security requirements call for.

Every event is HMAC-signed. Verify the signature with your endpoint's secret before you act on the payload, and rotate that secret from the dashboard whenever you need to.

In the region your organization is hosted in, either us1 or eu1. Your API key carries it in its prefix (bk_us1_, bk_eu1_), which is how the SDKs and the CLI pick the right endpoint without you configuring one.

Only what you scope it to. A key carries a list of scopes, each at read or write. A key with voice:write can authenticate calls on a trunk; a key with voice:read can list call records. A key cannot reach channels or settings outside its scopes.

The specific reason goes onto the call record where only you can read it. Returning a generic 503 to the SIP layer keeps someone probing your trunk from learning which trunks, numbers, and destinations exist.

Certifications and security documentation live in the Trust Center at trust.bird.com. The data processing agreement, privacy statement, and acceptable use policy are published at bird.com/legal. For a vendor questionnaire, your Bird account team handles it.