Dispatch rule | LiveKit Documentation

Overview

A dispatch rule determines which room each inbound SIP caller joins. You can send each caller to a dedicated room, put all callers in one room, or route them to a specific room by name or other criteria. When an inbound call reaches your SIP trunk and is handed off to LiveKit, the SIP service finds a matching dispatch rule and uses it to add the caller as a SIP participant to the appropriate room (creating the room if needed).

Create a dispatch rule using the CreateSIPDispatchRule API. By default, a dispatch rule matches all your trunks and makes a caller's phone number visible to others in the room. You can modify these defaults with dispatch rule options. For a full list of available options, see the CreateSIPDispatchRule API reference.

Reuse dispatch rules across calls

Dispatch rules are long-lived configuration objects meant to be reused. Create your dispatch rules once and reuse them for every call. Creating a new rule for each call adds unnecessary load and can degrade reliability at scale. To give each caller a unique room, rely on room naming within a single rule: an individual dispatch rule adds a random suffix per caller, and a callee dispatch rule names the room after the number that was dialed.

Dispatch to an agent

Use an individual dispatch rule to place each caller in their own room, and include the roomConfig option so your agent joins those rooms. See Agent dispatch for roomConfig parameters.

Individual dispatch rule

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-, and dispatches an agent named inbound-agent to newly created rooms:

{
  "dispatch_rule":
    {   
      "rule": {
        "dispatchRuleIndividual": {
          "roomPrefix": "call-"
        }   
      },  
      "name": "My dispatch rule",
      "roomConfig": {
        "agents": [{
          "agentName": "inbound-agent",
          "metadata": "job dispatch metadata"
        }]  
      }   
    }   
}

import {
  LiveKitAPI,
  SipDispatchRuleIndividual,
  CreateSipDispatchRuleOptions,
} from 'livekit-server-sdk';
import { RoomConfiguration, RoomAgentDispatch } from '@livekit/protocol';

const api = new LiveKitAPI();

const rule: SipDispatchRuleIndividual = {
  roomPrefix: 'call-',
  type: 'individual',
};
const options: CreateSipDispatchRuleOptions = {
  name: 'My dispatch rule',
  roomConfig: new RoomConfiguration({
    agents: [
      new RoomAgentDispatch({
        agentName: 'inbound-agent',
        metadata: 'job dispatch metadata',
      }),
    ],
  }),
};

const dispatchRule = await api.sip.createSipDispatchRule(rule, options);
console.log('created dispatch rule', dispatchRule);

from livekit import api

lkapi = api.LiveKitAPI()

# Create a dispatch rule to place each caller in a separate room
rule = api.SIPDispatchRule(
  dispatch_rule_individual = api.SIPDispatchRuleIndividual(
    room_prefix = 'call-',
  )
)

request = api.CreateSIPDispatchRuleRequest(
  dispatch_rule = api.SIPDispatchRuleInfo(
    rule = rule,
    name = 'My dispatch rule',
    trunk_ids = [],
    room_config=api.RoomConfiguration(
        agents=[api.RoomAgentDispatch(
            agent_name="inbound-agent",
            metadata="job dispatch metadata",
        )]
    )
  )
)

dispatch = await lkapi.sip.create_sip_dispatch_rule(request)
print("created dispatch", dispatch)
await lkapi.aclose()

require 'livekit'

lkapi = LiveKit::LiveKitAPI.new

rule = LiveKit::Proto::SIPDispatchRule.new(
  dispatch_rule_individual: LiveKit::Proto::SIPDispatchRuleIndividual.new(
    room_prefix: "call-",
  )
)

resp = lkapi.sip.create_sip_dispatch_rule(
  rule,
  name: "My dispatch rule",
  room_config: LiveKit::Proto::RoomConfiguration.new(
    agents: [
      LiveKit::Proto::RoomAgentDispatch.new(
        agent_name: "inbound-agent",
        metadata: "job dispatch metadata",
      )
    ]
  )
)

puts resp

package main

import (
  "context"
  "fmt"

  "github.com/livekit/protocol/livekit"
  lksdk "github.com/livekit/server-sdk-go/v2"
)

func main() {
  rule := &livekit.SIPDispatchRule{
    Rule: &livekit.SIPDispatchRule_DispatchRuleIndividual{
      DispatchRuleIndividual: &livekit.SIPDispatchRuleIndividual{
        RoomPrefix: "call-",
      },
    },
  }

  request := &livekit.CreateSIPDispatchRuleRequest{
    DispatchRule: &livekit.SIPDispatchRuleInfo{
      Name: "My dispatch rule",
      Rule: rule,
      RoomConfig: &livekit.RoomConfiguration{
        Agents: []*livekit.RoomAgentDispatch{
          {
            AgentName: "inbound-agent",
            Metadata:  "job dispatch metadata",
          },
        },
      },
    },
  }

  api, err := lksdk.NewLiveKitAPI()
  if err != nil {
    fmt.Println(err)
    return
  }

  // Execute the request
  dispatchRule, err := api.SIP().CreateSIPDispatchRule(context.Background(), request)
  if err != nil {
    fmt.Println(err)
  } else {
    fmt.Println(dispatchRule)
  }
}

import io.livekit.server.LiveKitAPI
import io.livekit.server.SipDispatchRuleIndividual
import io.livekit.server.CreateSipDispatchRuleOptions
import livekit.LivekitRoom.RoomConfiguration
import livekit.LivekitAgentDispatch

val api = LiveKitAPI.createClient(
  host = System.getenv("LIVEKIT_URL"),
  apiKey = System.getenv("LIVEKIT_API_KEY"),
  secret = System.getenv("LIVEKIT_API_SECRET")
)

val rule = SipDispatchRuleIndividual(
    roomPrefix = "call-"
)

val roomConfig = RoomConfiguration.newBuilder()
    .addAgents(
        LivekitAgentDispatch.RoomAgentDispatch.newBuilder()
            .setAgentName("inbound-agent")
            .setMetadata("job dispatch metadata")
            .build()
    )
    .build()

val response = api.sip.createSipDispatchRule(
    rule = rule,
    options = CreateSipDispatchRuleOptions(
      name = "My dispatch rule",
      roomConfig = roomConfig
    )
).execute()

if (response.isSuccessful) {
    val dispatchRule = response.body()
    println("Dispatch rule created: ${dispatchRule}")
}

use livekit_api::services::sip::CreateSIPDispatchRuleOptions;
use livekit_api::services::LiveKitApi;
use livekit_protocol as proto;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // host is required; API key and secret are read from
    // LIVEKIT_API_KEY and LIVEKIT_API_SECRET.
    let api = LiveKitApi::new("https://<your-subdomain>.livekit.cloud")?;

    let rule = proto::sip_dispatch_rule::Rule::DispatchRuleIndividual(
        proto::SipDispatchRuleIndividual {
            room_prefix: "call-".to_owned(),
            ..Default::default()
        },
    );

    let options = CreateSIPDispatchRuleOptions {
        name: "My dispatch rule".to_owned(),
        // Dispatch an agent into each room created by this rule.
        room_config: Some(proto::RoomConfiguration {
            agents: vec![proto::RoomAgentDispatch {
                agent_name: "inbound-agent".to_owned(),
                metadata: "job dispatch metadata".to_owned(),
                ..Default::default()
            }],
            ..Default::default()
        }),
        ..Default::default()
    };

    let dispatch_rule = api.sip().create_sip_dispatch_rule(rule, options).await?;
    println!("created dispatch rule {:?}", dispatch_rule);
    Ok(())
}

Sign in to the LiveKit Cloud dashboard .
Select Telephony → Dispatch rules .
Select Create new dispatch rule.
Select the JSON editor tab.
Full parameter access
You can also use the Dispatch rule details tab to create a dispatch rule. However, the JSON editor allows you to configure all available parameters.

Copy and paste the following JSON:

{
   "rule": {
     "dispatchRuleIndividual": {
       "roomPrefix": "call-"
     }
   },
   "name": "My dispatch rule",
   "roomConfig": {
     "agents": [{
       "agentName": "inbound-agent",
       "metadata": "job dispatch metadata"
     }]
   }
 }

Select Create.

Wildcard dispatch rule

When you omit the trunk_ids field, the dispatch rule matches calls from all inbound trunks.

Agent dispatch

Use the roomConfig parameter on a dispatch rule to specify which agents are dispatched to a room when it's created. The agents parameter for roomConfig is an array of agent dispatch entries. Each entry can include the following fields:

agentName: Name of the agent to dispatch (required).
metadata: Optional string metadata passed to the agent job.

Your agent receives the metadata string as job metadata. Access it in the entrypoint function using ctx.job.metadata. This is useful for routing or customizing agent behavior based on the dispatch rule. For example, you can route calls to different data stores or workflows:

import json

@server.rtc_session(agent_name="inbound-agent")
async def my_agent(ctx: JobContext):
    metadata = json.loads(ctx.job.metadata)
    store_id = metadata.get("store_id")
    # Route to the correct store based on dispatch metadata

export default {
  async entry(ctx: JobContext) {
    const metadata = JSON.parse(ctx.job.metadata);
    const storeId = metadata.storeId;
    // Route to the correct store based on dispatch metadata
  },
};

To learn more, see Job metadata.

For the full set of room configuration options, see RoomConfiguration in the SIP API reference. For agent dispatch behavior and configuration, see Agent dispatch.

Dispatch to rooms

The following rule types dispatch callers to shared rooms. Use them when you want all callers in the same room or when room assignment is based on the called number.

Shared rooms

A direct dispatch rule with a static roomName, or a callee dispatch rule with randomize set to false, routes unrelated callers into the same room, where they can hear each other. For production telephony where each caller should be isolated, use an individual dispatch rule or a callee rule with the default randomize=true so each call gets a unique room.

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:

{
   "dispatch_rule":
     {   
       "rule": {
         "dispatchRuleDirect": {
           "roomName": "open-room"
         }   
       },  
       "name": "My dispatch rule"
     }   
 }

Create the dispatch rule using lk:

lk sip dispatch create dispatch-rule.json

import {
  LiveKitAPI,
  SipDispatchRuleDirect,
  CreateSipDispatchRuleOptions,
  ServerError,
} from 'livekit-server-sdk';

const api = new LiveKitAPI();

// Dispatch all callers to the same room
const rule: SipDispatchRuleDirect = {
  roomName: 'open-room',
  type: 'direct',
};

const options: CreateSipDispatchRuleOptions = {
  name: 'My dispatch rule',
};

try {
  const dispatchRule = await api.sip.createSipDispatchRule(rule, options);
  console.log(dispatchRule);
} catch (e) {
  if (e instanceof ServerError) {
    console.error(`${e.code} error: ${e.message}`);
  } else {
    throw e;
  }
}

import asyncio

from livekit import api

async def main():
  livekit_api = api.LiveKitAPI()

  # Create a dispatch rule to place all callers in the same room
  rule = api.SIPDispatchRule(
    dispatch_rule_direct = api.SIPDispatchRuleDirect(
      room_name = 'open-room',
    )
  )

  request = api.CreateSIPDispatchRuleRequest(
    dispatch_rule = api.SIPDispatchRuleInfo(
      rule = rule,
      name = 'My dispatch rule',
    )
  )

  try:
    dispatchRule = await livekit_api.sip.create_sip_dispatch_rule(request)
    print(f"Successfully created {dispatchRule}")
  except api.ServerError as e:
    print(f"{e.code} error: {e.message}")

  await livekit_api.aclose()

asyncio.run(main())

require 'livekit'

name = "My dispatch rule"
room_name = "open-room"

lkapi = LiveKit::LiveKitAPI.new

rule = LiveKit::Proto::SIPDispatchRule.new(
  dispatch_rule_direct: LiveKit::Proto::SIPDispatchRuleDirect.new(
    room_name: room_name,
  )
)

begin
  resp = lkapi.sip.create_sip_dispatch_rule(
    rule,
    name: name,
  )
  puts resp
rescue LiveKit::ServerError => e
  puts "#{e.code} error: #{e.message}"
end

package main

import (
  "context"
  "errors"
  "fmt"

  "github.com/livekit/protocol/livekit"
  lksdk "github.com/livekit/server-sdk-go/v2"
)

func main() {

  // Specify rule type and options
  rule := &livekit.SIPDispatchRule{
    Rule: &livekit.SIPDispatchRule_DispatchRuleDirect{
      DispatchRuleDirect: &livekit.SIPDispatchRuleDirect{
        RoomName: "open-room",
      },
    },
  }

  // Create request
  request := &livekit.CreateSIPDispatchRuleRequest{
    DispatchRule: &livekit.SIPDispatchRuleInfo{
      Rule: rule,
      Name: "My dispatch rule",
    },
  }

  api, err := lksdk.NewLiveKitAPI()
  if err != nil {
    fmt.Println(err)
    return
  }

  // Execute the request
  dispatchRule, err := api.SIP().CreateSIPDispatchRule(context.Background(), request)

  if err != nil {
    var se lksdk.ServerError
    if errors.As(err, &se) {
      fmt.Printf("%s error: %s\n", se.Code(), se.Msg())
    } else {
      fmt.Println(err)
    }
  } else {
    fmt.Println(dispatchRule)
  }
}

import io.livekit.server.LiveKitAPI
import io.livekit.server.SipDispatchRuleDirect
import io.livekit.server.CreateSipDispatchRuleOptions
import io.livekit.server.ServerError

val api = LiveKitAPI.createClient(
  host = System.getenv("LIVEKIT_URL"),
  apiKey = System.getenv("LIVEKIT_API_KEY"),
  secret = System.getenv("LIVEKIT_API_SECRET")
)

val rule = SipDispatchRuleDirect(
    roomName = "open-room"
)

val response = api.sip.createSipDispatchRule(
    rule = rule,
    options = CreateSipDispatchRuleOptions(
      name = "My dispatch rule"
    )
).execute()

if (response.isSuccessful) {
    val dispatchRule = response.body()
    println("Dispatch rule created: ${dispatchRule}")
} else {
    val error = ServerError.from(response)
    println("${error?.code} error: ${error?.message}")
}

use livekit_api::services::sip::CreateSIPDispatchRuleOptions;
use livekit_api::services::LiveKitApi;
use livekit_protocol as proto;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // host is required; API key and secret are read from
    // LIVEKIT_API_KEY and LIVEKIT_API_SECRET.
    let api = LiveKitApi::new("https://<your-subdomain>.livekit.cloud")?;

    // Dispatch all callers to the same room
    let rule = proto::sip_dispatch_rule::Rule::DispatchRuleDirect(proto::SipDispatchRuleDirect {
        room_name: "open-room".to_owned(),
        ..Default::default()
    });

    let options = CreateSIPDispatchRuleOptions {
        name: "My dispatch rule".to_owned(),
        ..Default::default()
    };

    match api.sip().create_sip_dispatch_rule(rule, options).await {
        Ok(dispatch_rule) => println!("{:?}", dispatch_rule),
        Err(e) => eprintln!("failed to create dispatch rule: {e}"),
    }
    Ok(())
}

Sign in to the LiveKit Cloud dashboard .
Select Telephony → Dispatch rules .
Select Create new dispatch rule.
Select the JSON editor tab.
Form editor
You can also use the Dispatch rule details tab for this example by selecting Direct for Rule type.

Copy and paste the following JSON:

{
   "rule": {
     "dispatchRuleDirect": {
       "roomName": "open-room"
     }
   },
   "name": "My dispatch rule"
 }

Select Create.

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:

{
  "dispatch_rule":
    {
      "trunk_ids": [],
      "rule": {
        "dispatchRuleDirect": {
          "roomName": "safe-room",
          "pin": "12345"
        }
      },
      "name": "My dispatch rule"
    }
}

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.

{
  "dispatch_rule":
    {
      "rule": {
        "dispatchRuleCallee": {
          "roomPrefix": "number-",
          "randomize": false
        }
      },
      "name": "My dispatch rule"
    }
}