Give an AI agent a SIP address

AI AgentsSIP URI for a voice AI agent

Create a SIP address that rings a hosted AI agent, so a SIP phone or PBX can reach it without a phone number in between.

restsip

The claim

A hosted resource is reachable two ways: by a phone number pointed at it, or by a SIP address. This recipe makes the second one. The response carries the uri, and that string is the whole integration on the PBX side.

Why it holds

The vendored REST spec, tools/openapi/rest.json, is the authority.

POST /api/fabric/sip_addresses requires name and calling_handler_resource_id. The name is “lowercase letters, numbers, and hyphens only” and “is used to build the address’s SIP URI”. The recipe refuses anything else before sending.
user defaults to *, which “accepts any username”. Set it when the PBX should reach the agent by one specific username.
encryption is required, optional or forbidden. The recipe asks for required.
codecs defaults to PCMU and PCMA, and ip_auth_enabled to false. The recipe leaves both alone.

Neither SDK wraps this path in the versions pinned here. The request goes through the HTTP client every namespace shares, as the subproject recipes do.

How it works

NAME_SHAPE = re.compile(r"^[a-z0-9-]+$")

def give_address(resource_id, name, user=None, encryption="required"):
    if not NAME_SHAPE.match(name):
        raise ValueError(...)
    body = {"name": name, "calling_handler_resource_id": resource_id,
            "encryption": encryption}
    if user:
        body["user"] = user
    return http.post("/api/fabric/sip_addresses", body=body)

What the platform receives:

{"name": "front-desk",
 "calling_handler_resource_id": "0b7a2f3e-9c41-4d6e-8a52-1f0e3d2c4b5a",
 "encryption": "required"}

The response’s uri is what you dial. Its context says which domain the address lives under, public for the project’s default. With the default user, any username at that domain reaches the agent. With user set, only that one does.

Limitations

The verifier proves the request, not the call. Whether a given PBX accepts the URI, negotiates SRTP and reaches the agent is live behaviour.

password is write-only and never returned. A registration password belongs in your secrets, not in this recipe’s arguments.

What to change first

Change encryption="required" to "always" and run the verifier. The exact body comparison fails on a value outside the enum, which is the point. Three values are the whole vocabulary.

Where this sits

Before this

Create a hosted voice AI agent with one REST call

Connect a PBX with a Domain Application Route SIP calls to AI agents by username Register a SIP endpoint and receive calls

python/app.py

"""Give an AI agent a SIP address.

A hosted resource can be reached over SIP as well as from a phone number.
`POST /api/fabric/sip_addresses` requires a URL-safe `name` and the
`calling_handler_resource_id` of the resource to ring, and the response carries
the `uri` a SIP phone or PBX dials. The `user` part defaults to `*`, which
accepts any username.

3.0.1 has no wrapper for this path, so the request goes through the HTTP client
every namespace shares (rest/client.py).

Written against signalwire-sdk 3.0.1 (RestClient).

    python app.py <agent_resource_id> front-desk
"""
import re
import sys

from dotenv import load_dotenv
from signalwire.rest import RestClient

# the SDK does not read .env for you
load_dotenv()

# reads SIGNALWIRE_PROJECT_ID / SIGNALWIRE_API_TOKEN / SIGNALWIRE_SPACE from the env
client = RestClient()
http = client._http

# the spec: lowercase letters, numbers and hyphens, nothing else
NAME_SHAPE = re.compile(r"^[a-z0-9-]+$")


def give_address(resource_id, name, user=None, encryption="required"):
    """Create a SIP address that rings the resource. Returns the platform's record."""
    if not NAME_SHAPE.match(name):
        raise ValueError(f"name must be lowercase letters, numbers and hyphens: {name!r}")
    body = {"name": name, "calling_handler_resource_id": resource_id,
            "encryption": encryption}
    if user:
        # otherwise the spec's default `*` accepts any username
        body["user"] = user
    return http.post("/api/fabric/sip_addresses", body=body)


def dial_string(created):
    """What to type into the SIP phone."""
    return created["uri"]


if __name__ == "__main__":
    args = sys.argv[1:]
    if len(args) < 2:
        print(__doc__)
    else:
        made = give_address(args[0], args[1], *args[2:3])
        print(dial_string(made))

/**
 * Give an AI agent a SIP address.
 *
 * A hosted resource can be reached over SIP as well as from a phone number.
 * `POST /api/fabric/sip_addresses` requires a URL-safe `name` and the
 * `calling_handler_resource_id` of the resource to ring, and the response
 * carries the `uri` a SIP phone or PBX dials. The `user` part defaults to `*`,
 * which accepts any username.
 *
 * 2.0.5 has no wrapper for this path, so the request goes through the HTTP
 * client every namespace shares.
 *
 * Written against @signalwire/sdk 2.0.5 (RestClient).
 *
 *     npm start <agent_resource_id> front-desk
 */
import "dotenv/config";
import { RestClient } from "@signalwire/sdk";

// reads SIGNALWIRE_PROJECT_ID / SIGNALWIRE_API_TOKEN / SIGNALWIRE_SPACE
export const client = new RestClient();
const http = (client.calling as unknown as {
  _http: { post(path: string, body: unknown): Promise<Record<string, string>> };
})._http;

// the spec: lowercase letters, numbers and hyphens, nothing else
const NAME_SHAPE = /^[a-z0-9-]+$/;

export type Created = { uri: string; user: string; name: string; resource_id: string };

/** Create a SIP address that rings the resource. Returns the platform's record. */
export async function giveAddress(resourceId: string, name: string, user?: string,
                                  encryption = "required"): Promise<Created> {
  if (!NAME_SHAPE.test(name)) {
    throw new Error(`name must be lowercase letters, numbers and hyphens: '${name}'`);
  }
  const body: Record<string, string> = {
    name, calling_handler_resource_id: resourceId, encryption,
  };
  if (user) {
    // otherwise the spec's default `*` accepts any username
    body["user"] = user;
  }
  return http.post("/api/fabric/sip_addresses", body) as Promise<Created>;
}

/** What to type into the SIP phone. */
export const dialString = (created: Created) => created.uri;

if (process.argv[1] && import.meta.url.endsWith(process.argv[1].replace(/\\/g, "/"))) {
  const [resourceId, name, user] = process.argv.slice(2);
  if (!resourceId || !name) {
    console.log("usage: npm start <agent_resource_id> <name> [user]");
  } else {
    console.log(dialString(await giveAddress(resourceId, name, user)));
  }
}

Run it

cd python
pip install -r requirements.txt
cp ../.env.example .env          # project id, API token, space
python app.py <agent_resource_id> front-desk

The TypeScript surface is the same request on @signalwire/sdk, on Node 20.18.1 or newer:

cd typescript
npm ci
cp ../.env.example .env
npm start <agent_resource_id> front-desk

The resource id comes from [Create a hosted voice AI agent with one REST call](../create-a-hosted-voice-ai-agent-with-one-rest-call/). The script prints the URI; put it in the PBX as a trunk or an extension.

Verify it

No network, no account.

python verify.py          # from the recipe folder, not python/

The verifier swaps the SDK’s HTTP layer for a recorder, creates two addresses, and asserts the following.

four names the spec would reject, with a space, an underscore, capitals, or nothing, raise before any request is made
the spec requires exactly name and calling_handler_resource_id, and every key sent is documented
the first body carries the two required fields and encryption: required; the second adds user: reception
the spec’s name rule, the * default and its meaning, the encryption enum, the codec defaults and the IP-auth default are what the README says they are
the response schema documents uri as the full SIP URI, and the recipe returns it as the dial string
the TypeScript surface sends the same two bodies and refuses the same four names

Report an issue