what does

play_dialtone

option do on a sip transfer?

Thanks for reaching out, Ahron. I'm an AI assistant and I'm here to help. Give me a moment while I research this topic.

Is there a way to notify the agent that handle.addDoneCallback had an error?

Thanks — I’m responding about notifying an agent when

handle.add_done_callback

has an error. I do not have any documented mechanism that explicitly reports errors inside

SpeechHandle.add_done_callback()

back to an agent. The sources describe that

add_done_callback()

can trigger actions when playback completes, but they do not describe how to detect or surface exceptions raised inside that callback or how the system would notify an agent of such failures. I can still help — a few options you can consider depending on your implementation: • Instrument the callback to catch and report errors yourself a. Wrap the callback body in a try/except (or equivalent) and log the exception. b. From the except block, send a notification to the agent: for example, emit an event over your signaling channel, post a message to an agent UI, or call your backend alerting endpoint. • Use centralized logging/monitoring ◦ Ensure the callback logs errors to your application logs or an error-tracking service (Sentry, Logflare, etc.). Agents or on-call staff can be notified from those systems. • Surface an explicit status to the agent ◦ Have your callback update the participant/agent state (e.g., set a

playback_status

field to

error

) that the agent UI polls or subscribes to, so the agent sees the failure in real time. If you tell me: • which language/runtime you’re using for the callback (Python, JavaScript, etc.), and • how agents are reached (in-app UI, signaling messages, email, etc.), I’ll provide a short code example and the simplest pattern to notify agents in your environment. Sources: Agent speech and audio | LiveKit Documentation | How to detect when an agent has finished speaking | LiveKit

my question basically is, how can I let the agent know when an error occurs somewhere so it can notify the user.

Thanks — I’m responding to your clarified question: you want to let the agent know when an error occurs inside a callback (for example, a callback added via

handle.add_done_callback

) so the agent can notify the end user. LiveKit does not automatically surface exceptions raised inside background callbacks to an agent UI or session. You must catch and propagate those errors yourself. Here are practical, low-friction approaches you can use. 1) Catch errors inside the callback and notify the agent • Wrap the callback body in try/except and, on error, call whatever agent-facing API you already have (for example,

session.generate_reply()

, send a signaling message, or push an update to the agent UI). • Ensure the agent/session context is captured by the callback (via closure or shared state). Example (Python-like)

def playback_done(handle):
    try:
        if exc := handle.exception():
            raise exc
        # normal completion logic
    except Exception as e:
        logger.error(f"Playback callback error: {e}")
        # notify the agent asynchronously
        asyncio.create_task(session.generate_reply(
            instructions=f"Sorry, there was an error: {str(e)}. Please try again."
        ))

2) Use the handle’s API to check for exceptions • Many handle objects expose

exception()

(or similar). Call that from the callback to detect errors and react accordingly rather than relying on an uncaught exception to bubble up. 3) Prefer awaiting when possible (simpler error flow) • If your flow allows blocking until playout finishes,

await handle.wait_for_playout()

lets you catch exceptions in the calling coroutine and respond immediately:

handle = session.say("Playing...")
try:
    await handle.wait_for_playout()
except Exception as e:
    await session.generate_reply(instructions=f"An error occurred: {e}")

This avoids the extra complexity of cross-task error propagation. 4) Deliver the notification to the agent — options • Have the callback call

session.generate_reply()

(or equivalent) to create a spoken or text reply to the user. • Emit a signaling message/event the agent UI subscribes to (e.g., WebSocket) with an error status so the agent can take action. • Update a shared status field (e.g.,

playback_status = "error"

) that the agent UI polls or observes. 5) Add centralized logging/alerting for visibility • Log exceptions from callbacks to your monitoring system (Sentry, Stackdriver, etc.) so agents or on-call staff can be alerted for systemic failures, even if a single user notification also happens. Quick checklist to implement: • Ensure

session

or agent context is accessible inside the callback. • Call

handle.exception()

inside the callback and handle any exception. • Notify the agent via

session.generate_reply()

, signaling message, or UI state update. • Optionally log the error to your observability system for follow-up. If you tell me: • which runtime/language you’re using (Python, Node), and • how agents are reached (in-app UI, signaling channel, or voice response), I’ll give a focused code example and the minimal pattern to wire this into your agent notification flow. Sources: How to detect when an agent has finished speaking | LiveKit