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 will be 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 will be visible to others in the room. You can optionally hide the phone number of the caller by setting hide_phone_number: true.

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": "open-room",
			"pin": ""
		}
	}
}

Then create the Dispatch Rule using lk:

lk sip dispatch create dispatchRule.json

This creates a Dispatch Rule that creates a new room for each caller. The created room will be 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": ""
		}
	}
}

This creates a Dispatch Rule that puts callers into rooms based on the called number. The created room will be 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": ""
		}
	}
}

LiveKit Participants have a metadata 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": ""
		}
	}
}

Here, the {"is_internal": true} JSON will appear on all SIP Participants created from inbound call by this rule.