SIP dispatch rule

To provision a dispatch rule with the SIP service, use the CreateSIPDispatchRule API. It returns an SIPDispatchRuleInfo object that describes the created SIPDispatchRule. These parameters can also be queried at any time using the ListSIPDispatchRule API.

By default, a dispatch rule is matched against all your trunks. You can populate the trunk_ids if you wish for a SIP dispatch rule to only match a single trunk.

Also by default, a caller's phone number is visible to others in the room. You can optionally hide the phone number of the caller by setting hide_phone_number: true.

Direct dispatch rule

This creates a dispatch rule that puts all callers into a specified room, optionally protected by a pin.

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

Then create the dispatch rule using lk:

lk sip dispatch create dispatchRule.json

Caller dispatch rule (individual)

This creates a dispatch rule that 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 room name prefix by using the roomPrefix option.

{
  "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 created 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.

For example:

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

The metadata, {"is_internal": true}, is included for all SIP participants created from an inbound call by this dispatch rule and available in the participant metadata field.

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.

For example:

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

These attributes are available in the participant attributes field for all SIP participants created from an inbound call by this dispatch rule.

To learn more, see SIP participant attributes.