To create a SIP participant to make outbound calls, see Make outbound calls.
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. You can use SIP participant attributes to create different workflows based on the caller. For example, look up customer information in a database to identify the caller.
SIP attributes
All SIP participants have the following attributes:
Attribute | Description |
---|---|
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.callStatus | Current call status for the SIP call associated with this participant. Valid values are:
|
| 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 |
sip.ruleID | SIP DispatchRule ID used for the inbound call. This field is empty for outbound calls. |
sip.trunkID | The inbound or outbound SIP trunk ID used for the call. |
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. |
Twilio attributes
If you're using Twilio SIP trunks, the following additional attributes are included:
Attribute | Description |
---|---|
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 withheaders_to_attributes
and a key/value pair mapping.For example:
{"trunk": {"name": "Demo inbound trunk","numbers": ["+15105550100"],"headers_to_attributes": {"X-<custom_key_value>": "<custom_attribute_name>",}}}cautionNote the leading
+
assumes theDestination Number Format
is set to+E.164
for your Telnyx number.
Examples
The following examples use SIP participant attributes.
Basic example
This example logs the Twilio call SID if the user is a SIP participant.
if (participant.kind == ParticipantKind.SIP) {console.log(participant.attributes['sip.twilio.callSid']);};
Modify AI voice agent based on caller attributes
The following example uses template apps as a starting point. If you completed the Accepting incoming calls quickstart, you can use the agent you created in Step 2: Creating an AI voice agent.
Otherwise, to create a template app, run the following LiveKit CLI command. For example, to create a voice-pipeline-agent-python
template app:
lk app create --template voice-pipeline-agent-python
You can find a full list of Public template
apps in the LiveKit examples repo.
The following example is based off the voice-pipeline-agent-python
example app. The entrypoint
function is modified to identify SIP participants.
Add the following line near the top of your
agent.py
file to import thertc
module:from livekit import rtcReplace the
entrypoint
function with the following code:async def entrypoint(ctx: JobContext):initial_ctx = llm.ChatContext().append(role="system",text=("You are a voice assistant created by LiveKit. Your interface with users will be voice. ""You should use short and concise responses, and avoiding usage of unpronouncable punctuation. ""You were created as a demo to showcase the capabilities of LiveKit's agents framework."),)logger.info(f"connecting to room {ctx.room.name}")await ctx.connect(auto_subscribe=AutoSubscribe.AUDIO_ONLY)# Wait for the first participant to connectparticipant = await ctx.wait_for_participant()logger.info(f"starting voice assistant for participant {participant.identity}")# Default Deepgram modeldg_model = "nova-2-general"# Check if the participant is a SIP participantif participant.kind == rtc.ParticipantKind.PARTICIPANT_KIND_SIP:# Use a Deepgram model better suited for phone callsdb_model = "nova-2-phonecall"# Do something here based on SIP participant attributes# For example, look up customer information using their phone number# If this caller is calling from a specific phone number, do somethingif participant.attributes['sip.phoneNumber'] == '+15105550100':logger.info("Caller phone number is +1-510-555-0100")# This project is configured to use Deepgram STT, OpenAI LLM and TTS plugins# Other great providers exist like Cartesia and ElevenLabs# Learn more and pick the best one for your app:# https://docs.livekit.io/agents/pluginsassistant = VoicePipelineAgent(vad=ctx.proc.userdata["vad"],stt=deepgram.STT(model=dg_model),llm=openai.LLM(model="gpt-4o-mini"),tts=openai.TTS(),chat_ctx=initial_ctx,)assistant.start(ctx.room, participant)# The agent should be polite and greet the user when it joins :)await assistant.say("Hey, how can I help you today?", allow_interruptions=True)
Creating a SIP participant to make outbound calls
To make outbound calls, create a SIP participant. To learn more, see Make outbound calls.