SIP participant

Each user in a LiveKit telephony app is a LiveKit participant. This includes end users who call in using your inbound trunk, the participant you use to make outbound calls, and if you're using an agent, the AI voice agent that interacts with callers.

SIP participants are managed like any other participant using the participant management commands.

SIP participant attributes

SIP participants can be identified using the kind field for participants, which identifies the type of participant in a livekit room (i.e. session). For SIP participants, this is Participant.Kind == SIP.

The participant attributes field contains SIP specific attributes that identify the caller and call details.

SIP attributes

All SIP participants have the following attributes:

• sip.callID: LiveKit's SIP call ID. A unique ID used as a SIP call tag to identify a conversation (i.e. match requests and responses).

• sip.trunkID: The inbound or outbound SIP trunk ID used for the call.

• sip.ruleID: SIP DispatchRule ID used for the inbound call. This field is empty for outbound calls.

• sip.trunkPhoneNumber: Phone number associated with SIP trunk. For inbound trunks, this is the number dialed in to by an end user. For outbound trunks, this is the number a call originates from.

• sip.phoneNumber: User's phone number. For inbound trunks, this is the phone number the call originates from. For outbound SIP, this is the number dialed by the SIP participant.

  note:

  This attribute isn't available if HidePhoneNumber is set in the dispatch rule.

Twilio attributes

If you're using Twilio SIP trunks, the following additional attributes are included:

• sip.twilio.accountSid: Twilio account SID.
• sip.twilio.callSid: Twilio call SID.

Custom attributes

You can add custom SIP participant attributes in one of two ways:

• Adding attributes to the dispatch rule. To learn more, see Setting custom attributes on inbound SIP participants.

• Using SIP headers: For any X-* SIP headers, you can configure your trunk with headers_to_attributes and a key/value pair mapping.

  For example:

  TelnyxTwilio

  {
    "trunk": {
      "name": "Demo inbound trunk",
      "numbers": ["+1234567890"],
      "headers_to_attributes": {
        "X-<custom_key_value>": "<custom_attribute_name>",
      }
    }
  }

  Copy

  caution:

  Note that Telnyx numbers can only use the leading + if the Destination Number Format for the trunk is configured to +E.164.

Examples

if (participant.kind == ParticipantKind.SIP) {
  console.log(participant.attributes['sip.twilio.callSid']);
};

Creating a SIP participant to make outbound calls

To make outbound calls, create a SIP participant. To learn more, see Make outbound calls.