Addresses
An Address is how people and code reach a Resource on SignalWire. A caller dials a
phone number, a private branch exchange (PBX) sends a call to a SIP URI, or a browser dials a name
such as /public/support, and SignalWire hands the call to the Resource assigned to that Address.
That Resource is the Address’s handler.
Your own code uses the same Addresses to name a destination: the to of a call you create with
the REST API, the destination of connect in SWML, or the argument
to dial() in the Browser SDK.
Every Address has exactly one handler, and callers only ever see the Address. How a call reaches a Resource walks through the full path from the dialed Address to the Resource that answers.
Address types
Phone numbers
A phone number you’ve bought or ported gives you two Addresses, assigned independently: a calling Address whose handler takes inbound calls, and a messaging Address whose handler takes inbound messages. Assign a calling handler to start taking calls on the number.
Any Resource that can take a call can be a calling handler, such as an AI Agent, a SWML Script, a Call Flow, a Relay Application, a Subscriber, or a SIP Credential. A messaging handler is a Resource that runs messaging logic, such as a SWML Script created for messaging or a Relay Application.
SIP Addresses
A SIP Address gives a Resource its own SIP URI so devices and systems outside SignalWire, such as a PBX or your own carrier, can send it calls. SignalWire builds the host from your Space name and the domain you pick:
The user defaults to *, which accepts any username, so sip:anything@bayview-public.dapp.signalwire.com
reaches the same Resource. In the Dashboard, you type the domain in the Domain field, using up to
50 letters, numbers, and single hyphens. Through the REST API, the domain defaults to public. Each
user and domain pair is unique across your Space.
A SIP Address also carries its own settings:
A SIP Address carries calls only. It routes inbound SIP to its Resource, which makes it different from a SIP Credential, a Resource your own SIP devices register to and place calls from, and from a SIP Gateway, a Resource that connects your Space to an external SIP network. To bring calls in from your own carrier, give the handling Resource a SIP Address and point the carrier at it, as the bring your own carrier guide shows.
Aliases
An alias is a name in the form /<context>/<name>. SignalWire creates one from the Resource’s name
when you create the Resource, so an AI Agent named Ada that you add in the Dashboard is reachable
at /public/ada. A Subscriber’s alias comes from its display name, or from the part of its email
before the @ when it has none, so a Subscriber with the email john.doe@example.com is reachable
at /private/john-doe. Names use lowercase letters, numbers, underscores, and dashes, run up to
256 characters, and are unique within their context.
The context of that first alias depends on the Resource type. For the most common types:
The first alias of an AI Agent added in the Dashboard takes audio calls only. To reach an AI Agent
created with the REST API from a public call button on your website, add a public alias for it.
Add more aliases to expose the same Resource under other names or to shape how it’s reached. Each alias has these properties:
You can rename an alias, move it to another context, or change its channels and codecs at any time. Its Resource stays fixed. To put a different Resource behind a name, delete the alias and create one with the same name and context on the new Resource.
WhatsApp numbers
A WhatsApp business number connected to your Space can be assigned to a Resource so it handles inbound WhatsApp calls or messages. The number holds one Address at a time, for either calls or messages. The exception is a Relay Application assigned in the Dashboard, which takes both. Through the REST API, every assignment sets a single handler and removes the other, including for a Relay Application. WhatsApp onboarding covers connecting the number to your Space.
Contexts
Every alias lives in a context, and the context’s access type decides who can reach it. Every
project has two built-in contexts, public and private, which can’t be changed:
Phone numbers don’t belong to a context you choose. SignalWire places them in the external
context.
When you dial an alias from a REST API call, SWML connect, or a client, write the
full /<context>/<name>.
How SignalWire resolves an Address
SignalWire hands each call or message to the handler of the Address it was sent to, following the path from Address to Resource. Two rules depend on the Address type:
- For a phone number, a call goes to the handler of its calling Address and a message to the handler of its messaging Address.
- A client dialing an alias can use only the channels the alias allows.
Because the Resource is what handles the call, the same logic runs whether the caller dialed the phone number, the SIP Address, or an alias. See inbound calling for the handler code itself.
One Resource, many Addresses
Give one Resource every Address its callers need rather than duplicating the Resource per channel. Bayview Taxi’s dispatcher, Ada, is one AI Agent Resource with four Addresses:
To move riders and drivers to a new version of Ada, Bayview assigns the phone number to the new Resource. It then deletes the two aliases from the old Resource and re-creates them on the new one. The old aliases go first because an alias name can’t be reused in its context while another Resource holds it. The number and both aliases stay the same, so nothing that dials them changes.
The SIP Address can’t follow, because an AI Agent added in the Dashboard can’t take over an existing SIP Address. Bayview assigns the new Resource a SIP Address of its own and points the office PBX at its URI.
Create and manage Addresses
Every alias and SIP Address needs a Resource when you create it.
In the Dashboard, open a Resource and select its Addresses & Phone Numbers tab, then select + Add to Assign a Phone Number, Assign a SIP Address, or Add an Alias.
Moving an Address depends on its type:
- Phone number: assign a different Resource as its call or message handler from the number’s settings, with Assign Resource to phone route, or with Update phone number address.
- SIP Address: open it in the Dashboard, select Change Resource, and pick the new Resource. The SIP Address keeps its URI. The new Resource can’t be an AI Agent added in the Dashboard. To bring SIP calls to one, assign it a new SIP Address.
- Alias: delete it and create one with the same name and context on the new Resource.
Removing an Address removes only that way in. The Resource stays, and a phone number stays in your project, unassigned, until you assign another Resource. Select Delete Address next to an Address on its Resource’s Addresses & Phone Numbers tab, or use Delete SIP address to delete a SIP Address together with its settings.
With the REST API, every create call takes the ID of the Resource that handles the Address:
In the Browser SDK, a client signed in as a Subscriber lists Addresses through client.directory$
and dials the URI each entry returns. The address book guide shows how.