Bring your own carrier

Overview

Bring Your Own Carrier (BYOC) allows SignalWire users to retain their own carriers for connectivity instead of the vendors that we partner with. This allows you to use any carrier you want while still utilizing the powerful programmatic control for SIP from SignalWire!

This might be a good fit for you if:

• You like your current carrier but want to use our APIs to enhance your call flow
• You want international origination from a country we don’t yet support
• The number cannot be ported into SignalWire
• You want to keep control of the number rather than port it to SignalWire
• You want to SIP trunk to/from a SIP Server (such as Kamailio)

Inbound BYOC

If you would like to do inbound BYOC (i.e. send your carrier traffic to SignalWire), you will need to create a domain application. Domain Apps allow you to send SIP traffic to a custom domain and use SignalWire APIs to manage the incoming request. You can do this under SIP -> Domain Apps -> Create a Domain App, or via the Domain Apps API.

For detailed instructions on how to create a domain application, please follow the SIP Domain Applications guide.

Handling Inbound Calls

Using SWML

If you are using SWML to handle incoming calls, you will need to:

1. Go to the settings page for the newly created Domain App, by clicking on the app name in the Domain Apps list.
2. Set the HANDLE USING field to SWML Script
3. Set the WHEN A CALL COMES IN field to the URL of your SWML script
4. Ensure the SWML script is set up to provide instructions on what actions to perform when a call comes in.

To address both of the steps above, we will need to create an SWML script.

Example SWML Script

The following is a simple example of an SWML script that answers the call and plays a TTS message:

1
version: 1.0.0
2
sections:
3
  main:
4
    - play:
5
        url: 'say: Hello, welcome to SignalWire!'

Using Call-Flow Builder

If you are using a Call Flow to handle incoming calls, you will need to:

1. Go to the settings page for the newly created Domain App, by clicking on the app name in the Domain Apps list.
2. Set the HANDLE USING field to A Call Flow
3. Set the WHEN A CALL COMES IN field to the Call Flow you want to use from the dropdown list.
4. Ensure the Call Flow is set up to provide instructions on what actions to perform when a call comes in.

Example Call Flow

In the below example, we have a Call Flow that answers the call and plays a TTS message.

Using RELAY

To handle incoming calls using a RELAY Application, you will need to:

1. Go to the settings page for the newly created Domain App, by clicking on the app name in the Domain Apps list.
2. Set the HANDLE USING field to RELAY Application
3. Set a topic (V4) or context (V3) in the WHEN A CALL COMES IN field. Let’s use office as an example.
4. Run code listening for calls on that office topic/context and then do something with them.

1
import { Voice } from "@signalwire/realtime-api";
2
3
const client = new Voice.Client({
4
  project: "<project-id>",
5
  token: "<api-token>",
6
  contexts: ["office"],
7
});
8
9
client.on("call.received", async (call) => {
10
  console.log("Got call", call.from, call.to);
11
12
  try {
13
    await call.answer();
14
    console.log("Inbound call answered");
15
16
    await call.playTTS({ text: "Hello! This is a test call." });
17
  } catch (error) {
18
    console.error("Error answering inbound call", error);
19
  }
20
});

To learn more about what you can do with RELAY, have a look at our SDK documentation.

Outbound BYOC

If you are using BYOC to do outbound calls from SignalWire, you will need a SIP URL from your carrier that we can use to route calls to the right SIP trunk. Once you have that, you can create a call using the Calling API or Realtime SDK using the SIP URL, SIP username, and SIP password. Let’s look at some examples so you can see what we’re talking about!

Outbound Call Examples

Using Calling API/SWML

Calling API

To create an outbound call using the Calling API with curl, you can use the Create a Call endpoint with the following format:

$
curl -L 'https://<YOURSPACENAME>.signalwire.com/api/calling/calls' \
>
-H 'Content-Type: application/json' \
>
-H 'Accept: application/json' \
>
-H 'Authorization: Basic Base64-token-here' \
>
--data-raw '{
>
  "command": "dial",
>
  "params": {
>
    "url": "https://example.com/swml",
>
    "from": "sip:from-sip@example-112233445566.sip.signalwire.com",
>
    "to": "sip:from-sip@example-112233445567.sip.signalwire.com",
>
    "caller_id": "+1234567890",
>
    "fallback_url": "https://example.com/fallback"
>
  }
>
}'

In the params you can specify a url that points to an SWML script, or you can pass a swml key with the SWML script directly.

SWML

To create an outbound call using SWML, you can use the following format:

1
version: 1.0.0
2
sections:
3
  main:
4
    - connect:
5
        to: "sip:user@domain.com"
6
        headers:
7
          - name: "x-FROM_NUMBER"
8
            value: "%2B123456789"

Using Call-Flow Builder

To create an outbound call using a Call Flow, you can use the Forward to Phone node to dial out to a SIP endpoint:

Using RELAY

RELAY Realtime SDK

The RELAY SDK makes dialing out to a SIP endpoint simple:

1
import { Voice } from "@signalwire/realtime-api";
2
3
const client = new Voice.Client({
4
  project: "<project-id>",
5
  token: "<api-token>",
6
  contexts: ["office"],
7
});
8
9
try {
10
  const call = await client.dialSip({
11
    from: "sip:xxx@yyy.zz",
12
    to: "sip:ppp@qqq.rr",
13
    timeout: 30,
14
  });
15
16
  // TODO: Add code to do something with the call object here
17
} catch (e) {
18
  console.log("Call not answered.");
19
}

How to Get Started

If you are interested in BYOC and need additional assistance getting started, reach out to support@signalwire.com! One of our support technicians can make sure everything gets squared away so you can get up and running in no time.

Sign Up Here

If you would like to test this example out, create a SignalWire account and Space.

Please feel free to reach out to us on our Community Discord or create a Support ticket if you need guidance!