> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tavus.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Create conversation
> This endpoint starts a real-time video conversation with your AI replica, powered by a persona that allows it to see, hear, and respond like a human.
For AI agents, use `https://docs.tavus.io/openapi.yaml` for the full HTTP API contract.
## OpenAPI
````yaml post /v2/conversations
openapi: 3.0.3
info:
title: Tavus Developer API Collection
version: 1.0.0
contact: {}
servers:
- url: https://tavusapi.com
security:
- apiKey: []
tags:
- name: Videos
- name: Replicas
- name: Voices
- name: Conversations
- name: Personas
- name: Pronunciation Dictionaries
- name: Replacements
- name: Transcriptions
- name: Documents
paths:
/v2/conversations:
post:
tags:
- Conversations
description: >
This endpoint starts a real-time video conversation with your AI
replica, powered by a persona that allows it to see, hear, and respond
like a human.
operationId: createConversation
requestBody:
content:
application/json:
schema:
type: object
properties:
replica_id:
type: string
description: >-
The unique identifier for the replica that will join the
conversation. **Each request must have a valid `replica_id`
value that's either directly passed in or as part of a
persona**.
example: r90bbd427f71
persona_id:
type: string
description: >
The unique identifier for the persona that the replica will
use in the conversation.
- **If your Persona does not have a valid `replica_id`, you
must define the `replica_id` field.**
- **If your Persona already has a valid `replica_id` and you
provide one in the request, the `replica_id` provided in the
request will be used instead of the one defined in your
persona**.
example: pcb7a34da5fe
audio_only:
type: boolean
description: >-
Specifies whether the interaction should be voice-only.
**This field is required if you want to create an audio-only
conversation**.
example: 'false'
callback_url:
type: string
description: >-
A url that will receive webhooks with updates regarding the
conversation state.
example: https://yourwebsite.com/webhook
conversation_name:
type: string
description: A name for the conversation.
example: Improve Sales Technique
conversational_context:
type: string
description: >-
Optional context that will be appended to any context
provided in the persona, if one is provided.
example: >-
I want to improve my sales techniques. Help me practice
handling common objections from clients and closing deals
more effectively.
custom_greeting:
type: string
description: >-
An optional custom greeting that the replica will give once
a participant joines the conversation.
example: Hey there!
memory_stores:
type: array
items:
type: string
description: >-
The memory stores to use for the conversation. The persona
will have access to the existing memories in the store and
will add newly made memories to the store as well. In most
use cases, you will only need to pass in a single memory
store.
example:
- anna
document_ids:
type: array
items:
type: string
description: >-
The ids of the documents that the persona will be able to
access during the conversation. The `document_ids` are
returned during the document creation process in the
response of the [Get
Document](/api-reference/documents/get-document) and the
[Create Document](/api-reference/documents/create-document)
endpoints.
example:
- doc_1234567890
document_retrieval_strategy:
type: string
description: >-
The strategy to use for document retrieval. Possible values:
`speed`, `quality`, `balanced`. Default is `balanced`.
example: balanced
document_tags:
type: array
items:
type: string
description: >-
The tags of the documents that the replica will be able to
access during the conversation. The tags are passed in the
`document_tags` parameter of the [Create
Document](/api-reference/documents/create-document)
endpoint. The document tags do not have to be created
explicitly, it is enough to pass in the tags during the
document creation process.
example:
- sales
- marketing
test_mode:
type: boolean
description: >-
If true, the conversation will be created but the replica
will not join the call. This can be used for testing the
conversation creation process without incurring any costs.
Additionally, the conversation will be created with a status
`ended` so it does not affect concurrency limits.
example: false
require_auth:
type: boolean
description: >-
If true, creates a private room requiring authentication. A
`meeting_token` will be returned in the response that must
be used to join the conversation. Without a valid token,
users will see 'You are not allowed to join this meeting.'
example: false
max_participants:
type: integer
minimum: 2
description: >-
Maximum number of participants allowed in the conversation
room. Must be at least 2 (the replica counts as one
participant).
example: 2
properties:
type: object
description: >-
Optional properties that can be used to customize the
conversation.
properties:
max_call_duration:
type: integer
description: >-
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.
example: 3600
participant_left_timeout:
type: integer
description: >-
The duration in seconds after which the call will be
automatically shut down once the last participant
leaves.
example: 60
participant_absent_timeout:
type: integer
description: >-
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).
example: 300
enable_recording:
type: boolean
description: >-
If true, the user will be able to record the
conversation. You can find more instructions on
recording
[here](/sections/conversational-video-interface/quickstart/conversation-recordings#conversation-recordings).
example: true
enable_closed_captions:
type: boolean
description: >-
If true, the user will be able to display closed
captions (subtitles) during the conversation. You can
find more instructions on displaying closed captions if
you are using your custom DailyJS components
[here](https://docs.daily.co/reference/daily-js/events/transcription-events#transcription-message).
You need to have an [event
listener](https://docs.daily.co/reference/daily-js/events)
on Daily that listens for app-messages.
example: true
apply_greenscreen:
type: boolean
description: >-
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.
example: true
language:
type: string
description: >-
The language of the conversation. Please provide the
FULL language name, not the two letter code, or specify
`multilingual` for automatic language detection. When
set to `multilingual`, CVI will use STT language
detection to identify the user's spoken language and
respond accordingly. 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](https://docs.cartesia.ai/2024-11-13/build-with-cartesia/models#language-support),
and for ElevenLabs
[here](https://elevenlabs.io/languages).
example: multilingual
recording_s3_bucket_name:
type: string
deprecated: true
description: >
**Deprecated.** Use `recording_storage` (also on
`properties`) instead. The name of the S3 bucket where
the recording will be stored. Existing integrations
using this flat field continue to work unchanged.
example: conversation-recordings
recording_s3_bucket_region:
type: string
deprecated: true
description: >
**Deprecated.** Use `recording_storage` (also on
`properties`) instead. The region of the S3 bucket where
the recording will be stored. Existing integrations
using this flat field continue to work unchanged.
example: us-east-1
aws_assume_role_arn:
type: string
deprecated: true
description: >
**Deprecated.** Use `recording_storage` (also on
`properties`) instead. The ARN of the role that will be
assumed to access the S3 bucket. Existing integrations
using this flat field continue to work unchanged.
example: ''
recording_storage:
$ref: '#/components/schemas/recording_storage_config'
examples:
Required Parameters Only:
value:
replica_id: r90bbd427f71
persona_id: pcb7a34da5fe
Full Customizations:
value:
replica_id: r90bbd427f71
persona_id: pcb7a34da5fe
callback_url: https://yourwebsite.com/webhook
conversation_name: Improve Sales Technique
conversational_context: >-
I want to improve my sales techniques. Help me practice
handling common objections from clients and closing deals
more effectively.
properties:
max_call_duration: 1800
participant_left_timeout: 60
participant_absent_timeout: 120
language: multilingual
enable_closed_captions: true
apply_greenscreen: true
Audio Only:
value:
replica_id: r90bbd427f71
persona_id: pcb7a34da5fe
audio_only: true
Private Room:
value:
replica_id: r90bbd427f71
persona_id: pcb7a34da5fe
require_auth: true
Recording Storage - Amazon S3:
value:
replica_id: rf4e9d9790f0
persona_id: pcb7a34da5fe
properties:
enable_recording: true
recording_storage:
provider: s3
bucket_name: conversation-recordings
bucket_region: us-east-1
assume_role_arn: arn:aws:iam::123456789012:role/TavusRecordingWriter
external_id: tavus-acct-abc123
Recording Storage - Google Cloud Storage:
value:
replica_id: rf4e9d9790f0
persona_id: pcb7a34da5fe
properties:
enable_recording: true
recording_storage:
provider: gcs
bucket_name: conversation-recordings
project_id: my-gcp-project
workload_identity_provider: >-
projects/123456/locations/global/workloadIdentityPools/tavus-recording-pool/providers/tavus-worker
service_account_email: >-
tavus-recording-writer@my-gcp-project.iam.gserviceaccount.com
Recording Storage - Azure Blob Storage:
value:
replica_id: rf4e9d9790f0
persona_id: pcb7a34da5fe
properties:
enable_recording: true
recording_storage:
provider: azure_blob
storage_account: myrecordingsaccount
container: conversation-recordings
tenant_id: 11111111-2222-3333-4444-555555555555
client_id: 66666666-7777-8888-9999-000000000000
responses:
'200':
description: ''
content:
application/json:
schema:
type: object
properties:
conversation_id:
type: string
description: A unique identifier for the conversation.
example: c123456
conversation_name:
type: string
description: The name of the conversation.
example: A Meeting with Hassaan
conversation_url:
type: string
description: >-
A direct link to join the conversation. This link can be
used to join the conversation directly or can be embedded
in a website.
example: https://tavus.daily.co/c123456
status:
type: string
description: >-
The status of the conversation. Possible values: `active`,
`ended`.
example: active
callback_url:
type: string
description: >-
The url that will receive webhooks with updates of the
conversation state.
example: sample.com/callback
created_at:
type: string
description: The date and time the conversation was created.
example:
meeting_token:
type: string
description: >-
A short-lived JWT token required to join the conversation.
Only returned when `require_auth` is true. Append as
`?t=TOKEN` to the conversation URL or pass to Daily SDK's
join() method.
example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
'400':
description: Bad Request
content:
application/json:
schema:
type: object
properties:
error:
type: string
description: The error message.
example: >-
There was an error creating the conversation, please reach
out to support at support@tavus.io!
'401':
description: UNAUTHORIZED
content:
application/json:
schema:
type: object
properties:
message:
type: string
description: The error message.
example: Invalid access token
components:
schemas:
recording_storage_config:
type: object
description: >
Provider-agnostic recording storage configuration. Supports Amazon S3
(any region),
Google Cloud Storage via Workload Identity Federation, and Azure Blob
Storage via
Entra ID Federated Credentials. All fields are non-secret identifiers —
every
provider uses federated identity, so you configure a trust relationship
on your
side and pass identifiers to us, never credentials.
Use this in place of the legacy `recording_s3_bucket_name` /
`recording_s3_bucket_region` /
`aws_assume_role_arn` fields. Existing customers using the flat fields
continue to
work unchanged.
required:
- provider
properties:
provider:
type: string
enum:
- s3
- gcs
- azure_blob
description: Storage provider discriminator.
example: s3
bucket_name:
type: string
description: Bucket name. Used when `provider` is `s3` or `gcs`.
example: conversation-recordings
bucket_region:
type: string
description: >
AWS region (e.g. `us-east-1`, `eu-north-1`). Used when `provider` is
`s3`. Any AWS region is
supported — Daily-supported regions get a direct write; others are
routed through a Tavus-managed
Cloudflare Worker that copies the recording into your bucket via
`sts:AssumeRole`.
example: us-east-1
assume_role_arn:
type: string
description: >-
IAM role ARN that Tavus assumes to write to your bucket. Used when
`provider` is `s3`.
example: arn:aws:iam::123456789012:role/TavusRecordingWriter
external_id:
type: string
description: >-
Optional `ExternalId` value to include in the AssumeRole call. Used
when `provider` is `s3`.
example: tavus-acct-abc123
project_id:
type: string
description: GCP project ID containing the bucket. Used when `provider` is `gcs`.
example: my-gcp-project
workload_identity_provider:
type: string
description: >
Resource name of your Workload Identity Pool Provider — without the
`//iam.googleapis.com/`
prefix (Tavus prepends it). Used when `provider` is `gcs`.
example: >-
projects/123456/locations/global/workloadIdentityPools/tavus-pool/providers/tavus-cf-worker
service_account_email:
type: string
description: >-
Email of the service account that has `storage.objects.create` on
the bucket. Used when `provider` is `gcs`.
example: tavus-recording-writer@my-gcp-project.iam.gserviceaccount.com
storage_account:
type: string
description: Azure storage account name. Used when `provider` is `azure_blob`.
example: myrecordingsaccount
container:
type: string
description: >-
Container within the storage account. Used when `provider` is
`azure_blob`.
example: conversation-recordings
tenant_id:
type: string
description: Azure AD tenant UUID. Used when `provider` is `azure_blob`.
example: 11111111-2222-3333-4444-555555555555
client_id:
type: string
description: App Registration client UUID. Used when `provider` is `azure_blob`.
example: 66666666-7777-8888-9999-000000000000
securitySchemes:
apiKey:
type: apiKey
in: header
name: x-api-key
````