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. Set Allow REFER transfers to match the trunk type. Leave it off for a standard PSTN carrier trunk; turn it on only for a PBX-style trunk whose remote system performs the transfer itself. New trunk providers default to off. See Call transfer for the details.
  5. 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. Optionally enter a SIP prefix — a short lowercase label (a-z, max 20 characters) prepended to the auto-generated numeric identifier. This makes the SIP URI more recognizable in your PBX dial plan, e.g. sip:mypbx1234567890@sip.stellarcs.ai instead of sip:1234567890@sip.stellarcs.ai.
  6. Choose which agent should handle calls
  7. Select the environment (Development, Staging, or Production)
  8. Choose the version mode:
    • Published: Always uses the latest published version
    • Draft: Uses the current draft version
    • Pinned: Uses a specific agent version
  9. For an inbound SIP connector, optionally enable Tenant SIP fallback to route tenant-authenticated SIP calls whose destinations don't match another connector. Enabling this replaces any current fallback for your tenant.
  10. Ensure the Enabled toggle is on
  11. Save the connector

The connector generates a SIP URI in the format:

sip:{prefix}{10-digit-identifier}@sip.stellarcs.ai

If no prefix is set, the identifier is just the 10-digit number.

Tenant SIP fallback routing​

The Tenant SIP fallback setting applies tenant-wide to inbound calls authenticated with your tenant's SIP digest credentials. You can designate one inbound SIP connector as the fallback. If you enable the setting on another connector, that connector replaces the current fallback.

Stellar resolves each tenant-authenticated destination in this order:

  1. An exact SIP connector identifier
  2. A phone number connector matching the dialed number
  3. The enabled tenant SIP fallback connector

An exact connector that exists but is disabled remains a rejected destination; the call doesn't continue to the fallback. A disabled fallback connector is also skipped, so an otherwise unmatched call is rejected.

The fallback doesn't apply to IP-based calls authenticated as shared trunk-provider traffic. Those calls continue to use the trunk provider's phone number routing.

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. Unless you configure the tenant SIP fallback described above, the remaining digits after the prefix must match a connector identifier or an assigned phone number.

    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, 512 bytes per value)
  • Values are sanitized before AI exposure: control characters are stripped, whitespace is normalized, and values are truncated to 256 characters
  • Headers whose values are empty after sanitization are preserved for debugging but not exposed to the AI assistant

This allows your phone system to pass structured metadata to the AI agent — for example, customer IDs, routing context, or locale preferences — by setting custom SIP headers on the INVITE request.

caution

Custom X-* header values are included in the AI assistant's context. Treat header content as untrusted input — do not rely on SIP headers alone to enforce security boundaries. Prompt injection via SIP headers (e.g., embedding instructions in header values) is mitigated by sanitization but not eliminated. For sensitive operations, use server-side validation rather than AI-level instructions passed through headers.

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.

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. It keeps the gateway in the media path but ensures the caller is never left in silence during the transfer.

This is the usual transfer method and works with any trunk. If the transfer target requires SIP digest authentication, attach an authentication connector to the handover action (see below).

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 suits a trunk whose remote side is a PBX that legitimately performs the transfer itself, for example a 3CX integration.

REFER is opt-in per trunk, controlled by the Allow REFER transfers setting on the trunk provider (managed by a super admin). Newly created trunk providers have it off; trunks that existed before the setting was introduced were left on to preserve their behavior. A REFER asks the carrier to re-originate the call toward the target and bill the new leg to the trunk account, so carrier-honored REFER is a toll-fraud vector on a PSTN trunk. Leave the setting off for standard PSTN carrier trunks and enable it only for a trunk whose remote system performs the transfer.

When Allow REFER transfers is off, any transfer that uses REFER on that trunk is blocked before anything reaches the carrier. The handover fails and is reported as a blocked destination. There is no automatic fallback to INVITE, so the agent tells the caller the transfer could not be completed. For trunks that do not allow REFER, select INVITE as the transfer method on the handover action.

Authentication for outbound transfers​

When using INVITE-based transfers, 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​

You can pass call context to your phone system as SIP X-* headers on the outbound REFER or INVITE. Configure outbound X-headers on the handover action in Studio to control exactly which headers are sent and use template expressions to populate their values. If no outbound headers are configured, the gateway falls back to mapping extra Parameters Schema fields to X-headers automatically.

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
  • A failed REFER transfer does not fall back to INVITE. If the trunk's Allow REFER transfers setting is off (the default for new trunk providers), the transfer is blocked before it reaches the carrier; select INVITE as the transfer method on the handover action instead

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.