> ## 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 face, powered by a PAL 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: Faces
- name: Voices
- name: Conversations
- name: Deployments
- name: PALs
- name: Tools
- name: PAL Tools
- name: Connectors
- name: Pronunciation Dictionaries
- name: Replacements
- name: Transcriptions
- name: Documents
- name: Memory Stores
paths:
/v2/conversations:
post:
tags:
- Conversations
description: >
This endpoint starts a real-time video conversation with your AI face,
powered by a PAL that allows it to see, hear, and respond like a human.
operationId: createConversation
requestBody:
content:
application/json:
schema:
type: object
properties:
face_id:
type: string
description: >-
The unique identifier for the face the PAL will render in
the conversation. **Each request must have a valid `face_id`
value that's either directly passed in or as part of a
PAL**.
example: rc9cff32ceba
pal_id:
type: string
description: >
The unique identifier for the PAL that will use the
specified face in the conversation.
- **If your PAL does not have a valid `face_id`, you must
define the `face_id` field.**
- **If your PAL already has a valid `face_id` and you
provide one in the request, the `face_id` provided in the
request will be used instead of the one defined in your
PAL**.
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 PAL, 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 PAL will give once a
participant joins the conversation. When set, this is spoken
verbatim and always wins over generated greetings.
example: Hey there!
dynamic_greeting:
type: boolean
description: >
Optional override of the PAL's `dynamic_greeting`. Omit to
inherit the PAL. Greeting priority is a written
`custom_greeting`, then this field set to true (generates
even if the PAL has a written `greeting`), then the PAL's
`greeting`, then the PAL's `dynamic_greeting`. Generated
from the PAL and any `conversational_context`, in the first
tag of this conversation's `properties.languages`, otherwise
the PAL's `languages`.
example: false
memory_stores:
type: array
deprecated: true
items:
type: string
description: >-
Legacy tag-based memory namespaces. Existing integrations
remain supported. New integrations should use
`participant_tags`; do not send both fields in one request.
example:
- user_12345-p123456789ab
participant_tags:
type: array
maxItems: 1
description: >-
Optional participant tags for memory. Provide zero or one
stable, non-empty tag. With one tag, Tavus finds or creates
the PAL-specific memory store server-side. Reuse the same
tag with the same PAL to continue memory across
conversations. Omit the field or send an empty array for a
stateless conversation. Sending more than one tag returns a
400 error because multi-participant memory is not supported
yet. Cannot be combined with `memory_stores`.
items:
type: string
minLength: 1
example:
- user_12345
document_ids:
type: array
items:
type: string
description: >-
The ids of the documents that the PAL 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 PAL 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 PAL 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
meeting_url:
type: string
description: >
A Google Meet, Zoom, or Microsoft Teams URL for the PAL to
join instead of a Tavus-hosted Daily room (for example
`https://meet.google.com/abc-defg-hij`,
`https://us02web.zoom.us/j/123456789`,
`https://teams.microsoft.com/l/meetup-join/...`).
When set, the PAL joins that meeting shortly after the
conversation is created. Requires the PAL to have a
conferencing layer with `username` configured. See [Google
Meet / Zoom /
Teams](/sections/conversational-video-interface/pal/meetings#join-a-meeting-via-api).
example: https://meet.google.com/xgq-epxn-ccp
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 PAL counts as one
participant).
example: 2
policy:
type: string
description: >
Regional policy applied to this conversation. Set to `eu`
when you want PAL fields left on `auto` to resolve as
described in the [EU AI
Act](/sections/onboarding-guide/eu-ai-act) product guide:
- `emotion_recognition: auto` behaves like `limited`
(Raven-1 does not attach biometric-derived emotion).
- `disclosure_type: auto` delivers the spoken and on-screen
AI disclosure for that conversation.
- Explicit settings (`full`, `limited`, `always`, `off`) are
honored as-is and are not overridden by `policy`.
Leave unset when you do not want that auto resolution.
Choosing the correct value per participant is your
responsibility — on the create-conversation API Tavus does
not geolocate the caller.
enum:
- eu
example: eu
objectives_id:
type: string
description: >-
The unique identifier of an objectives set to use for this
conversation. Overrides any `objectives_id` set on the PAL
for this call only, without modifying the PAL. Create
objectives with [Create
Objectives](/api-reference/objectives/create-objectives).
See [Overriding objectives per
conversation](/sections/conversational-video-interface/pal/objectives#overriding-objectives-per-conversation).
example: o12345
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
auto_start_recording:
type: boolean
description: >-
If true, Tavus starts the recording about a second after
the pal joins, so you do not need to call
`startRecording()` from your client. Requires
`recording_storage`. Only supported on Tavus-hosted
rooms - not with `daily_room`, `meeting_url`, or
LiveKit. Defaults to false. See [Start recording
automatically](/sections/conversational-video-interface/quickstart/conversation-recordings#start-recording-automatically).
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. Background
customization not compatible with Phoenix-4.5 faces.
This property resolves to `false` when used with
Phoenix-4.5 face.
example: true
language:
type: string
deprecated: true
description: >
**Deprecated.** Use `languages` instead, on this object
or on the PAL.
`language` takes one FULL language name, not a code, or
`multilingual` for automatic detection. It cannot
express which languages a conversation should be
prepared for, so it cannot restrict recognition, hold
the PAL's replies to a set, or select a per-language
voice. `languages` does all three, and covers the
single-language case: `languages: ["es"]` is equivalent
to `language: "spanish"`.
Existing integrations keep working unchanged. Where both
are sent, `languages` wins and rewrites this field. See
[Language
support](/sections/conversational-video-interface/language-support).
example: multilingual
languages:
type: array
description: >
The languages this conversation is expected to run in,
from the [spoken
languages](/sections/conversational-video-interface/language-support#spoken-languages)
Tavus supports. More precise than `language:
multilingual`, Tavus restricts speech recognition to
this set and holds the PAL's replies to it, instead of
detecting from every language.
Setting `languages` decides `language` for you: several
entries make the conversation `multilingual`, a single
entry makes it that language. The first entry is the
language the conversation opens in.
Overrides a `languages` set on the PAL; the two are not
merged. A language the conversation cannot actually be
held in, one the resolved TTS engine and model cannot
speak, is rejected rather than ignored. See [Language
support](/sections/conversational-video-interface/language-support#setting-languages).
maxItems: 42
items:
type: string
maxLength: 16
example:
- en
- es
- pt
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:
face_id: rc9cff32ceba
pal_id: pcb7a34da5fe
Full Customizations:
value:
face_id: rc9cff32ceba
pal_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:
face_id: rc9cff32ceba
pal_id: pcb7a34da5fe
audio_only: true
Private Room:
value:
face_id: rc9cff32ceba
pal_id: pcb7a34da5fe
require_auth: true
Google Meet (direct invite):
value:
face_id: rc9cff32ceba
pal_id: pcb7a34da5fe
meeting_url: https://meet.google.com/xgq-epxn-ccp
Microsoft Teams (direct invite):
value:
face_id: rc9cff32ceba
pal_id: pcb7a34da5fe
meeting_url: https://teams.microsoft.com/l/meetup-join/19%3ameeting_abc
EU AI Act compliance (policy = eu):
value:
face_id: rc9cff32ceba
pal_id: pcb7a34da5fe
policy: eu
Recording Storage - Amazon S3:
value:
face_id: rc9cff32ceba
pal_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
key_template: recordings/{conversation_id}/{epoch_ms}.mp4
Recording Storage - Google Cloud Storage:
value:
face_id: rc9cff32ceba
pal_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:
face_id: rc9cff32ceba
pal_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. The response body contains either an `error` or
`message` field depending on the error type.
content:
application/json:
schema:
type: object
properties:
error:
type: string
description: Present for request validation errors.
message:
type: string
description: Present for limit and account errors.
examples:
bad_request:
summary: Missing required field
value:
error: >-
Bad Request. {'_schema': ['Either face_id or a pal_id with
a default face specified must be present.']}
concurrent_limit:
summary: Concurrent conversation limit reached
value:
message: User has reached maximum concurrent conversations
'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: >
Not used for S3 recordings: the recording service always presents
the ExternalId `tavus`
when assuming your role. To isolate your account, set `key_template`
and scope your role's
permissions policy to `tavus//*` instead. See
[Conversation
Recordings](/sections/conversational-video-interface/quickstart/conversation-recordings#amazon-s3).
deprecated: true
key_template:
type: string
description: >
Shapes the destination object key. Tokens: `{conversation_id}` and
`{epoch_ms}`. Allowed literal
characters `[0-9A-Za-z./_-]`, max 512 characters, no leading slash,
no `//`, no `..`.
On `s3`, setting this switches recordings to the account-scoped
layout: Tavus prepends
`tavus//` to the template, so a policy restricted
to that prefix admits only
your account's recordings. `{epoch_ms}` is required on `s3`. Without
`key_template`, S3
recordings use the default key `tavus//`.
On `gcs` and `azure_blob` the template is used as the full object
key.
example: recordings/{conversation_id}/{epoch_ms}.mp4
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
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.