Tavus sends JSON payloads to theDocumentation Index
Fetch the complete documentation index at: https://docs.tavus.io/llms.txt
Use this file to discover all available pages before exploring further.
callback_url you configure on each resource. On your server, read the body and branch on event_type (and message_type where noted). This page covers five callback areas: conversation events (below), guardrails, objectives, replica training, and video generation—payload shapes differ, and most event-specific fields live under properties.
Conversation Callbacks
If acallback_url is provided when you call POST https://tavusapi.com/v2/conversations (Create Conversation), callbacks will provide insight into the conversation’s state. These can be system-related (e.g. replica joins and room shutdowns) or application-related (e.g. final transcription parsing and recording-ready webhooks). Additional webhooks coming soon.
Structure
All Conversation callbacks share the following basic structure. Differences will occur in theproperties object.
Types
Our callbacks are split into two main categories:System Callbacks
These callbacks are to provide insight into system-related events in a conversation. They are:- system.replica_joined: This is fired when the replica becomes ready for a conversation.
- system.shutdown: This is fired when the room shuts down, for any of the following reasons:
max_call_duration reachedparticipant_left_timeout reachedparticipant_absent_timeout reachedbot_could_not_join_meeting_it_was_probably_endeddaily_room_has_been_deletedexception_encountered_during_conversation_startupend_conversation_endpoint_hitinternal error occurred at step x
Application Callbacks
These callbacks are to inform developers about logical events that take place. They are:- application.transcription_ready: This is fired after ending a conversation, where the chat history is saved and returned.
- application.recording_ready: This is fired once your recording is durably written to your storage destination. Includes
storage_provider(s3/gcs/azure_blob) and a fully-qualifiedstorage_uriso the same handler works across providers. See Recording Storage to set up GCS, Azure, or S3-in-any-region destinations. - application.recording_copy_failed: This is fired only on the worker-copy path (GCS, Azure, or S3 in regions Daily doesn’t support natively) when Tavus is unable to deliver the recording into your bucket after retries. Daily’s default storage retains the recording for ~30 days as a manual recovery window. Common causes: customer IAM trust policy mismatch, federated credential drift, bucket region typo. Use this as the canary for misconfiguration in your end.
- application.perception_analysis: This is fired after ending a conversation, when the replica has finished summarizing the visual artifacts that were detected throughout the call. This is a feature that is only available when the persona has
raven-1specified in the Perception Layer.
Guardrail Callbacks
If acallback_url is provided on a guardrail, a callback is sent when that guardrail is triggered during a conversation.
Objective Callbacks
If acallback_url is provided on an objective, a callback is sent when that objective is completed during a conversation.
Replica Training Callbacks
If acallback_url is provided in the POST /replicas call, you will receive a callback on replica training completion or on replica training error.
- Replica Training Completed
- Replica Training Error
Video Generation Callbacks
If acallback_url is provided in the POST /videos call, you will receive callbacks on video generation completed and on video error.
- Video Generation Completed
- Video Generation Error
Sample Webhook Setup
Create a sample webhook endpoint using Python Flask, and expose it publicly with ngrok.Prerequisites
Step 2: Make a Webhook Server
Set up a webhook server and save it as The server will receive and process webhook callbacks from Tavus, handle different event types, store transcripts in memory, and analyze conversation data for each session.
server.py.Step 3: Run the Server
Run the app using the following command in the terminal:The server should run on port
5000.Step 4: Forward the Port Using Ngrok
With ngrok installed and on your PATH, forward the port from a terminal (on Windows you can run The command will generate a forwarding link (e.g., https://1234567890.ngrok-free.app), which can be used as the callback URL.
ngrok.exe from the install folder instead).Step 5: Use the Callback URL
Include the callback URL in your request to Tavus by appending
/webhook to the forwarding link and setting it in the callback_url field.Create conversation with callback_url
- Replace
<api-key>with your actual API key. You can generate one in the Developer Portal. - Replace
<replica_id>with the Replica ID you want to use. - Replace
<persona_id>with the Persona ID you want to use.

