Conversational Video Interface

Create Conversation

With the Tavus Conversational Video Interface (CVI) you are able to create a conversation with a replica in real time.

Conversations

A conversation is a video call with a replica.

After creating a conversation, a conversation_url will be returned in the response. The conversation_url can be used to join the conversation directly or can be embedded in a website. To embed the conversation_url in a website, you can find instructions here.

Once a conversation is created, the replica will automatically join the call and will start participating.

By providing a callback_url, you can receive webhooks with updates regarding the conversation state.

Learn about recording conversations here.

POST

conversations

curl --request POST \
  --url https://tavusapi.com/v2/conversations \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
  "replica_id": "r79e1c033f",
  "persona_id": "p5317866",
  "callback_url": "https://yourwebsite.com/webhook",
  "conversation_name": "A Meeting with Hassaan",
  "conversational_context": "You are about to talk to Hassaan, one of the cofounders of Tavus. He loves to talk about AI, startups, and racing cars.",
  "custom_greeting": "Hey there Hassaan, long time no see!",
  "properties": {
    "max_call_duration": 3600,
    "participant_left_timeout": 60,
    "participant_absent_timeout": 300,
    "enable_recording": true,
    "enable_transcription": true,
    "apply_greenscreen": true,
    "language": "english",
    "recording_s3_bucket_name": "conversation-recordings",
    "recording_s3_bucket_region": "us-east-1",
    "aws_assume_role_arn": ""
  }
}'

{
  "conversation_id": "c123456",
  "conversation_name": "A Meeting with Hassaan",
  "status": "active",
  "conversation_url": "https://tavus.daily.co/c123456",
  "replica_id": "r79e1c033f",
  "persona_id": "p5317866",
  "created_at": "<string>"
}

Authorizations

x-api-key

string

header

required

Body

application/json

replica_id

string

The unique identifier for the replica that will join the conversation.

persona_id

string

The unique identifier for the persona that the replica will use in the conversation.

callback_url

string

A url that will receive webhooks with updates regarding the conversation state.

conversation_name

string

A name for the conversation.

conversational_context

string

Optional context that will be appended to any context provided in the persona, if one is provided.

custom_greeting

string

An optional custom greeting that the replica will give once a participant joines the conversation.

properties

object

Optional properties that can be used to customize the conversation.

properties.max_call_duration

integer

The maximum duration of the call in seconds. The default max_call_duration is 3600 seconds (1 hour). Once the time limit specified by this parameter has been reached, the conversation will automatically shut down.

properties.participant_left_timeout

integer

The duration in seconds after which the call will be automatically shut down once the last participant leaves.

properties.participant_absent_timeout

integer

Starting from conversation creation, the duration in seconds after which the call will be automatically shut down if no participant joins the call. Default is 300 seconds (5 minutes).

properties.enable_recording

boolean

If true, the user will be able to record the conversation. You can find more instructions on recording here.

properties.enable_transcription

boolean

If true, the user will be able to transcribe the conversation. You can find more instructions on displaying transcriptions if you are using your custom DailyJS components here. You need to have an event listener on Daily that listens for app-messages.

properties.apply_greenscreen

boolean

If true, the background will be replaced with a greenscreen (RGB values: [0, 255, 155]). You can use WebGL on the frontend to make the greenscreen transparent or change its color.

properties.language

string

The language of the conversation. Please provide the FULL language name, not the two letter code. If you are using your own TTS voice, please ensure it supports the language you provide. If you are using a stock replica or default persona, please note that only Elevenlabs and Cartesia supported languages are available. You can find a full list of supported languages for Cartesia here, for ElevenLabs here and for PlayHT here

properties.recording_s3_bucket_name

string

The name of the S3 bucket where the recording will be stored.

properties.recording_s3_bucket_region

string

The region of the S3 bucket where the recording will be stored.

properties.aws_assume_role_arn

string

The ARN of the role that will be assumed to access the S3 bucket.

Response

200 - application/json

conversation_id

string

A unique identifier for the conversation.

conversation_name

string

The name of the conversation.

status

string

The status of the conversation. Possible values: active, ended.

conversation_url

string

A direct link to join the conversation. This link can be used to join the conversation directly or can be embedded in a website.

replica_id

string

A unique identifier for the replica used to create this conversation.

persona_id

string

A unique identifier for the persona used to create this conversation.

created_at

string

The date and time the conversation was created.

Rename Video Get Conversation

curl --request POST \
  --url https://tavusapi.com/v2/conversations \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
  "replica_id": "r79e1c033f",
  "persona_id": "p5317866",
  "callback_url": "https://yourwebsite.com/webhook",
  "conversation_name": "A Meeting with Hassaan",
  "conversational_context": "You are about to talk to Hassaan, one of the cofounders of Tavus. He loves to talk about AI, startups, and racing cars.",
  "custom_greeting": "Hey there Hassaan, long time no see!",
  "properties": {
    "max_call_duration": 3600,
    "participant_left_timeout": 60,
    "participant_absent_timeout": 300,
    "enable_recording": true,
    "enable_transcription": true,
    "apply_greenscreen": true,
    "language": "english",
    "recording_s3_bucket_name": "conversation-recordings",
    "recording_s3_bucket_region": "us-east-1",
    "aws_assume_role_arn": ""
  }
}'

{
  "conversation_id": "c123456",
  "conversation_name": "A Meeting with Hassaan",
  "status": "active",
  "conversation_url": "https://tavus.daily.co/c123456",
  "replica_id": "r79e1c033f",
  "persona_id": "p5317866",
  "created_at": "<string>"
}

Phoenix Replicas

Videos

Conversational Video Interface

Replica Personas

Speech

Create Conversation

Conversations

Authorizations

Body

Response