​
Video Callbacks

If a callback_url is providing in the POST /videos call, you will receive callbacks on video generation completed and on video error.

​
Video Generation Completed

{
  "created_at": "2024-08-28 15:27:40.824457",
  "data": {
    "script": "Hello this is a test to give examples of callbacks"
  },
  "download_url": "https://stream.mux.com/H5H029h02tY7XDpNj9JFDbLleTyUpsJr5npddO8gRsKqY/high.mp4?download=1e30440cf9",
  "generation_progress": "100/100",
  "hosted_url": "https://videos.tavus.io/video/1e30440cf9",
  "replica_id": "r79e1c033f",
  "status": "ready",
  "status_details": "Your request has processed successfully!",
  "stream_url": "https://stream.mux.com/H5H029h02tY7XDpNj9JFDbLleTyUpsJr5npddO8gRsKqY.m3u8",
  "updated_at": "2024-08-28 15:29:19.802670",
  "video_id": "1e30440cf9",
  "video_name": "replica_id: r79e1c033f - August 28, 2024 - video: 1e30440cf9"
}

​
Video Generation Error

On error, the status_details parameter will contain the error message. You can learn more about API Errors and Status Details here

{
  "created_at": "2024-08-28 15:32:53.058894",
  "data": {
    "script": "This is a test script to show how videos error"
  },
  "download_url": null,
  "error_details": null,
  "generation_progress": "0/100",
  "hosted_url": "https://videos.tavus.io/video/c9b85a6d36",
  "replica_id": "ra5ed77426",
  "status": "error",
  "status_details": "An error occurred while generating this request. Please check your inputs or try your request again.",
  "stream_url": null,
  "updated_at": "2024-08-28 15:35:03.762392",
  "video_id": "c9b85a6d36",
  "video_name": "replica_id: ra5ed77426 - August 28, 2024 - video: c9b85a6d36"
}

​
Replica Training

If a callback_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_id": "rxxxxxxxxx",
  "status": "ready",
}

​
Replica Training Error

On error, the error_message parameter will contain the error message. You can learn more about API Errors and Status Details here

{
  "replica_id": "rxxxxxxxxx",
  "status": "error",
  "error_message": "There was an issue processing your training video. The video provided does not meet the minimum duration requirement for training"
}

​
Conversations

​
Overview

If callback_url is provided in the Create Conversation API Request, callbacks will be sent to provide inside into the state of the conversation. Our callbacks range from system-related callbacks like replica joins and room shutdowns, to application-related callbacks like final transcription parsing and recording ready webhooks, with many more webhooks coming soon!

​
Callback 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 reached, participant_left_timeout reached, participant_absent_timeout reached, internal 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 if you had enabled recording on, set up a custom S3 bucket for recording and started a recording inside the room at any point. This will point to the key at which your new recording lies, useful for serving recordings through a CDN.
API Errors and Status DetailsChangelog