Skip to main content

SIP Providers

SIP providers connect your phone numbers to VOCALS. They handle the PSTN (public telephone network) side of the call while VOCALS handles the AI conversation.

VOCALS supports two types of SIP connectivity:

  • Twilio -- Managed SIP with WebSocket Media Streams (simplest setup)
  • Generic SIP -- Any standard SIP trunk provider (Netelip, Zadarma, Telnyx, etc.) via Asterisk

Choosing a Provider Type​

TwilioGeneric SIP
Setup complexityLow (API credentials only)Medium (SIP trunk config)
Supported providersTwilio onlyAny SIP trunk provider
Inbound callsYesYes
Outbound callsYesYes
Audio protocolWebSocket Media Streams (mulaw)AudioSocket via Asterisk (slin/alaw)
CostTwilio pricingYour SIP provider's pricing

Setting Up Twilio​

Prerequisites​

  • A Twilio account with a phone number
  • Your Twilio Account SID and Auth Token

Steps​

  1. Go to Settings > SIP Providers in the VOCALS dashboard.
  2. Click Add SIP Provider.
  3. Select Twilio as the type.
  4. Enter your credentials:
    • Account SID -- Found in your Twilio Console dashboard. It always starts with AC followed by 32 hexadecimal characters (e.g., ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx). Anything else is rejected when you save.
    • Auth Token -- Found in your Twilio Console dashboard
    • Phone Number -- Your Twilio phone number in E.164 format, country code included (e.g., +34911234567). A number without a + and country code is rejected when you save it -- see Number Format.
  5. Click Save.
warning

Paste the Account SID, not your Twilio account email. Twilio uses the Account SID as the username when VOCALS places a call, so any other value makes every outbound call fail with an authentication error. VOCALS checks the format when you save -- if you see "That is not a Twilio Account SID", copy the value again from the Twilio Console.

Twilio Configuration​

After saving in VOCALS, configure your Twilio number to route calls to VOCALS:

  1. On the SIP Providers page, copy the Voice Webhook URL. It is shown on the provider card -- click it to copy -- and again in the edit panel when you open the provider. It looks like https://api.usevocals.com/voice/webhook?tenant_id={your_tenant_id}.
  2. In the Twilio Console, go to Phone Numbers > Manage > Active Numbers.
  3. Click on your number.
  4. Under Voice Configuration, set:
    • A call comes in: Webhook
    • URL: the Voice Webhook URL you copied
    • HTTP Method: POST
  5. Click Save configuration.

Twilio will now forward incoming calls to VOCALS via WebSocket Media Streams.

note

The Voice Webhook URL identifies your VOCALS account, not one provider, so it is the same on every SIP provider card. Providers that reach VOCALS over a registered SIP trunk (Netelip, Zadarma, and the rest) never call it -- it is only needed by webhook-based providers such as Twilio.

Numbers configured before this URL changed

The webhook used to be https://api.usevocals.com/twilio/voice?tenant_id=.... That address still works and will keep working indefinitely -- there is nothing to migrate. Both addresses answer the same way, so you only need the new one when configuring a number for the first time.

Setting Up Netelip​

Netelip is a European SIP trunk provider with coverage in Spain and Latin America.

Prerequisites​

  • A Netelip account with a DID (phone number)
  • Your SIP credentials from the Netelip control panel

Steps​

  1. Go to Settings > SIP Providers in the VOCALS dashboard.
  2. Click Add SIP Provider.
  3. Select Netelip as the type. This pre-fills the SIP server and port, but you can change them if needed.
  4. Fill in the connection details:
    • SIP Server -- Pre-filled as sip.netelip.com. Netelip also offers regional servers like sip-eu.netelip.com -- use whichever your account is configured for.
    • SIP Port -- Default 5060.
    • Transport -- UDP (default for Netelip).
    • Outbound Number Format -- Pre-filled as 00 prefix, which is what Netelip expects.
    • Username -- Your Netelip SIP username.
    • Password -- Your Netelip SIP password.
  5. Optionally configure inbound call filtering:
    • Allowed IPs -- Restrict which IP addresses can send calls to your trunk. Leave empty to allow all. Netelip's SIP servers typically send from their published IP ranges.
  6. Click Save.

After saving, VOCALS registers your trunk with the SIP server. Check the registration status badge on the SIP provider card:

  • Green (Registered) -- Trunk is connected and ready for calls.
  • Red (Unregistered) -- Registration failed. Check your credentials and SIP server address.
  • Yellow (Unknown) -- Status could not be determined. The trunk may still be initializing.

Netelip DID Configuration​

In your Netelip control panel, configure your DID to route calls to VOCALS:

  1. Log in to your Netelip account.
  2. Go to DID Numbers (or equivalent).
  3. Set the destination for your number to your VOCALS server's IP address on port 5060.
  4. Ensure the codec is set to G.711a (alaw) or G.711u (ulaw) -- VOCALS auto-detects both.

Setting Up a Generic SIP Provider​

Any SIP trunk provider that supports standard SIP registration can be used with VOCALS.

Prerequisites​

  • A SIP trunk account with your provider
  • SIP server address, port, and credentials
  • A DID (phone number) from your provider

Steps​

  1. Go to Settings > SIP Providers in the VOCALS dashboard.
  2. Click Add SIP Provider.
  3. Select Generic SIP as the type.
  4. Fill in the connection details:
    • SIP Server -- Your provider's SIP server hostname or IP (e.g., sip.provider.com).
    • SIP Port -- Usually 5060 for UDP/TCP.
    • Transport -- UDP or TCP depending on your provider.
    • Outbound Number Format -- How VOCALS writes the dialled number and caller ID when it hands the call to your carrier. See Outbound Number Format below.
    • Username -- Your SIP authentication username.
    • Password -- Your SIP authentication password.
  5. Add each DID from your provider under Phone Numbers, in E.164 format with the country code (e.g., +34930485412). A number without a + and country code is rejected -- see Number Format.
  6. Optionally configure inbound call filtering:
    • Allowed IPs -- Whitelist your provider's SIP server IPs to prevent unauthorized call injection.
    • Media Encryption -- Set to match your provider's requirements (none, sdes, or dtls).
  7. Click Save.

Common SIP Providers​

These providers are known to work with VOCALS. Configuration is similar across providers -- only the SIP server address and credentials differ.

ProviderSIP ServerDefault PortTransportOutbound Number FormatNotes
Netelipsip.netelip.com5060UDP00 prefixSpain/LATAM coverage. Also sip-eu.netelip.com.
Zadarmasip.zadarma.com5060UDPE.164 digitsGlobal coverage, competitive pricing.
Telnyxsip.telnyx.com5060UDP/TLSE.164 digitsGlobal, developer-friendly.
VoIP.msatlanta.voip.ms5060UDPE.164 digitsNorth America, many server locations.
OVHsip.ovh.net5060UDPE.164 digitsEurope, bundled with OVH hosting.
tip

When setting up a new SIP provider, start by making an outbound test call to verify audio quality and latency before configuring inbound routing.

Outbound Number Format​

Carriers disagree about how an international number should be written on the wire. VOCALS always stores your numbers in canonical E.164 (+441234567890); this setting only decides what it sends to your carrier when placing a call.

OptionDialled asUse it when
E.164 digits (default)441234567890Your carrier expects bare digits. This is what most wholesale carriers want.
00 prefix00441234567890Your carrier expects the European 00 international access code. Netelip and some other European trunks require this.

The same format is applied to the caller ID, which your carrier validates separately from the destination number.

If the format is wrong, the carrier rejects the call within a fraction of a second and it never rings. If your outbound calls fail instantly while the trunk shows as Registered, switch this setting and try again.

How SIP Calls Work in VOCALS​

For non-Twilio providers, VOCALS uses Asterisk as a SIP gateway:

Your SIP Provider (PSTN)
        |
   SIP trunk (registration + calls)
        |
   Asterisk (SIP gateway)
        |
   AudioSocket (binary audio protocol)
        |
   Bridge service (codec conversion)
        |
   WebSocket to VOCALS backend
        |
   STT -> LLM -> TTS pipeline
  1. Asterisk registers with your SIP provider and handles SIP signaling.
  2. When a call arrives (or is initiated), Asterisk opens an AudioSocket connection to the bridge service.
  3. The bridge converts between Asterisk's audio format (alaw/ulaw/slin) and the VOCALS backend WebSocket protocol.
  4. The backend runs the call through the same STT -> LLM -> TTS pipeline used for Twilio calls.

This architecture means all providers -- Twilio and generic SIP -- share the same AI pipeline. The only difference is the telephony transport layer.

Outbound Calls​

Both Twilio and generic SIP providers support outbound calls:

  1. Go to Calls in the dashboard, or use the API POST /api/v1/calls.
  2. Select the agent and phone number to call from.
  3. Enter the destination number.
  4. Click Call.

For generic SIP providers, outbound calls are routed through Asterisk. The caller ID is set to the phone number assigned to the agent making the call. Both the dialled number and the caller ID are written in the trunk's Outbound Number Format.

Answering Machine Detection (AMD)​

For outbound calls via generic SIP, VOCALS includes answering machine detection:

  • Asterisk analyzes the first few seconds of audio to determine if a human or machine answered.
  • If a machine is detected (voicemail greeting), the call is automatically hung up.
  • If a human is detected (or the result is inconclusive), the call proceeds normally.
  • As a fallback, the LLM also monitors for voicemail patterns during the conversation.

AMD is automatic for outbound calls -- no additional configuration is needed.

Registration Status​

After configuring a generic SIP provider, the dashboard shows the trunk's registration status:

  • Registered -- The trunk is connected to your SIP provider and ready for calls.
  • Unregistered -- Registration failed. Common causes:
    • Wrong SIP server address or port
    • Incorrect username or password
    • Firewall blocking SIP traffic (port 5060)
    • Provider account suspended
  • Unknown -- The status could not be determined.

Registration status updates automatically. After saving or editing a SIP provider, allow 10-30 seconds for the trunk to register.

Deleting a SIP Provider​

A SIP provider can only be deleted once none of its phone numbers are assigned to an agent. If any agent still holds one of them, the delete is refused and the confirmation dialog lists the agents standing in the way.

To go ahead, open each listed agent, remove or reassign its phone number, then delete the SIP provider again.

note

This is deliberate. Deleting a SIP provider an agent depends on would take that agent's number away with it, and the agent would simply stop receiving calls with nothing to show why.

Troubleshooting​

Registration Fails​

  1. Check credentials: Verify your SIP username and password match your provider's control panel.
  2. Check server address: Ensure the SIP server hostname resolves correctly. Try the IP address directly if DNS is suspect.
  3. Check port and transport: Most providers use UDP on port 5060. Some require TCP on port 5060. (TLS is not currently supported.)
  4. Check firewall: Your server must allow outbound traffic on the SIP port and UDP ports 10000-10100 (RTP media).

Outbound Calls Are Rejected Immediately​

The trunk shows as Registered, but every outbound call fails before it rings.

  1. Check the number format: set Outbound Number Format to match your carrier. Most carriers want E.164 digits; Netelip and some other European trunks want 00 prefix. See Outbound Number Format.
  2. Check the caller ID: your carrier will usually only let you present a number you own. Make sure the phone number assigned to the agent is a DID on that trunk.
  3. Check your account: some carriers block international destinations or require a balance top-up before outbound calls are permitted.

No Audio (One-Way or Silent Calls)​

  1. Check RTP ports: Ensure UDP ports 10000-10100 are open on your server's firewall for media traffic.
  2. Check NAT: If your server is behind NAT, ensure the public IP is correctly configured. VOCALS auto-detects this from the EXTERNAL_IP environment variable.
  3. Check codec: VOCALS supports G.711a (alaw), G.711u (ulaw), and signed linear (slin). Most providers default to G.711a in Europe and G.711u in North America.

Calls Connect but Agent Doesn't Respond​

  1. Check agent assignment: Ensure a phone number is assigned to the agent and the DID matches.
  2. Check the number format: the DID must be stored with its country code (+34930485412, not 930485412). A number saved without one cannot be matched to an agent, so the call connects to your account but never reaches the agent. See Number Format.
  3. Check providers: Verify the agent has valid STT, LLM, and TTS providers configured with working API keys.
  4. Check call logs: The dashboard shows detailed logs for each call, including any provider errors.

Echo or Feedback​

  1. Check jitter buffer: VOCALS applies an adaptive jitter buffer automatically. If echo persists, it may be on the SIP provider's side.
  2. Reduce TTS volume: Some TTS providers output audio at high volume that can cause echo on the PSTN side. Lower the gain if your provider supports it.