Phone calls reference

​

How a transfer works

1. A Transfer says where the caller goes and what happens when nobody answers.
2. A phone line is the call’s own leg. Build it per call, like CallHooks.
3. transfer_tool returns an ordinary tool. Hooks, spans, task tool lists and the end of the call treat it like any other tool. See Tools.
4. The model calls it with no arguments. It never sees the destination.
5. The tool says its line first, like “Putting you through now, one moment.” Once the transfer starts, the caller’s speech cannot cancel it, on either framework. On LiveKit the line itself cannot be cut off either, and neither can the lines a SipLine says. On Pipecat the caller can still cut the line off. Build the user aggregator with user_mute_strategies(protect=["tool_calls"]) to protect it.
6. The line transfers the caller. On success the call ends, with no model reply after it, and its end reason is transferred.
7. When nobody takes the transfer, on_unavailable decides:
   • return_to_caller is the default. The model reads why, like “The transfer failed (busy). Tell the caller and keep helping them.”
   • hangup makes the line say unavailable_line, then the call ends. Write that line in the call’s language.
8. A call with no phone leg, like a web call, tells the model so, and the agent keeps helping.
9. One transfer runs at a time per call. A second call of a transfer tool, the same one or another, tells the model one is already under way. After a transfer nobody took, the model may try again.

​

Transfer

​

transfer_tool

​

Phone numbers

from pydantic import BaseModel
from unmute_core.telephony import E164_PATTERN, E164Number, is_e164

is_e164("+34910000000")  # True
is_e164("0034910000000")  # False


class Callback(BaseModel):
    number: E164Number

​

Phone number checks

​

LiveKit SIP

​

An inbound call

participant = await ctx.wait_for_participant()
info = sip_call_info(participant, metadata, trunk_number=os.environ["SIP_NUMBER"])
state = CallState(State, call=info)

​

SipLine

trunk = api.SIPOutboundConfig(
    hostname=os.environ["SIP_ADDRESS"],
    auth_username=os.environ["SIP_USERNAME"],
    auth_password=os.environ["SIP_PASSWORD"],
)

​

An outbound call

line = SipLine(session, trunk=trunk, caller_id=os.environ["FROM_NUMBER"])
try:
    dialled = await line.dial(metadata["phone_number"], on_voicemail="leave_message")
except DialError as error:
    logger.info("nobody answered: %s", error.reason)  # busy, no answer, sip 503
    ctx.shutdown("dial failed")
    return
if not dialled.ended:
    greet(session, greeting, state)

1. dial checks the number is E.164, then calls it and waits for an answer.
2. LiveKit’s answering machine detection holds the agent’s speech until it knows who answered. It asks a model: detector_llm, else the session’s LLM, else the agent’s.
3. Voicemail hangs up, or leaves a message the model words. A full or missing mailbox hangs up. ended is then True. Pass SipLine(session, call=call) to note that end as agent_ended in the call’s hooks.
4. A number nobody answers raises DialError with the reason and the sip_status.

​

SipLine.dial

​

Cold transfer

​

Warm transfer

ESCALATE = Transfer(
    "escalate",
    "+34910000000",
    mode="warm",
    briefing="Mention that the caller is a VIP.",
)

1. The caller hears hold music.
2. The agent calls the person and briefs them from the chat. The briefing persona is BRIEFING_PERSONA, and briefing is added after it.
3. The person says they are ready, and the calls merge. The agent says connected_line and leaves.
4. When the person declines, does not answer, or is a voicemail, the caller comes back to the agent.

​

Pipecat on a carrier websocket

info = telephony_call_info(runner_args.call_data, trunk_number=os.environ["FROM_NUMBER"])
state = CallState(State, call=info)

line = TwilioLine(
    info.carrier_call_id,
    account_sid=os.environ["TWILIO_ACCOUNT_SID"],
    auth_token=os.environ["TWILIO_AUTH_TOKEN"],
    worker=worker,
    serializer=serializer,
)

​

TwilioLine

​

TelnyxLine

​

The serializer

​

An outbound call

<Response><Connect><Stream url="wss://your-bot/ws">
  <Parameter name="direction" value="outbound"/>
  <Parameter name="to_number" value="+34910000000"/>
</Stream></Connect></Response>

​

Pipecat in a Daily room over SIP

line = DailySipLine(transport, worker, sip_host=os.environ["SIP_ADDRESS"])
forward_dial_in(transport, body["call_sid"], account_sid=sid, auth_token=token)  # inbound
dial_out(transport, worker, "sip:+34910000000@trunk.example", call=call)  # outbound

1. forward_dial_in sends a Twilio call into the room once Daily gives the room’s SIP address. It runs once.
2. dial_out calls a SIP address once the bot joins. When that leg ends, the pipeline is cancelled. Other legs of the room end nothing. Pass call= and the callee hanging up ends the call with caller_hung_up. A leg that failed is no hang-up.
3. DailySipLine asks Daily to call the person through your trunk, then waits until they answer, up to the ring timeout. A transfer nobody answers leaves the caller with the agent. Once the person answers, the agent leaves and Daily keeps bridging the two legs, so both are billed until the call ends. An event about the caller’s own leg settles no transfer.

​

voicemail_tool

​

Where to go next