Start with the failing direction: calls into Voiceflow, outbound API calls, audio after connection, or transfers. Keep the SIP response and the HTTP response separate; they describe different parts of a call.
Choose the symptom
Inbound calls do not reach the agent
Check the hostname, source authentication and agent assignment.
- Send the INVITE to the complete SIP address hostname from Creator. IP-literal destinations are dropped;
REGISTERreturns405. - Check the provider’s actual public source address against IPs. A NAT address can differ from the PBX’s local address. A bring-your-own trunk needs Inbound calls enabled.
- For Credentials or Both, configure the SIP digest username/password on the phone system. A
401challenge is part of digest authentication; repeated challenges or403after credentials require checking the username/password and source range. - Confirm the connection has an agent and the intended Environment/version. Unassigned connections do not start an agent conversation.
- Check production concurrency and credits if calls are rejected as busy or declined.
The API rejects an outbound call
Separate destination, configuration, credits and concurrency errors.
- 400 Invalid phone number: use E.164, or a 1–15 digit extension on Bring your own SIP. Voiceflow SIP does not accept extensions.
- 400 Connection not assigned: assign an agent.
- 400 Outbound not configured: check addresses, Caller ID and the credential requirements for that connection type.
- 400 Connection not ready: the service has no complete outbound provisioning; contact support with the connection ID if this persists.
- 404: verify the connection ID from Outbound call API → View; do not substitute the SIP hostname.
- 402: restore workspace credits. 429: wait for production call capacity.
For an authorization failure, use an API key with read access to the assigned project and its versions. See Outbound SIP calls.
The API returns 200 but the destination does not answer
Inspect the dial result on your phone system rather than retrying immediately.
HTTP 200 confirms acceptance of the dial request. Check the destination, provider routing, Caller ID policy and the PBX’s SIP response. A busy, declined or not-found response does not move to another gateway. Gateway failover applies to transport failures, 5xx and qualifying timeouts. Check call records before sending another request to avoid duplicate calls.
The call connects but audio is missing or one-way
Check the media path independently of SIP signalling.
Allow RTP/SRTP traffic between the phone system and the media addresses, using the ports negotiated in SDP. Check NAT mappings on the PBX and firewall. The SIP proxy is not the media relay; allowing only SIP signalling addresses is insufficient. See network and media.
An encrypted connection fails
Match SRTP audio with TLS signalling and a trusted gateway certificate.
With Encrypted audio (SRTP) on, inbound calls must use TLS on 5061 and SRTP. Non-TLS INVITEs return 403 TLS Required. Every outbound destination must also use TLS. For a TLS gateway, check its certificate chain is trusted by a public CA; a self-signed certificate is rejected. TLS signalling alone does not enable SRTP media.
A transfer ends the conversation
Check REFER support and the receiving destination.
For a SIP destination, confirm the PBX permits SIP REFER and can route the target URI. Check the provider’s rejection before retrying. Voiceflow ends the agent call when its transfer request fails; an accepted transfer request does not prove a human answered. Prototype outbound calls cannot forward. See Transferring SIP calls.
The caller appears anonymous or has the wrong identity
Check what your phone system supplies as the caller.
Inspect the SIP caller identity supplied by the provider. SIP addresses are reduced to their user part. Withheld or anonymous callers intentionally receive a unique anonymous- runtime ID per call. Changing the dialled number does not select another agent within the same connection.
Confirm the result
Repeat one test call under the corrected configuration. Confirm the assigned agent, both audio directions and a conversation in Transcripts. For outbound, verify the receiving phone actually rings and connects; HTTP acceptance alone is not the success check.
Collect diagnostic evidence
Include the connection ID, UTC test time, inbound/outbound direction, dialled destination, SIP response or HTTP status, and the matching Transcript when available. Redact API keys, SIP passwords and customer context headers. For missing SIP availability or the workspace’s signalling IP allowlist, contact your account manager.