Make and receive calls

Place calls to phones and answer calls to your SignalWire number with SWML, Relay, or the Browser SDK. Each section below takes one of them from a first test call on your own phone through tracking the call’s progress.

Choose an approach

Each approach has its own code and its own kind of Resource on your phone number, so pick one and follow only its section. The sections don’t build on each other, and code from one doesn’t carry over to another.

• SWML is a document of call instructions that SignalWire runs. You build it with the Server SDKs and send it in a REST request to place a call. To answer one, serve it from your server or host it in SignalWire, which needs none of your code running.
• WebSocket (Relay) is a Relay client in the Server SDKs. It holds a WebSocket open from your server, receives calls and events as they happen, and controls each call from your code.
• The Browser SDK puts a person on the call from a web page, with their microphone, camera, and in-call controls.

Prepare for your first call

Have these values ready:

• Your Space URL, such as <YOUR_SPACE>.signalwire.com.
• Your Project ID and API token from the Dashboard’s API credentials page. Enable the token’s Voice permission, and Numbers if you assign a phone number in code.
• A voice-capable phone number in your Space, and a phone you can call it from and answer.
• For the Browser SDK, a web page you can serve over HTTPS or localhost. The guide creates the Subscriber and its token for you.

Replace these values in the samples you run:

How an incoming call reaches your code

Placing a call only takes a request from your code. Answering one takes a little setup first, because SignalWire has to know where to send the call. Every phone number has one call handler: a Resource you assign under the number’s Inbound Call Settings. When someone dials the number, SignalWire hands the call to that Resource, and the Resource type decides what happens next:

So each answering walkthrough below has the same three parts: build the handler, assign it to your number, and call the number to test it. If the number has no call handler, or still points at a different Resource, the call never reaches your code.

Make and receive calls via SWML

A SWML document lists what happens on the call, such as playing a message, forwarding the caller, or recording. SignalWire runs it; your code supplies it.

Place a call via SWML

Send a REST dial request with a SWML document in swml. SignalWire runs the document when the destination answers.

# Install: python -m pip install signalwire-sdk==3.4.1
# Save as outbound_call.py and run: python outbound_call.py
from signalwire import SWMLBuilder, SWMLService
from signalwire.rest import RestClient
client = RestClient(
    project="<YOUR_PROJECT_ID>",
    token="<YOUR_API_TOKEN>",
    host="<YOUR_SPACE>.signalwire.com",
)
swml = (
    SWMLBuilder(SWMLService(name="outbound-call"))
    .say("Hello, welcome to SignalWire!")
    .build()
)
call = client.calling.dial(
    from_="<YOUR_CALLER_ID>",
    to="<YOUR_DESTINATION>",
    swml=swml,
)
print(call["id"])

{
  "billing_ms": null,
  "charge": 0,
  "charge_details": [
    {
      "charge": 0.004,
      "description": "Outbound Voice"
    }
  ],
  "created_at": "2024-05-06T12:20:00Z",
  "direction": "outbound-api",
  "duration": null,
  "duration_ms": null,
  "from": "+12069708643",
  "id": "0e9c80d7-a149-4917-892d-420043709f45",
  "parent_id": null,
  "source": "realtime_api",
  "status": "queued",
  "to": "+15550198765",
  "type": "relay_pstn_call",
  "url": null
}

Answer a call via SWML

When someone calls your number, SignalWire runs the SWML Script assigned to it. The script either fetches the document from your server on each call, or holds the document itself. Hosting it in SignalWire is the quickest way to hear your first call; serving it from your server lets your code build a different document for each caller.

This flow shows a call handled by a script that fetches its document from your server:

# Install: python -m pip install signalwire-sdk==3.4.1
# Save as inbound_swml_server.py and run: python inbound_swml_server.py
from signalwire import SWMLBuilder, SWMLService
service = SWMLService(
    name="inbound-swml-server",
    route="/swml",
    port=3000,
    basic_auth=("signalwire", "<YOUR_BASIC_AUTH_PASSWORD>"),
)
SWMLBuilder(service).say("Hello, welcome to SignalWire!")
# Serves the document at /swml. Put the credentials in the URL you give
# SignalWire: https://signalwire:<YOUR_BASIC_AUTH_PASSWORD>@<YOUR_PUBLIC_HOST>/swml
service.serve()

ngrok http 3000

curl -u "signalwire:<YOUR_BASIC_AUTH_PASSWORD>" "https://<YOUR_PUBLIC_HOST>/swml"

# Install: python -m pip install signalwire-sdk==3.4.1
# Save as assign_swml_webhook.py and run: python assign_swml_webhook.py
from signalwire.rest import RestClient
client = RestClient(
    project="<YOUR_PROJECT_ID>",
    token="<YOUR_API_TOKEN>",
    host="<YOUR_SPACE>.signalwire.com",
)
client.phone_numbers.set_swml_webhook(
    "<YOUR_PHONE_NUMBER_ID>",
    "https://signalwire:<YOUR_BASIC_AUTH_PASSWORD>@<YOUR_PUBLIC_HOST>/swml",
)

Track a call via SWML

To follow an outbound call, add status_url and status_events to the dial request in Place a call via SWML. SignalWire sends an HTTP POST to status_url as the call reaches each state you list: created, ringing, answered, or ended. Without status_events, you get ended only. The webhooks guide covers endpoint setup and local testing.

call = client.calling.dial(
    from_="<YOUR_CALLER_ID>",
    to="<YOUR_DESTINATION>",
    swml=swml,
    status_url="<YOUR_STATUS_WEBHOOK_URL>",
    status_events=["ringing", "answered", "ended"],
)

For an inbound call, the request SignalWire sends your server carries the call in its call object: from, to, direction, and call_id (see the webhook payload reference). The same fields are available inside any SWML document as variables. To read the caller’s number back, replace the greeting with this one:

SWMLBuilder(service).say("Thanks for calling from ${call.from}.")

A SWML document can also fetch data mid-call with request and branch on the result with switch. Methods such as record, connect, and stream take their own status_url to report their progress.

Make and receive calls via WebSocket (Relay)

A Relay client runs on your server and holds a WebSocket connection to SignalWire. It receives calls and events on that connection and sends commands back, so it needs no public HTTP endpoint.

Place a call via WebSocket (Relay)

# Install: python -m pip install signalwire-sdk==3.4.1
# Save as outbound_relay.py and run: python outbound_relay.py
import asyncio
from signalwire.relay import RelayClient
client = RelayClient(
    project="<YOUR_PROJECT_ID>",
    token="<YOUR_API_TOKEN>",
    contexts=["default"],
)
async def main():
    async with client:
        call = await client.dial(
            devices=[[{
                "type": "phone",
                "params": {
                    "from_number": "<YOUR_CALLER_ID>",
                    "to_number": "<YOUR_DESTINATION>",
                    "timeout": 30,
                },
            }]],
        )
        async def hang_up_after_playback(_event):
            if call.state != "ended":
                await call.hangup()
        await call.play([{
            "type": "tts",
            "params": {"text": "Hello, welcome to SignalWire!"},
        }], on_completed=hang_up_after_playback)
        await call.wait_for_ended()
asyncio.run(main())

Answer a call via WebSocket (Relay)

A Relay handler is a program on your server that stays connected to SignalWire, so it needs no public URL. It subscribes to one or more topics, names you choose and list in contexts. A Relay Application is the Resource that ties your phone number to one topic: calls to the number go to whichever Relay client is subscribed to that topic.

# Install: python -m pip install signalwire-sdk==3.4.1
# Save as inbound_relay.py and run: python inbound_relay.py
from signalwire.relay import RelayClient
client = RelayClient(
    project="<YOUR_PROJECT_ID>",
    token="<YOUR_API_TOKEN>",
    contexts=["inbound-calling"],
)
@client.on_call
async def handle_call(call):
    await call.answer()
    async def hang_up_after_playback(_event):
        if call.state != "ended":
            await call.hangup()
    await call.play([{
        "type": "tts",
        "params": {"text": "Hello, welcome to SignalWire!"},
    }], on_completed=hang_up_after_playback)
    await call.wait_for_ended()
client.run()

# Install: python -m pip install signalwire-sdk==3.4.1
# Save as assign_relay_topic.py and run: python assign_relay_topic.py
from signalwire.rest import RestClient
client = RestClient(
    project="<YOUR_PROJECT_ID>",
    token="<YOUR_API_TOKEN>",
    host="<YOUR_SPACE>.signalwire.com",
)
client.phone_numbers.set_relay_topic("<YOUR_PHONE_NUMBER_ID>", "inbound-calling")

Track a call via WebSocket (Relay)

Relay reports call state through call.on(). Add a calling.call.state listener to either first-run program, right after it gets the call, to see states such as answered, ending, and ended, with the end_reason once the call finishes. An outbound dial() returns after the destination answers, so there the listener sees ending and ended.

from signalwire.relay.event import CallStateEvent
def handle_state(event: CallStateEvent):
    print(f"State: {event.call_state}, reason: {event.end_reason}")
call.on("calling.call.state", handle_state)

On an inbound call, the Call object also carries the caller’s number in device.params.from_number, with direction and call_id.

This flow shows every message an outbound call exchanges on the connection. The created, ringing, and answered states arrive before dial() returns, so a listener you add afterward sees only ending and ended:

For more handlers, see Event listeners in the Relay client guide.

Make and receive calls in the browser

The Browser SDK signs a web page in as a Subscriber, so a person places and answers calls from the page with their own microphone and speakers. The page authenticates with a Subscriber token from your backend, never your API token.

Get a Subscriber token

A Subscriber is the Resource for one person in your app, identified by a reference such as their email. Run this program on your server once to create a test Subscriber and print a token for it. Paste the token in place of <YOUR_SUBSCRIBER_ACCESS_TOKEN> in the pages below.

# Install: python -m pip install signalwire-sdk==3.4.1
# Save as subscriber_token.py and run: python subscriber_token.py
from signalwire.rest import RestClient
client = RestClient(
    project="<YOUR_PROJECT_ID>",
    token="<YOUR_API_TOKEN>",
    host="<YOUR_SPACE>.signalwire.com",
)
# Create the Subscriber once. Later, run only the token request for a fresh token.
client.fabric.subscribers.create(email="<YOUR_SUBSCRIBER_EMAIL>")
sat = client.fabric.tokens.create_subscriber_token(reference="<YOUR_SUBSCRIBER_EMAIL>")
print(sat["token"])

The cURL requests call Create Subscriber, then Create Subscriber token with the Subscriber’s email as reference.

A token lasts two hours by default, so run the token request again when the page stops signing in. In production, your backend issues a token each time a user signs in, as the authentication guide shows.

Place a call from a browser

// Install: npm install @signalwire/js@4.0.0-rc.2 rxjs@7.8.2
// Load as a module script on an HTTPS or localhost page with these elements:
// <audio id="remote-audio" autoplay></audio>
// <button id="call" type="button">Call</button>
// <button id="hangup" type="button" disabled>Hang up</button>
// Use a Subscriber Access Token issued by your backend.
import { SignalWire, StaticCredentialProvider } from "@signalwire/js";
const client = new SignalWire(new StaticCredentialProvider({
  token: "<YOUR_SUBSCRIBER_ACCESS_TOKEN>",
}));
const remoteAudio = document.querySelector("#remote-audio");
const callButton = document.querySelector("#call");
const hangupButton = document.querySelector("#hangup");
callButton.onclick = async () => {
  callButton.disabled = true;
  try {
    const call = await client.dial("<YOUR_DESTINATION>", { audio: true, video: false });
    call.remoteStream$.subscribe((stream) => (remoteAudio.srcObject = stream));
    hangupButton.disabled = false;
    hangupButton.onclick = () => {
      void call.hangup().catch(console.error);
    };
    call.status$.subscribe((status) => {
      if (status === "disconnected" || status === "failed" || status === "destroyed") {
        remoteAudio.srcObject = null;
        hangupButton.disabled = true;
        callButton.disabled = false;
      }
    });
  } catch (error) {
    callButton.disabled = false;
    console.error(error);
  }
};

Answer a call in a browser

Assign the Subscriber to your phone number, and calls to the number ring the page signed in as that Subscriber.

// Install: npm install @signalwire/js@4.0.0-rc.2 rxjs@7.8.2
// Load as a module script on an HTTPS or localhost page with these elements:
// <p id="status">Offline</p>
// <p id="caller"></p>
// <audio id="remote-audio" autoplay></audio>
// <button id="answer" type="button" disabled>Answer</button>
// <button id="decline" type="button" disabled>Decline</button>
// <button id="hangup" type="button" disabled>Hang up</button>
// Use a Subscriber Access Token issued by your backend for the Subscriber
// that the phone number rings.
import { SignalWire, StaticCredentialProvider } from "@signalwire/js";
const client = new SignalWire(new StaticCredentialProvider({
  token: "<YOUR_SUBSCRIBER_ACCESS_TOKEN>",
}));
const statusLine = document.querySelector("#status");
const callerLine = document.querySelector("#caller");
const remoteAudio = document.querySelector("#remote-audio");
const answerButton = document.querySelector("#answer");
const declineButton = document.querySelector("#decline");
const hangupButton = document.querySelector("#hangup");
const finalStatuses = new Set(["disconnected", "failed", "destroyed"]);
let currentCall = null;
await client.register();
statusLine.textContent = "Online";
client.session.incomingCalls$.subscribe((calls) => {
  const ringing = calls.find((call) => call.status === "ringing");
  if (!ringing || ringing === currentCall) return;
  currentCall = ringing;
  callerLine.textContent = `Incoming call from ${ringing.from}`;
  answerButton.disabled = false;
  declineButton.disabled = false;
  ringing.remoteStream$.subscribe((stream) => (remoteAudio.srcObject = stream));
  ringing.status$.subscribe((status) => {
    statusLine.textContent = status;
    if (status !== "ringing") {
      answerButton.disabled = true;
      declineButton.disabled = true;
    }
    if (status === "connected") hangupButton.disabled = false;
    if (finalStatuses.has(status)) {
      remoteAudio.srcObject = null;
      hangupButton.disabled = true;
      callerLine.textContent = "";
      if (currentCall === ringing) currentCall = null;
    }
  });
});
answerButton.onclick = () => {
  void currentCall?.answer({ audio: true, video: false });
};
declineButton.onclick = () => {
  void currentCall?.reject();
};
hangupButton.onclick = () => {
  void currentCall?.hangup().catch(console.error);
};

The Browser SDK inbound calls guide builds a complete receiver page, including two callers ringing at once.

Track a call in a browser

The Browser SDK is the client-side counterpart of the Relay client: the page holds a WebSocket connection to SignalWire, and call state arrives as events on it rather than as HTTP callbacks. As in Track a call via WebSocket (Relay), you subscribe to a call’s events, here through the call’s status$ observable instead of call.on().

An outbound dial() returns the call while it is ringing. The call then moves through connecting and connected, and through disconnecting, disconnected, and destroyed once it ends. With disconnected, failed, and destroyed treated as final, one subscription updates the page for every outcome. To show the status on the calling page, add <p id="status">Idle</p> to Place a call from a browser, then add the lookup below and replace that page’s status$ subscription:

const statusLine = document.querySelector("#status");
// Inside callButton.onclick, after dial() resolves:
call.status$.subscribe((status) => {
  statusLine.textContent = `Call: ${status}`;
  if (status === "disconnected" || status === "failed" || status === "destroyed") {
    remoteAudio.srcObject = null;
    hangupButton.disabled = true;
    callButton.disabled = false;
  }
});

The answering page in Answer a call in a browser already writes each status to #status. An inbound call follows the same path once it’s answered; one that leaves ringing without reaching connected was declined, or the caller hung up.

Each entry in incomingCalls$ is a Call with direction set to inbound, the browser’s equivalent of the Relay Call a server handler receives. Read from for the caller’s number or Address, to for the number or Address they dialed, and fromName for a display name. SignalWire sends _undef_ as fromName when the caller supplied none, so fall back to from.

Next steps