SIP Domain Applications

A Domain Application is a SignalWire feature that allows you to send SIP traffic to a custom domain and run specified logic. To define that logic, you can set up a handler in the SIP Space of your SignalWire Dashboard.

The Domain App page in the SignalWire Dashboard.

Relay Application

If you are handling incoming SIP traffic with a Relay Application, you are defining your logic in a separate Relay application on your own server. Relay applications run different logic based on the context attached to incoming calls, so you will need to choose a context to label your incoming SIP traffic. The following example shows a Relay client listening for the "office" context then runs the logic inside the event listener callback.

Relay V4

import { SignalWire } from "@signalwire/realtime-api";

const client = await SignalWire({
  project: "your-project-id",
  token: "your-api-token",
  // This topic must match the topic you set in your Domain App handler.
  topics: ["office"],
});

const voiceClient = client.voice;

await voiceClient.listen({
  topics: ["office"],
  onCallReceived: async (call) => {
    console.log("Call received:", call.id, call.from, call.to);

    try {
      await call.answer();
      console.log("Inbound call answered");
      await call.playTTS({ text: "Welcome to SignalWire!" });
    } catch (error) {
      console.error("Error answering inbound call", error);
    }
  },
});

Relay V3

import { Voice } from "@signalwire/realtime-api";

const client = new Voice.Client({
  project: "your-project-id",
  token: "your-api-token",
  // This context must match the context you set in your Domain App handler.
  contexts: ["office"],
});

client.on("call.received", async (call) => {
  console.log("Call received:", call.id, call.from, call.to);

  try {
    await call.answer();
    console.log("Inbound call answered");
    const playback = await call.playTTS({ text: "Welcome to SignalWire!" });
    await playback.ended();
  } catch (error) {
    console.error("Error answering inbound call", error);
  }
});

Find the many options for what you can do with Relay in our Relay Realtime SDK reference or another SDK of your choice.

cXML Webhooks

Using the cXML Webhooks handler will open the wide array of options with our cXML API. This is an easy yet powerful way to control your Domain application. cXML Webhooks most often utilize cXML Applications, our serverless containers for simple SignalWire applications.

Start by creating a cXML application in the Resources Space of your Dashboard. Click the blue "+ Add" button to open a new bin editor. Give your bin a descriptive name that will be easy to identify later, then write your logic using cXML.

For example, if you want to answer an inbound SIP call with a welcome message:

<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Say>Welcome to SignalWire. This is my first call.</Say>
</Response>

Or even to connect an inbound SIP call to a video room:

<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Connect>
    <Room>fstovideo</Room>
  </Connect>
</Response>

Save your cXML application and copy its Request URL from the bins list. This is the URL you will input in your Domain Application settings.

The Apps tab in your LaML space

LaML bins do not support conditional or complex logic, but in the Domain Application settings, you can assign a backup webhook and a status change webhook. You can also set these fallback webhooks with a LaML Application discussed below.

cXML Application

A cXML Application handler will run logic the same way cXML Webhooks do, but they simplify the assignment of resources to cXML scripts. For example, you may have ten Domain Applications you would like to direct toward the same LaML Bin. If at some point you need to redirect the applications to a different LaML Bin, you would need to edit the settings of each Domain Application. However, if your ten Domain Applications were handled by a LaML application, you would just need to change one setting of the LaML application.

The Apps tab in your resources space

cXML Applications are created and managed in the resources Space of your Dashboard. After you create the LaML application, use the cXML application name to refer to it in the Domain Application settings.

Video Room

While you can connect inbound SIP traffic to a video room using cXMLs as described above, you also have the option of immediately connecting calls to a video room. To use the Video Room handler, search for the video room name in the settings dropdown and select the video room you would like to use. Inbound calls will be automatically directed to this video room.

tip

For a full guide to creating and configuring new Domain Applications, visit our SIP Space help page.