SIP dispatch rule | LiveKit Docs

To create a dispatch rule with the SIP service, use the CreateSIPDispatchRule API. It returns a SIPDispatchRuleInfo object that describes the created SIPDispatchRule.

By default, a dispatch rule is matched against all your trunks and makes a caller's phone number visible to others in the room. You can change these default behaviors using dispatch rule options. See the CreateSIPDispatchRule API reference for full list of available options.

To learn more about SIP and dispatch rules, see SIP overview. To learn more about SIP API endpoints and types, see SIP API.

Direct dispatch rule

A direct dispatch rule places all callers into a specified room. You can optionally protect room access by adding a pin in the pin field:

In the following examples, all calls are immediately connected to room open-room on LiveKit.

Create a file named dispatch-rule.json and add the following:

{
  "trunk_ids": [],
  "hide_phone_number": false,
  "rule": {
    "dispatchRuleDirect": {
      "roomName": "open-room",
      "pin": ""
    }
  }
}

Create the dispatch rule using lk:

lk sip dispatch create dispatch-rule.json

Pin-protected room

Add a pin to a room to require callers to enter a pin to connect to a room in LiveKit. The following example requires callers to enter 12345# on the phone to enter safe-room:

{
  "trunk_ids": [],
  "hide_phone_number": false,
  "rule": {
    "dispatchRuleDirect": {
      "roomName": "safe-room",
      "pin": "12345"
    }
  }
}

Caller dispatch rule (individual)

An SIPDispatchRuleIndividual rule creates a new room for each caller. The name of the created room is the phone number of the caller plus a random suffix. You can optionally add a specific prefix to the room name by using the roomPrefix option.

The following examples dispatch callers into individual rooms prefixed with call-:

{
  "trunk_ids": [],
  "hide_phone_number": false,
  "rule": {
    "dispatchRuleIndividual": {
      "roomPrefix": "call-",
      "pin": ""
    }
  }
}

Callee dispatch rule

This creates a dispatch rule that puts callers into rooms based on the called number. The name of the room is the called phone number plus an optional prefix (if roomPrefix is set). You can optionally add a random suffix for each caller by setting randomize to true, making a separate room per caller.

{
  "trunk_ids": [],
  "hide_phone_number": false,
  "rule": {
    "dispatchRuleCallee": {
      "roomPrefix": "number-",
      "randomize": false,
      "pin": ""
    }
  }
}

Setting custom metadata on inbound SIP participants

LiveKit participants have a metadata field that can store arbitrary data for your application (typically JSON). It can also be set on SIP participants created by a dispatch rule. Specifically, metadata set on a dispatch rule will be inherited by all SIP participants created by it.

The following examples add the metadata, {"is_internal": true}, to all SIP participants created from an inbound call by this dispatch rule:

{
  "trunk_ids": [],
  "hide_phone_number": false,
  "metadata": "{\"is_internal\": true}",
  "rule": {
    "dispatchRuleIndividual": {
      "roomPrefix": "call-",
      "pin": ""
    }
  }
}

Setting custom attributes on inbound SIP participants

LiveKit participants have an attributes field that stores key-value pairs. You can add custom attributes for SIP participants in the dispatch rule. These attributes are inherited by all SIP participants created by the dispatch rule.

To learn more, see SIP participant attributes.

The following examples add two attributes to SIP participants created by this dispatch rule:

{
  "trunk_ids": [],
  "hide_phone_number": false,
  "attributes": {
    "<key_name1>": "<value1>",
    "<key_name2>": "<value2>"
  },
  "rule": {
    "dispatchRuleIndividual": {
      "roomPrefix": "call-",
      "pin": ""
    }
  }
}

List dispatch rules

Use the ListSIPDispatchRule API to list all dispatch rules.

lk sip dispatch list