Phone Numbers | SignalWire

Search for available phone numbers, purchase them, and manage the numbers in your SignalWire project. This resource extends the standard CRUD pattern with a search() method for discovering available numbers, uses PUT for updates, and provides typed helpers for binding inbound calls to a handler (SWML webhook, cXML webhook, AI agent, call flow, Relay application/topic).

Access via client.phoneNumbers on a RestClient instance.

Idiomatic deviation: create() and update() accept an untyped body object (Record<string, unknown>) rather than narrow per-field types. This mirrors Python’s **kwargs-style flexibility. Response payloads follow the same typing.

import { RestClient } from "@signalwire/sdk";
const client = new RestClient({
  project: "your-project-id",
  token: "your-api-token",
  host: "your-space.signalwire.com"
});
const available = await client.phoneNumbers.search({ areacode: "512" });
for (const number of available.data ?? []) {
    console.log(number.phoneNumber);
}

Methods

Standard CRUD

list

List phone numbers owned by the project.

create

Purchase a phone number.

get

Retrieve details for a specific phone number.

update

Update configuration for a phone number.

delete

Release a phone number from the project.

Search for available phone numbers to purchase.

Typed Binding Helpers

Each helper is a one-line wrapper over update that sets call_handler to the right value and populates the handler-specific companion field for you. Pass extra wire-level fields through the extra argument (or as additional keys on the params object) for fields the helper doesn’t name explicitly. Setting a binding auto-materializes the matching Fabric resource on the server.

setSwmlWebhook

Route inbound calls to an SWML webhook URL.

setCxmlWebhook

Route inbound calls to a cXML (LAML) webhook.

setCxmlApplication

Route inbound calls to an existing cXML application by ID.

setAiAgent

Route inbound calls to an AI Agent Fabric resource by ID.

setCallFlow

Route inbound calls to a Call Flow by ID.

setRelayApplication

Route inbound calls to a named Relay application.

setRelayTopic

Route inbound calls to a Relay topic.

PhoneCallHandler

For callers passing call_handler directly to update, the PhoneCallHandler const provides typed values. It is a const-as-enum (as const object plus a same-named string-union type), so passing a member serializes to its wire value with full type-checking on the call site.

import { PhoneCallHandler } from "@signalwire/sdk";
await client.phoneNumbers.update("phone-number-id", {
  call_handler: PhoneCallHandler.AI_AGENT,
  call_ai_agent_id: "ai-agent-id",
});

Member	Wire value	Companion field	Auto-creates
`RELAY_SCRIPT`	`relay_script`	`call_relay_script_url`	`swml_webhook`
`LAML_WEBHOOKS`	`laml_webhooks`	`call_request_url`	`cxml_webhook`
`LAML_APPLICATION`	`laml_application`	`call_laml_application_id`	`cxml_application`
`AI_AGENT`	`ai_agent`	`call_ai_agent_id`	`ai_agent`
`CALL_FLOW`	`call_flow`	`call_flow_id`	`call_flow`
`RELAY_APPLICATION`	`relay_application`	`call_relay_application`	`relay_application`
`RELAY_TOPIC`	`relay_topic`	`call_relay_topic`	(routes via Relay)

LAML_WEBHOOKS (wire value laml_webhooks) produces a cXML handler, not a generic webhook. For SWML, use RELAY_SCRIPT — or, more conveniently, the setSwmlWebhook helper.