Skip to main content

Getting started

You need a Retell workspace, a SIP carrier or PBX, and an account in the sipsandwich application.

1. Choose how your carrier authenticates​

Select the access model your provider supports:

  • IP authentication trusts traffic based on approved source IP addresses. No SIP username or password is required.
  • Registration has sipsandwich actively sign in to the carrier using REGISTER requests.
  • SIP digest authenticates individual calls when the carrier returns a 401 or 407 challenge.

See Carrier authentication for the exact information required by each model.

2. Connect Retell​

Add a Retell API key in the application, import or select an agent, and confirm the destination configuration shown by the wizard.

3. Assign a phone number​

Map an inbound number to a Retell agent. The routing layer validates tenant policy before forwarding signaling to Retell.

New phone-number imports use the actual number in Retell by default. US and Canadian 10-digit numbers, 11-digit numbers beginning with 1, and valid E.164 numbers are normalized to E.164. For example, 9412839002, 19412839002, and +19412839002 all import as +19412839002.

The optional Use a private Retell routing ID toggle starts off. Turn it on when you need a generated routing identifier instead of the actual number. Review the import preview before saving. If Retell rejects an actual-number import, the application reports the error instead of silently switching to a generated identifier.

Imports and subsequent updates put the number first in the Retell display name, for example +19412839002-sipsandwich.ai-Imported Number. Existing routing identifiers are preserved. Secondary workspace mappings and internal agent routes keep distinct private identifiers so calls reach the correct route.

4. Choose the inbound destination​

Open Numbers → your number → Routing and choose Retell, Custom SIP URI, or Saved provider connection. Custom inbound destinations are available to every workspace and plan and do not require a Retell API key.

For a custom SIP URI, enter a public IPv4 SIP endpoint such as sip:100@provider.example:5060;transport=tcp. The application validates the URI, rejects credentials and SIP headers, blocks private/reserved and sipsandwich edge addresses, and pins a public IPv4 next hop. A saved provider connection must be an enabled registered connection in the same workspace and is checked again when each call arrives. The inbound provider remains attached to the number, and returning to Retell is always available.

Custom destinations change inbound SIP signaling only. They do not add PBX features, accept device registrations, anchor media, or create a separate charge. Existing calls are unchanged when the setting is saved.

5. Test signaling​

Place a test call and use the call trace tools in the application to verify the SIP route and response codes.

Remove a Retell connection​

Removing a saved primary Retell API key or an additional workspace first deletes the phone-number imports that sipsandwich manages for that connection in Retell. This includes its internal agent routing numbers. Calls through those imports will stop working.

Review the deletion warning and explicitly acknowledge that the numbers will be deleted before confirming. The encrypted API key stays stored while cleanup runs and is removed from sipsandwich only after cleanup succeeds. If cleanup fails, the application keeps the key and shows an error so you can retry.

This removes the Retell imports associated with the selected connection. It does not cancel the underlying numbers with your carrier or delete your Retell agents and unrelated phone numbers.

Automate the supported tenant API​

Workspace owners can generate a tenant API token from Settings → Security → API access. Copy the ss_api_... value when it is created and send it as a bearer token:

curl https://api.sipsandwich.ai/api/v1/sip/trunks \
  -H "Authorization: Bearer $SIPSWICH_API_TOKEN"

The public reference is intentionally limited to stable automation for Retell connection and agent sync, SIP trunks, phone numbers, outbound call creation, call history, and bounded trace sessions.

Automate with developer tools​

The tenant API supports HTTP clients in any language, plus source packages for TypeScript/JavaScript, the CLI, and MCP hosts. See Developer tools for the shared bearer-token setup and the exact SDK, CLI, and MCP operations.