diff --git a/agents/telephony/byo-sip.mdx b/agents/telephony/byo-sip.mdx new file mode 100644 index 0000000..9024ae8 --- /dev/null +++ b/agents/telephony/byo-sip.mdx @@ -0,0 +1,205 @@ +--- +title: "Bring Your Own Number" +description: "Import a number you already own by pointing your carrier's SIP trunk at Fish Audio: no rental fee, no telephony charges" +icon: "phone-plus" +--- + +If your numbers already live at a carrier, you can connect them to your agents without porting anything. Point the carrier's SIP trunk at Fish Audio and import the number: it stays with your carrier, who keeps billing you for the telephone-network legs, and on Fish Audio the calls bill as ordinary agent sessions. Imported numbers carry no monthly rental and no telephony charges of any kind: no phone surcharge, no transfer fees, agent minutes only. + +This works with any carrier or PBX that speaks SIP trunking: Twilio Elastic SIP Trunking, Asterisk or FreePBX, and most SIP providers. It is also the only way to use non-US/CA numbers, which the purchasable inventory does not cover. + +## How it works + +- **Inbound**: your carrier routes calls for the number over its trunk to Fish Audio's SIP endpoint. The platform matches the dialed number and hands the call to the agent bound to it; from there it is a normal [inbound call](/agents/telephony/inbound-calls). +- **Outbound** (optional): give the import a termination host and the platform can also place calls from the number. Outbound calls and warm-transfer consult legs dial out through your trunk, with the imported number as the caller ID. + +The SIP endpoint to point your trunk at: + +```text Origination URI +sip:1pv316az391.sip.livekit.cloud;transport=tcp +``` + +## Prerequisites + +- A number at your carrier and access to its SIP trunk configuration. +- Team owner or admin role (console), or an API key. + +## Import the number + +### In the console + +On the workspace **Phone numbers** page, choose **Import number**. Enter the number in E.164 format, set at least one inbound authentication factor, and optionally fill in the **Outbound calling (termination)** section. The same form is available later from the number's row menu as **Edit configuration**. + +### Through the API + +Import with the same endpoint that purchases numbers, using the `sip` provider variant: + +```bash Request +curl --request POST https://api.fish.audio/v1/agent/phone-numbers \ + --header "Authorization: Bearer $FISH_API_KEY" \ + --header "Content-Type: application/json" \ + --data '{ + "provider": "sip", + "phone_number": "+14155550123", + "label": "Main line (our carrier)", + "inbound_auth_username": "fish-inbound", + "inbound_auth_password": "long-random-password", + "inbound_allowed_addresses": ["203.0.113.0/24"], + "termination_uri": "pbx.example.com", + "termination_transport": "tcp", + "termination_auth_username": "fish-outbound", + "termination_auth_password": "another-long-password" + }' +``` + +Returns `201` with the number object. Imported numbers land in your default workspace, like purchases. + +| Field | Description | +| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | +| `provider` | Required: `sip`. | +| `phone_number` | Required: the E.164 number you own at the carrier. | +| `label` | Optional free-form label, up to 120 characters. | +| `agent_id` | Optional: bind an agent so the number answers right away. | +| `inbound_auth_username` | SIP digest username your trunk authenticates with; requires the password. | +| `inbound_auth_password` | The matching digest password. | +| `inbound_allowed_addresses` | IP addresses or CIDR ranges allowed to send calls for this number, up to 32. | +| `termination_uri` | Optional: your trunk's termination host as a bare `hostname[:port]`, without the `sip:` prefix. Enables outbound calls and warm transfers. | +| `termination_transport` | `auto` (default), `udp`, `tcp`, or `tls`. | +| `termination_auth_username` | Optional digest username for your termination; requires the password and a `termination_uri`. | +| `termination_auth_password` | The matching digest password. | + +At least one inbound factor (digest credentials and/or allowed addresses) is required; a `422` reports what is missing. A `409` means the number is already on the platform. A `502` means trunk provisioning failed; the number stays visible with status `error` and is safe to release and retry. + + + Digest passwords are stored only in the underlying trunk objects and are never + echoed back by the API. + + +## Inbound authentication + +The SIP endpoint is shared, so an import must prove that calls really come from your trunk: + +- **Digest credentials**: the platform challenges your trunk and verifies the username and password. Use this whenever your carrier or PBX answers digest challenges (Asterisk, FreePBX, most SIP providers). +- **Allowed source addresses**: calls are only accepted from the listed IPs or CIDR ranges. Use this for carriers that do not authenticate their origination traffic; Twilio Elastic SIP Trunking is one, so for Twilio this is the required factor. + +Set both when your carrier supports it. + +## Carrier walkthroughs + +### Twilio Elastic SIP Trunking + + + + In the Twilio console, under **Elastic SIP Trunking**, create a trunk (or + reuse an existing one). + + + Add an origination URI: `sip:1pv316az391.sip.livekit.cloud;transport=tcp`. + + + On the trunk's **Numbers** tab, add the phone number. Twilio routes its + calls through the trunk from then on. + + + Twilio's origination does not answer digest challenges, so authenticate by + source address: allow Twilio's published signaling IP ranges for the regions + you use (see [Twilio's IP address + list](https://www.twilio.com/docs/sip-trunking/ip-addresses)). In the + console, the **Twilio Elastic SIP Trunking preset** button fills the ranges + and sets the transport for you. + + + On the trunk's **Termination** tab, note the termination SIP URI + (`yourprefix.pstn.twilio.com`) and attach a **Credential List**. Pass the + host as `termination_uri` and the credentials as `termination_auth_username` + and `termination_auth_password`. Credentials are required here: Fish Audio's + outbound traffic does not come from fixed IPs, so Twilio IP access control + lists cannot authorize it. + + + For [cold transfers](/agents/telephony/transfers), enable **Call Transfer + (SIP REFER)** in the trunk's settings so Twilio honors the handoff. + + + +### Asterisk, FreePBX, and other SIP platforms + +- Route the number's inbound calls to `sip:1pv316az391.sip.livekit.cloud;transport=tcp`. +- Configure digest credentials on the trunk and pass the same pair as `inbound_auth_username` and `inbound_auth_password`; add your PBX's public IPs to `inbound_allowed_addresses` for defense in depth. +- For outbound, expose a termination host reachable from the internet and pass it as `termination_uri`, with digest credentials if your PBX requires registration or authentication. + +## Outbound calls and transfers + +What an imported number can do depends on whether you configured a termination: + +| | Inbound-only (no `termination_uri`) | With termination | +| ------------------ | --------------------------------------- | --------------------------------------------- | +| **Inbound calls** | Yes | Yes | +| **Cold transfers** | Yes, when your carrier honors SIP REFER | Yes, when your carrier honors SIP REFER | +| **Warm transfers** | No | Yes; the consult leg dials through your trunk | +| **Outbound calls** | No | Yes; caller ID is the imported number | + +The number object reports this as `supports_outbound`. + +## Update the configuration + +Change any part of an imported number's trunk configuration in place: rotate digest credentials, adjust the allowed addresses, or add, change, and remove the termination. In the console, open **Edit configuration** from the number's row menu; over the API, `PUT` the full desired configuration: + +```bash Request +curl --request PUT https://api.fish.audio/v1/agent/phone-numbers/$PHONE_NUMBER_ID/sip-config \ + --header "Authorization: Bearer $FISH_API_KEY" \ + --header "Content-Type: application/json" \ + --data '{ + "inbound_auth_username": "fish-inbound", + "inbound_auth_password": "", + "inbound_allowed_addresses": ["203.0.113.0/24", "198.51.100.7"], + "termination_uri": "pbx.example.com", + "termination_transport": "tls", + "termination_auth_username": "fish-outbound", + "termination_auth_password": "" + }' +``` + +The body is the import payload without `phone_number`, `label`, and `agent_id`, and it replaces the whole configuration. Two conveniences: + +- An empty password next to a set username keeps the stored password, so you can edit other fields without re-entering secrets. Setting a username for the first time requires a password. +- An empty `termination_uri` removes the termination and makes the number inbound-only again. + +Updates apply in place: routing is never interrupted, and calls already in progress are unaffected. The response is the updated number object; for imported numbers it carries the non-secret configuration (`inbound_auth_username`, `inbound_allowed_addresses`, `termination_uri`, `termination_transport`, `termination_auth_username`) alongside `supports_outbound`. + +## Billing + +Imported numbers are free on Fish Audio: no monthly rental, no phone surcharge, no transfer fees. Calls on them bill as agent minutes only, like web sessions. Your carrier continues to bill you directly for its side of the traffic. + +## Release + +Releasing an imported number (`DELETE /v1/agent/phone-numbers/$PHONE_NUMBER_ID`) disconnects it from Fish Audio and returns `204`. The number itself stays yours at the carrier; you can import it again later. + +## Going further + + + + What happens when someone dials a bound number. + + + Cold and warm handoffs to a human. + + + The shared lifecycle: list, bind, label, release. + + + API keys and workspace scoping for every request. + + diff --git a/agents/telephony/phone-numbers.mdx b/agents/telephony/phone-numbers.mdx index 74a449b..e3a4a73 100644 --- a/agents/telephony/phone-numbers.mdx +++ b/agents/telephony/phone-numbers.mdx @@ -4,7 +4,7 @@ description: "Search, purchase, bind, and release phone numbers for your agents icon: "phone" --- -Phone numbers connect your agents to the telephone network. Each number lives in a workspace within your team (purchases land in your default workspace) and is bound to at most one agent: calls to the number are answered by that agent. The `/v1/agent/phone-numbers` API covers the whole lifecycle: search the purchasable inventory, buy a number, bind it to an agent, and release it when you no longer need it. +Phone numbers connect your agents to the telephone network. Each number lives in a workspace within your team (purchases land in your default workspace) and is bound to at most one agent: calls to the number are answered by that agent. The `/v1/agent/phone-numbers` API covers the whole lifecycle: search the purchasable inventory, buy a number (or [import one you already own](/agents/telephony/byo-sip)), bind it to an agent, and release it when you no longer need it. ## Search available numbers @@ -17,11 +17,11 @@ curl "https://api.fish.audio/v1/agent/available-phone-numbers?country_code=US&ar The response is an `available_phone_numbers` array of inventory entries forwarded from the provider: number and region. -| Parameter | Description | -| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | -| `country_code` | ISO 3166-1 alpha-2 country code, `US` (default) or `CA`. | -| `area_code` | Restrict results to one area code, like `415`. | -| `number_type` | `local` (default). The managed inventory is US and Canada local numbers only; `toll_free` returns `400`. | +| Parameter | Description | +| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | +| `country_code` | ISO 3166-1 alpha-2 country code, `US` (default) or `CA`. | +| `area_code` | Restrict results to one area code, like `415`. | +| `number_type` | `local` (default). The managed inventory is US and Canada local numbers only; `toll_free` returns `400`. | | `provider` | Inventory to search. Only `twilio` (the default) is available: managed numbers with [call transfer](/agents/telephony/transfers) support. | @@ -46,15 +46,21 @@ curl --request POST https://api.fish.audio/v1/agent/phone-numbers \ Returns `201` with the number object, the same shape the list endpoint returns. The number lands in your default workspace, and its monthly price is billed in daily slices. -| Field | Description | -| -------------- | ------------------------------------------------------------------------ | +| Field | Description | +| -------------- | ----------------------------------------------------------------------- | | `provider` | Required: `twilio`, the inventory the number came from. | | `phone_number` | Required: an E.164 number from the search response. | -| `label` | Optional free-form label, up to 120 characters. | +| `label` | Optional free-form label, up to 120 characters. | | `agent_id` | Optional: bind an agent so the number answers inbound calls right away. | A `409` means the number is already on the platform; a `502` means the provider refused the purchase; the number stays visible with status `error` and is safe to release. + + Already have a number at your own carrier? The same endpoint imports it with + `provider: "sip"` instead of buying one: no rental fee, no telephony charges. + See [Bring your own number](/agents/telephony/byo-sip). + + ## List your numbers Returns your team's phone numbers across its workspaces, newest first; each carries its `workspace_id`. @@ -82,7 +88,7 @@ curl https://api.fish.audio/v1/agent/phone-numbers \ | Field | Description | | ----------------- | ---------------------------------------------------------------- | -| `phone_number_id` | Unique identifier; use it in URL paths | +| `phone_number_id` | Unique identifier; use it in URL paths | | `phone_number` | The number in E.164 format | | `provider` | Telephony provider backing the number | | `label` | Free-form label you assign | diff --git a/agents/telephony/transfers.mdx b/agents/telephony/transfers.mdx index be8df08..ea75194 100644 --- a/agents/telephony/transfers.mdx +++ b/agents/telephony/transfers.mdx @@ -8,16 +8,16 @@ When a caller needs a person, the agent can transfer the call. Configure a desti Two modes decide what the handoff feels like: -| | Cold | Warm | -| ------------------------------ | ----------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| **Handoff** | The agent announces the transfer and drops out; the carrier connects the caller to the destination. | The caller waits on hold while the agent briefs the human on a private call, then the two are connected. | -| **What the human hears first** | The caller, directly. | The agent's briefing: who is calling and what they need. | +| | Cold | Warm | +| ------------------------------ | ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **Handoff** | The agent announces the transfer and drops out; the carrier connects the caller to the destination. | The caller waits on hold while the agent briefs the human on a private call, then the two are connected. | +| **What the human hears first** | The caller, directly. | The agent's briefing: who is calling and what they need. | | **Recording & analysis** | Stop at the handoff: nothing after it appears in [post-call analysis](/agents/monitor/post-call-analysis). | Recording continues after the human joins, capturing the full call audio; the transcript (and therefore analysis) covers only the agent's segment, up to the merge. | ## Prerequisites - A phone number bound to your agent, answering inbound calls. See [Inbound calls](/agents/telephony/inbound-calls). -- The number must support transfers. Numbers purchased from the platform inventory (`provider: "twilio"`) do; see [Phone numbers](/agents/telephony/phone-numbers). +- The number must support transfers. Numbers purchased from the platform inventory (`provider: "twilio"`) do; see [Phone numbers](/agents/telephony/phone-numbers). [Imported SIP numbers](/agents/telephony/byo-sip) support cold transfers when the carrier honors SIP REFER, and warm transfers when a termination is configured. ## Configure a destination @@ -62,7 +62,7 @@ curl --request PATCH "https://api.fish.audio/v1/agent/agents/$AGENT_ID/config" \ | `type` | Destination type; `phone` is the only value today and the default. | | `label` | Name for the destination, shown in the Builder. At most 64 characters. | | `phone_number` | The destination in E.164 format, for example `+14155550123`. | -| `mode` | `cold` (default) or `warm`; see the comparison above. | +| `mode` | `cold` (default) or `warm`; see the comparison above. | | `warm_connect` | Warm only: `confirm` (default) waits for the human's go-ahead before connecting; `direct` connects right after the briefing. | Destination numbers must be E.164 and are limited to a set of supported countries. A number outside the list is rejected with `422 Unprocessable Entity` and an error naming the allowed country codes. The transfer card in the console shows the current list. @@ -74,8 +74,8 @@ Configuring a destination is what enables the built-in `transfer_call` tool: an The built-in instructions are conservative: the agent transfers only when the caller asks for a person, or when the request clearly needs one and the agent cannot help further. - Use the system prompt to sharpen the escalation policy, for example - "Transfer to a human whenever the caller mentions a refund." See + Use the system prompt to sharpen the escalation policy, for example "Transfer + to a human whenever the caller mentions a refund." See [Tools](/agents/build/tools) for how the agent chooses between its tools. diff --git a/docs.json b/docs.json index 1d6b003..1d5dd88 100644 --- a/docs.json +++ b/docs.json @@ -117,6 +117,7 @@ "group": "Telephony", "pages": [ "agents/telephony/phone-numbers", + "agents/telephony/byo-sip", "agents/telephony/inbound-calls", "agents/telephony/transfers" ]