Call forwarding

twilio api trunking v1 trunks update --sid <twilio-trunk-sid> \
--transfer-mode enable-all \
--transfer-caller-id from-transferee

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

// ...

async function transferParticipant(participant) {
  console.log('transfer participant initiated');

  const api = new LiveKitAPI();
  const transferTo = 'tel:+15105550100';

  try {
    await api.sip.transferSipParticipant('open-room', participant.identity, transferTo, {
      playDialtone: false,
    });
    console.log('SIP participant transferred successfully');
  } catch (error) {
    if (error instanceof ServerError) {
      // Why the transfer failed, for example STR_REJECTED
      const transferReason = error.metadata?.sip_transfer_reason;
      if (transferReason) {
        console.error('Transfer failure reason: ', transferReason);
      }
      if (error instanceof SipCallError) {
        // Only set when the destination or its provider reports a SIP status
        console.error('SIP error code: ', error.sipStatusCode);
        console.error('SIP error message: ', error.sipStatus);
      } else if (!transferReason) {
        console.error('Error transferring SIP participant: ', error.code, error.message);
      }
    } else {
      console.error('Error transferring SIP participant: ', error);
    }
  }
}

import logging

from livekit import api

logger = logging.getLogger("transfer-logger")
logger.setLevel(logging.INFO)

async def transfer_call(participant_identity: str, room_name: str) -> None:
  async with api.LiveKitAPI() as livekit_api:
    transfer_to = 'tel:+14155550100'

    try:
      await livekit_api.sip.transfer_sip_participant(
          api.TransferSIPParticipantRequest(
              participant_identity=participant_identity,
              room_name=room_name,
              transfer_to=transfer_to,
              play_dialtone=False,
          )
      )
      print("SIP participant transferred successfully")
    except api.SipCallError as error:
      # Why the transfer failed, for example STR_REJECTED
      if error.sip_transfer_reason is not None:
        print(f"Transfer failure reason: {error.sip_transfer_reason}")
      # Only set when the destination or its provider reports a SIP status
      if error.sip_status_code is not None:
        print(f"SIP error code: {error.sip_status_code}")
        print(f"SIP error message: {error.sip_status}")
    except api.ServerError as error:
      print(f"Error transferring SIP participant: {error.code} - {error.message}")

require 'livekit'

room_name = 'open-room'
participant_identity = 'participant_identity'

def transferParticipant(room_name, participant_identity)
  lkapi = LiveKit::LiveKitAPI.new

  transfer_to = 'tel:+14155550100'

  begin
    lkapi.sip.transfer_sip_participant(
      room_name,
      participant_identity,
      transfer_to,
      play_dialtone: false
    )
    puts "SIP participant transferred successfully"
  rescue LiveKit::ServerError => e
    # Why the transfer failed, for example STR_REJECTED
    transfer_reason = e.metadata["sip_transfer_reason"]
    puts "Transfer failure reason: #{transfer_reason}" if transfer_reason
    if e.is_a?(LiveKit::SipCallError)
      # Only set when the destination or its provider reports a SIP status
      puts "SIP error code: #{e.sip_status_code}"
      puts "SIP error message: #{e.sip_status}"
    elsif transfer_reason.nil?
      puts "Error transferring SIP participant: #{e.code} #{e.message}"
    end
  end
end

import (
	"context"
	"errors"
	"fmt"

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

func transferParticipant(ctx context.Context, participantIdentity string) {
	roomName := "open-room"
	transferTo := "tel:+14155550100"

	// Reads LIVEKIT_URL, LIVEKIT_API_KEY, and LIVEKIT_API_SECRET from the environment.
	api, err := lksdk.NewLiveKitAPI()
	if err != nil {
		fmt.Println("Error:", err)
		return
	}

	transferRequest := &livekit.TransferSIPParticipantRequest{
		RoomName:            roomName,
		ParticipantIdentity: participantIdentity,
		TransferTo:          transferTo,
		PlayDialtone:        false,
	}

	_, err = api.SIP().TransferSIPParticipant(ctx, transferRequest)
	if err != nil {
		// Why the transfer failed, for example STR_REJECTED
		transferErr := lksdk.SIPTransferErrorFrom(err)
		if transferErr != nil {
			fmt.Println("Transfer failure reason:", transferErr.Reason)
		}
		// Only set when the destination or its provider reports a SIP status
		if s := lksdk.SIPStatusFrom(err); s != nil {
			fmt.Printf("SIP error: %d %s\n", s.Code, s.Status)
		} else if transferErr == nil {
			var se lksdk.ServerError
			if errors.As(err, &se) {
				fmt.Printf("Error transferring SIP participant: %s %s\n", se.Code(), se.Msg())
			} else {
				fmt.Println("Error:", err)
			}
		}
		return
	}

	fmt.Println("SIP participant transferred successfully")
}

import io.livekit.server.LiveKitAPI
import io.livekit.server.SipCallError
import io.livekit.server.ServerError

fun transferParticipant(roomName: String, participantIdentity: String) {
    // Reads LIVEKIT_URL, LIVEKIT_API_KEY, and LIVEKIT_API_SECRET from the environment.
    val api = LiveKitAPI.createClient()

    val transferTo = "tel:+14155550100"

    val response = api.sip.transferSipParticipant(
        roomName,
        participantIdentity,
        transferTo,
        io.livekit.server.TransferSipParticipantOptions(playDialtone = false),
    ).execute()

    if (response.isSuccessful) {
        println("SIP participant transferred successfully")
    } else {
        // Decode the error once: reading the response body consumes it
        val error = ServerError.from(response)
        // Why the transfer failed, for example STR_REJECTED
        val transferReason = error?.metadata?.get("sip_transfer_reason")
        if (transferReason != null) {
            println("Transfer failure reason: $transferReason")
        }
        if (error is SipCallError) {
            // Only set when the destination or its provider reports a SIP status
            println("SIP error code: ${error.sipStatusCode}")
            println("SIP error message: ${error.sipStatus}")
        } else if (transferReason == null) {
            println("Error transferring SIP participant: ${error?.code} ${error?.message}")
        }
    }
}

use livekit_api::services::sip::TransferSIPParticipantOptions;
use livekit_api::services::{LiveKitApi, ServerError, ServiceError, SipCallError};

#[tokio::main]
async fn main() {
    let api = LiveKitApi::new("https://my-project.livekit.cloud").unwrap();

    let room_name = "open-room".to_owned();
    let participant_identity = "<participant-identity>".to_owned();
    let transfer_to = "tel:+14155550100".to_owned();

    let result = api
        .sip()
        .transfer_sip_participant(
            room_name,
            participant_identity,
            transfer_to,
            TransferSIPParticipantOptions { play_dialtone: Some(false), ..Default::default() },
        )
        .await;

    match result {
        Ok(()) => println!("SIP participant transferred successfully"),
        Err(e) => {
            // Why the transfer failed, for example STR_REJECTED
            let transfer_reason = match &e {
                ServiceError::Twirp(ServerError::Twirp(code)) => {
                    code.meta.get("sip_transfer_reason").cloned()
                }
                _ => None,
            };
            if let Some(reason) = &transfer_reason {
                println!("Transfer failure reason: {reason}");
            }
            if let Some(sip) = SipCallError::from_error(&e) {
                // Only set when the destination or its provider reports a SIP status
                println!("SIP error code: {}", sip.sip_status_code().unwrap_or_default());
                println!("SIP error message: {}", sip.sip_status().unwrap_or_default());
            } else if transfer_reason.is_none() {
                eprintln!("Error transferring SIP participant: {e}");
            }
        }
    }
}

lk sip participant transfer --room <CURRENT_ROOM> \
  --identity <PARTICIPANT_ID> \
  --to "<SIP_ENDPOINT>"

from livekit import api, rtc
from livekit.agents import Agent, RunContext, function_tool, get_job_context

class Assistant(Agent):
    ## ... existing init code ...

    @function_tool()
    async def transfer_call(self, ctx: RunContext):
        """Transfer the call to a human agent, called after confirming with the user"""

        transfer_to = "+15105550123"

        job_ctx = get_job_context()

        # Find the active SIP caller in the room. The identity is set at
        # dispatch time and might not match the caller's phone number.
        # Assumes a single SIP caller per room.
        sip_participant = next(
            (
                p for p in job_ctx.room.remote_participants.values()
                if p.kind == rtc.ParticipantKind.PARTICIPANT_KIND_SIP
            ),
            None,
        )
        if sip_participant is None:
            return "no active SIP caller to transfer"

        # let the message play fully before transferring
        await ctx.session.generate_reply(
            instructions="Inform the user that you're transferring them to a different agent."
        )

        try:
            await job_ctx.api.sip.transfer_sip_participant(
                api.TransferSIPParticipantRequest(
                    room_name=job_ctx.room.name,
                    participant_identity=sip_participant.identity,
                    # to use a sip destination, use `sip:user@host` format
                    transfer_to=f"tel:{transfer_to}",
                )
            )
        except Exception as e:
            print(f"error transferring call: {e}")
            # give the LLM that context
            return "could not transfer call"

pnpm add livekit-server-sdk

import { voice, llm, getJobContext } from '@livekit/agents';
import { LiveKitAPI } from 'livekit-server-sdk';
import { ParticipantKind } from '@livekit/rtc-node';
import { z } from 'zod';

export class Agent extends voice.Agent {
  constructor() {
    super({
      instructions: 'You are a helpful assistant.',
      tools: {
        transferCall: llm.tool({
          description:
            'Transfer the call to a human agent, called after confirming with the user.',
          parameters: z.object({}),
          execute: async (_, { ctx }) => {
            const transferTo = 'tel:+15105550123';
            const jobCtx = getJobContext();
            const room = jobCtx.room;

            // Find the active SIP caller in the room. The identity is set at
            // dispatch time and might not match the caller's phone number.
            // Assumes a single SIP caller per room.
            const sipParticipant = Array.from(room.remoteParticipants.values()).find(
              (p) => p.kind === ParticipantKind.SIP,
            );
            if (!sipParticipant) {
              return 'no active SIP caller to transfer';
            }

            // Let the message play fully before transferring
            ctx.session.generateReply({
              instructions: "Inform the user that you're transferring them to a different agent.",
            });
            await ctx.waitForPlayout();

            const api = new LiveKitAPI();

            try {
              await api.sip.transferSipParticipant(
                room.name!,
                sipParticipant.identity,
                transferTo,
                { playDialtone: false },
              );
            } catch (e) {
              console.log(`error transferring call: ${e}`);
              return 'could not transfer call';
            }
          },
        }),
      },
    });
  }
}