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.

Your SIP Space is the hub for your SIP SignalWire services. Click on the "Domain Apps" tab to manage or create new Domain Applications

When you create a Domain Application, there are four handler options: Relay Application, LaML Webhooks, a LaML Application, or a Video Room. Let's explore what you can do with each handler.

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.

LaML Webhooks

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

Start by creating a LaML Bin in the LaML Space of your Dashboard. In the "Bins" tab, click the blue "+ New" 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 Compatibility XML.

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 LaML Bin 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.

LaML Application

A LaML Application handler will run logic the same way LaML Webhooks do, but they simplify the assignment of resources to LaML Bins. 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 LaML space

LaML Applications are created and managed in the LaML Space of your Dashboard. After you create the LaML application, use the LaML 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 LaML 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.