A SIP connection gives your agent a SIP address that your own phone system, PBX or contact center can send calls to. Use it when your phone numbers stay with your current provider and you want a Voiceflow agent to answer some of those calls, place calls through your phone system, and transfer callers back to it.

Before you start

  • You need the Admin role in the workspace to create a SIP connection.
  • You need a voice agent to assign the connection to.
  • Your phone system must be able to send calls to a SIP hostname over UDP, TCP or TLS, and identify itself to Voiceflow with a fixed public IP address, a SIP username and password, or both.
  • For outbound calls and transfers, your phone system needs a SIP trunk that accepts calls from Voiceflow with a username and password, and a phone number to show as the caller ID.

Creating a SIP connection

  1. Open Phone numbers in the sidebar and click Create number.
  2. Under SIP, select Voiceflow SIP.
  3. Choose how Voiceflow recognizes calls from your phone system:
    • IPs: add the public IP address of your phone system, or a range like 198.51.100.0/24. Click + to add more addresses, one per row.
    • Credentials: enter a SIP username and SIP password. Your phone system uses them to answer Voiceflow’s authentication challenge.
    • Both: a call must come from one of the listed IP addresses and authenticate with the username and password.
  4. Enter a Label. It’s only shown in Voiceflow, your phone system doesn’t use it.
  5. To let the agent place calls through your phone system and transfer callers to it, turn on Outbound calls and transfers and fill in the fields described in Outbound calls and transfers. You can also do this later.
  6. Click Create.

The connection opens in the editor. Copy the SIP address shown at the top, for example 3f2c9a1e-5b7d-4e8a-9c61-2d4b8f0e7a13.sip.voiceflow.com. Every connection gets its own address, and it can’t be changed.

Sending calls from your phone system

Route the calls you want Voiceflow to handle to the SIP address. Every PBX or carrier configures this differently, but the settings are the same:

Always send calls to the hostname of the SIP address. Calls sent to an IP address instead of the hostname are not answered.

Put the caller’s number in the From header. Voiceflow uses it to identify the caller, see Caller identification.

Assigning the connection to an agent

A SIP connection answers calls only while it’s assigned to an agent. Calls to an unassigned connection are ended.

  • From the workspace: open Phone numbers in the workspace sidebar, click Assign in the Assigned to column, and pick a voice agent. Calls follow the agent’s traffic split on each environment’s published version.
  • From the agent: open Phone numbers in the agent’s sidebar, click Assign existing number, select the SIP connection, then choose an Environment and a Version (Draft or Published).

SIP connections route to environments the same way phone numbers do. See Routing calls to an environment.

Outbound calls and transfers

Turn on Outbound calls and transfers to let the agent call people through your phone system. Once it’s on, all of these fields are required:

Your trunk must accept calls from Voiceflow with these credentials. To start a call, use the Outbound call API.

Transferring callers to your phone system

When the agent forwards a call to a SIP address with the Call forward step or the call forward system tool, Voiceflow asks your phone system to take the call back with a SIP REFER. Your phone system must accept REFER requests for transfers to work. If it rejects the transfer, the call ends.

Verifying the connection

  1. Dial a number that your PBX routes to the SIP address, and check that the call connects.
  2. Open Transcripts and confirm the call is listed, with the caller’s number as the user.
  3. If outbound calls are on, click View in the Outbound call API column, enter your own number under Test call and click Call.

Troubleshooting

Calls to the SIP address aren't answered

  1. Check that your phone system sends the call to the full SIP address hostname, not an IP address.
  2. If the connection uses IPs or Both, check that the listed addresses match the public IP your phone system calls from. Phone systems behind NAT usually call from the router’s public IP.
  3. If the connection uses Credentials or Both, check the username and password on your phone system.
  4. Check that the connection is assigned to an agent.

Calls stopped working after several failed attempts

Repeated failed authentication attempts temporarily block the IP address they come from, for up to an hour. Fix the credentials or IP addresses, then wait before calling again.

Your phone system can't register

Voiceflow doesn’t accept REGISTER requests. Set the trunk up as a peer without registration, and send calls to the SIP address directly.

Callers show up as anonymous

Voiceflow takes the caller from the From header. When it’s withheld or anonymous, the caller gets a generated ID that starts with anonymous-. Send the caller’s number in the From header to identify callers.

Calls are rejected as busy

SIP calls share the concurrency limit of your phone numbers. When all slots are in use, or your workspace is out of credits, new calls are rejected. See your plan limits.

Transfers end the call

Your phone system must accept SIP REFER requests from Voiceflow. Check that REFER is allowed on the trunk and that the transfer destination exists on your phone system.

Editing or deleting a SIP connection

Click a SIP connection in Phone numbers to open the editor. Changes save automatically.

To stop using a connection, click the three dots menu next to it and select Delete. Your phone system won’t be able to send calls to that address anymore, and a deleted address can’t be recovered. If you create a new connection, update your phone system with its new SIP address.

Use the up and down arrow keys to select a result, Enter to open it, and Escape to close the search.