Voice troubleshooting
Start with the call log. The presence of a record and its fields determine which checks to follow.
An outgoing call is missing from the call log
A call Bird cannot admit is turned away at the SIP layer, before a record exists. Five things cause that:
- The trunk does not carry outbound calls yet. A new trunk carries no calls until you turn outbound calling on on its page, and it refuses every attempt until you do, whatever credentials the call presents.
- The trunk has no way to recognize you yet. A new trunk rejects every call until you add an IP range, an allowed API key, or session credentials.
- The call arrived from an address outside the trunk's IP allow list. Behind NAT, compare the router's public address with the trunk's IP allow list. The phone system's private address does not reach Bird.
- The password challenge failed. Check that the username is bird. The password must be an allowed API key secret or an unexpired session credential. The trunk must also offer the Digest algorithm that your phone system used.
- The call was addressed to a SIP domain Bird does not recognize. Copy the domain whole from the trunk page rather than assembling it.
The call is rejected with a rejection reason
Bird refused the call before dialing a carrier, and the reason names the check it failed. Open the call and use the rejection panel's link to the relevant setting. Rejected calls lists every reason and its fix.
caller_id_not_verified is the one a new client hits most, usually because the client puts the digest username where the caller ID belongs: the two are different fields.
The call is failed rather than rejected
Failed is not a refusal. The call was attempted and did not work, and SIP response carries the code that came back. A 486 is a busy number, a 404 an unallocated one. This usually points at the number you dialed rather than at your setup.
A call Bird refused is Rejected, not Failed, so filter the log on Rejected when you are looking for a call that failed one of Bird's checks.
The call is rejected with no rejection reason
On an outgoing call, the far end declined it outright and SIP response carries its code.
On an incoming call, the number that was dialed turned the call away, which fails no check and so names no reason. Open the call and read Inbound route: a reject route is a number that is not pointed at an answer. Receiving calls works through every inbound refusal from its route and reason.
The person you called saw a different number
The call has a record and no rejection reason, so it passed every check Bird makes. What went wrong is downstream of Bird: the terminating operator replaced the caller ID, or refused a call that presents it. The same cause shows up as a number that connects in one country and never connects in another.
Verification proves you control a caller ID. It does not oblige the operator that delivers the call to accept it, and operators apply their own national rules to a number that was not procured through Bird. See the CLI verification and delivery disclaimer for the practices involved, which include in-country CLI requirements, origin-based blocking, and do-not-originate lists.
To tell which kind of number you presented, open it under Voice > Numbers and read the panel at the top of its page. A number you bought from Bird shows its subscription, and so does one you bought and also verified. Only a number you own somewhere else shows a verification alone. A subscription means the number was procured through Bird, so the disclaimer does not govern it. Presenting a number procured through Bird is what raises delivery and completion rates on the destinations that reject a verified one.
An incoming call never reaches your phone system
The number answered the call, and the delivery is what failed. Check in this order:
- Read the call's Inbound route. It says which trunk or forward the number was pointed at when the call arrived. A reject route means the number was pointed at nothing, which is also where a number lands after its trunk is deleted or has inbound calling turned off.
- Check the trunk has a gateway. A trunk with no delivery gateway refuses every call to the numbers it answers, and the record reads no_route_found. Add one under Inbound calling on the trunk page.
- Check the gateway address. Bird dials the gateways in priority order and gives up when none answers. Confirm the SIP URI host, its port, and that your phone system accepts calls from Bird on it.
- For a forward, check the target is still verified. The forward target is re-checked on every call, so a caller ID you removed stops forwarding from that point.
Your client answers MD5 and gets nowhere
Some equipment mishandles a challenge that leads with SHA-256. Set the trunk to MD5 only.
Calls connect but audio is one-way
Your client is behind NAT, and its media is going to a private address. Enable NAT or STUN handling in the client.
Next steps
| Page | What it covers |
|---|---|
| Call log | Every field on a call record, and every rejection reason |
| SIP trunks | The IP allow list, keys, session credentials, and Digest |
| SIP client setup | The settings each softphone and PBX asks for |
| Placing calls | What Bird expects on the INVITE, and how the handshake runs |
| Receiving calls | Pointing a number at a trunk or a forward, and what it records |
Related resources
Continue with the documentation, guides and examples for this topic. Resources are in English.
Understand the conceptWhat is a voice API?Explore the capabilityVoiceImplementation guideVoice overview
Get an implementation brief