Skip to main content

SIP & other providers

Stellar integrates with phone systems using standard SIP (Session Initiation Protocol) connectivity. This enables integration with a wide range of telephony platforms beyond Twilio and Genesys.

Supported platformsโ€‹

Stellar's SIP integration works with most SIP-compatible systems, including:

  • Cloud PBX: RingCentral, 8x8, Vonage, Microsoft Teams (with SIP gateway), Cisco Webex Calling
  • On-premise: Cisco Unified Communications Manager, Avaya IP Office, Mitel MiVoice, FreePBX / Asterisk
  • SIP trunking providers: Bandwidth.com, Telnyx, Voxbone
note

If your platform supports standard SIP, it can likely integrate with Stellar. Contact the Stellar team to verify compatibility.

Prerequisitesโ€‹

Your phone systemโ€‹

  • SIP support for outbound calls
  • Admin access to configure SIP trunks or endpoints
  • Network connectivity to Stellar's SIP endpoint

Networkโ€‹

  • Firewall rules allowing:
    • SIP signaling: TLS 5061 (preferred) or UDP/TCP 5060
    • RTP media: UDP 10000โ€“20000
  • If behind NAT, ensure outbound UDP is allowed on the RTP port range
  • Sufficient bandwidth for expected call volume

Stellarโ€‹

  • Agent configured and tested in Studio
  • Per-environment configuration set up (secrets, variables, auth connectors)
  • Authentication configured: SIP credentials or IP-based trunk provider authentication (see Step 1 below)

Authentication methodsโ€‹

Stellar supports two methods for authenticating inbound SIP calls. You can use either method depending on your provider's capabilities.

SIP digest authenticationโ€‹

The standard method using username and password credentials. Your phone system authenticates using SIP digest auth (RFC 2617) on each call. This works with any SIP-compatible system.

IP-based authenticationโ€‹

For SIP trunk providers that send calls from known, static IP addresses, Stellar can authenticate based on the source IP alone โ€” no SIP credentials are needed. When an INVITE arrives without an Authorization header, Stellar checks the source IP against the trunk provider's allowed IP list. If it matches, the call is admitted immediately without a digest challenge.

This is useful for providers like Telnyx, Bandwidth, or on-premise SBCs with fixed public IPs where managing digest credentials adds unnecessary complexity.

tip

IP-based authentication and digest authentication can coexist. If a call arrives from an unrecognized IP without credentials, Stellar falls back to the normal digest challenge. Calls with credentials are always authenticated via digest auth regardless of source IP.

Setupโ€‹

Step 1: Configure authenticationโ€‹

Choose one of the following authentication methods:

Option A: SIP digest credentialsโ€‹

SIP credentials are used to authenticate your phone system when it connects to Stellar. Each credential uses SIP digest authentication (RFC 2617).

  1. Navigate to SIP credentials in Studio
  2. Click Add credential
  3. Enter a username (at least 8 characters, alphanumeric with dots, hyphens, and underscores)
  4. Enter a password (at least 8 characters)
  5. Optionally configure:
    • IP allowlist: If your PBX or SBC has a static IP address, restrict access to those IPs. This is a recommended best practice โ€” add your PBX's public IP address or CIDR range to prevent unauthorized use of the credential.
    • Require TLS: Enforce that connections using this credential must use TLS transport. Recommended for production.
  6. Save the credential

You can create multiple credentials, for example separate ones for development and production, or for different PBX systems.

Option B: IP-based authenticationโ€‹

If your provider sends calls from known static IPs:

  1. Navigate to Trunk providers in Studio (super admin access required)
  2. Create or edit a trunk provider
  3. Add the provider's public IP addresses or CIDR ranges to the Allowed IPs field (e.g. 203.0.113.10, 198.51.100.0/24)
  4. Save the trunk provider

No SIP credentials are needed on the provider side โ€” calls from the allowed IPs are authenticated automatically.

Step 2: Create an agent connector in Studioโ€‹

  1. Navigate to Phone connectors in Studio
  2. Click Add connector
  3. Select SIP as the type
  4. Enter a name for the connector
  5. Choose which agent should handle calls
  6. Select the environment (Development, Staging, or Production)
  7. Choose the version mode:
    • Published: Always uses the latest published version
    • Draft: Uses the current draft version
    • Pinned: Uses a specific agent version
  8. Ensure the Enabled toggle is on
  9. Save the connector

The connector generates a SIP URI in the format:

sip:{connector-identifier}@sip.stellarcs.ai

Step 3: Configure your phone systemโ€‹

Configure your phone system to route calls to Stellar:

  1. Create a SIP trunk pointing to sip.stellarcs.ai

    • Configure the transport: TLS on port 5061 is preferred; UDP or TCP on port 5060 is also supported
    • Set up authentication: digest credentials from Step 1 (Option A), or no credentials needed if using IP-based auth (Option B)
    • Set codec preferences to G.722 (preferred for HD voice quality) or G.711 (ฮผ-law or A-law)

  2. Set up call routing to direct calls to the trunk. There are two common approaches:

    Direct SIP URI dialing โ€” Your PBX dials the full SIP URI directly at some point in the dial plan:

    sip:123456789@sip.stellarcs.ai

    This is the simplest option if your system supports SIP URI destinations in its call routing.

    Prefix-based trunk routing โ€” Route calls matching a specific prefix to the Stellar trunk, stripping the prefix before sending. For example, with prefix 777:

    • User or IVR dials 777123456789
    • Dial plan matches the 777 prefix and strips it
    • The call is sent to the Stellar trunk as 123456789@sip.stellarcs.ai

    This approach is common with Asterisk, FreePBX, and other PBX systems that route by prefix to specific trunks. The remaining digits after the prefix must match your connector identifier.

    Either approach can be triggered conditionally โ€” for example, routing to Stellar when a queue times out, an IVR option is selected ("press 3 for AI assistant"), or after-hours routing activates.

Step 4: Prepare the networkโ€‹

  • Open firewall ports:
    • SIP signaling: TLS 5061 (preferred) or UDP/TCP 5060
    • RTP media: UDP 10000โ€“20000
  • If your PBX or SBC is behind NAT, ensure it can send and receive UDP traffic on the RTP port range. Stellar's gateway uses symmetric RTP, so it automatically learns your media address from incoming packets โ€” no special NAT configuration is typically needed on Stellar's side
  • Optionally enable QoS to prioritize voice traffic

Step 5: Test the integrationโ€‹

  1. Place a test call through your phone system
  2. Verify SIP connectivity and digest authentication succeeds
  3. Check audio quality in both directions
  4. Test conversation flow and actions
  5. Trigger a transfer and verify it completes

Once testing passes, start routing limited production traffic and scale up gradually.

SIP configuration referenceโ€‹

Endpointโ€‹

SIP URI:    sip:{connector-identifier}@sip.stellarcs.ai
TLS port:   5061 (preferred)
UDP/TCP:    5060
Auth:       IP-based (source IP matching) or SIP digest (RFC 2617, MD5)

Codecsโ€‹

CodecUse
G.722 (HD Voice)Preferred โ€” wideband audio
G.711 ฮผ-law (PCMU)North America
G.711 A-law (PCMA)International

G.722 provides significantly better audio quality (7 kHz bandwidth vs 3.4 kHz for G.711) and is offered as the preferred codec during SDP negotiation. The codec is negotiated automatically during call setup via SDP.

DTMFโ€‹

RFC 2833 telephone events (recommended and supported).

Media encryptionโ€‹

Stellar's SIP gateway supports SRTP for media encryption. The gateway is configured in opportunistic mode by default โ€” it offers SRTP to all clients, and clients that support SRTP will use it automatically. Clients without SRTP support connect with standard RTP.

For maximum security, configure your phone system to use both TLS (for SIP signaling) and SRTP (for media).

SIP headersโ€‹

The gateway extracts and forwards the following SIP headers to the AI agent as call context:

Standard headers:

  • From, To, Contact
  • User-Agent
  • Accept-Language (used for automatic language detection)
  • P-Asserted-Identity, Remote-Party-ID

Custom headers:

  • All X-* headers are forwarded (up to 32 headers, 1024 bytes per value)

This allows your phone system to pass additional context to the AI agent by setting custom SIP headers on the INVITE request.

Call transferโ€‹

When the AI agent determines a call should be transferred (e.g., to a human agent or another department), it initiates a SIP transfer. Stellar supports two transfer methods.

REFER transfer (blind)โ€‹

The gateway sends a SIP REFER to your phone system. Your system then dials the transfer target directly, and the gateway steps out of the media path.

This is the default transfer method. It works well when your PBX supports REFER and can handle the outbound leg independently.

INVITE transfer (attended)โ€‹

The gateway dials the transfer target in parallel while the AI continues the conversation with the caller. When the target answers, the AI disconnects and the gateway bridges RTP between the caller and the target.

This method is used as an automatic fallback when REFER is rejected, or when explicitly requested. It keeps the gateway in the media path but ensures the caller is never left in silence during the transfer.

Authentication for outbound transfersโ€‹

When using INVITE-based transfers (either directly or as a REFER fallback), the transfer target may require SIP digest authentication. You can configure this by attaching a SIP digest authentication connector to the handover action in Studio. The credentials are sent on the outbound INVITE only โ€” REFER transfers do not use them, since the remote PBX handles the outbound leg independently.

Context passing during transfersโ€‹

Transfer variables configured in Studio are passed as SIP X-* headers on the outbound REFER or INVITE. This allows your phone system to receive context about the call (e.g., caller intent, conversation summary, case ID) and route or display it accordingly.

Troubleshootingโ€‹

Call setup failuresโ€‹

  • Digest auth: Verify SIP digest credentials (username and password)
  • IP-based auth: Confirm your provider's public IP or CIDR range is listed in the trunk provider's allowed IPs
  • If using IP allowlists on credentials, confirm your PBX's public IP is included
  • If TLS is required on the credential, ensure your PBX connects on port 5061
  • Check network connectivity to sip.stellarcs.ai
  • Review SIP error responses (use SIP trace tools like Wireshark or sngrep)
  • Confirm the SIP URI and routing configuration

Audio problemsโ€‹

  • Check that RTP ports (UDP 10000โ€“20000) are open in both directions
  • Verify codec compatibility (G.722, G.711 ฮผ-law, or A-law)
  • Review NAT/firewall configuration for RTP traversal
  • Monitor for packet loss or jitter on the network path
  • If using SRTP, verify your PBX's SRTP configuration

Transfer issuesโ€‹

  • Validate the destination phone number or SIP address format
  • Test transfer destinations independently
  • Check firewall rules for inbound calls from Stellar
  • If REFER transfers fail, Stellar will automatically fall back to INVITE-based transfers

FAQโ€‹

Can I route SIP calls directly to a phone number connector?โ€‹

Yes. If you have SIP credentials configured for your tenant, you can dial a phone number connector's E.164 identifier as a SIP URI:

sip:+31201234567@sip.stellarcs.ai

The gateway authenticates your SIP credentials and resolves the dialed number to the matching phone number connector within your tenant. This is useful if you want to test phone number connectors from your own PBX without going through a trunk provider.