Skip to main content
POST
For AI agents, use https://docs.tavus.io/openapi.yaml for the full HTTP API contract.
Set callback_url on the PAL as the default for conversation webhooks. A non-empty callback_url on Create Conversation overrides that default for that conversation only, without changing the PAL. Omit the conversation field or pass an empty string to inherit the default. See Conversation callbacks.

Authorizations

​
x-api-key
string
header
required

Body

application/json
​
face_id
string

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
string

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
boolean

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
string

URL that receives webhooks about the conversation state. A non-empty value overrides the PAL’s callback_url for this conversation only, without modifying the PAL. Omit this field or pass an empty string to inherit the PAL’s callback URL. If neither level has a URL, no conversation callbacks are sent. See Conversation callbacks.

Example:

"https://yourwebsite.com/webhook"

​
conversation_name
string

A name for the conversation.

Example:

"Improve Sales Technique"

​
conversational_context
string

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
string

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
boolean

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
string[]
deprecated

Legacy tag-based memory namespaces. Existing integrations remain supported. New integrations should use participant_tags; do not send both fields in one request.

Example:
​
participant_tags
string[]

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.

Maximum array length: 1
Minimum string length: 1
Example:
​
document_ids
string[]

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 and the Create Document endpoints.

Example:
​
document_retrieval_strategy
string

The strategy to use for document retrieval. Possible values: speed, quality, balanced. Default is balanced.

Example:

"balanced"

​
document_tags
string[]

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 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:
​
test_mode
boolean

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
string

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.

Example:

"https://meet.google.com/xgq-epxn-ccp"

​
require_auth
boolean

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
integer

Maximum number of participants allowed in the conversation room. Must be at least 2 (the PAL counts as one participant).

Required range: x >= 2
Example:

2

​
policy
enum<string>

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 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.

Available options:
eu
Example:

"eu"

​
objectives_id
string

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. See Overriding objectives per conversation.

Example:

"o12345"

​
properties
object

Optional properties that can be used to customize the conversation.

Response

​
conversation_id
string

A unique identifier for the conversation.

Example:

"c123456"

​
conversation_name
string

The name of the conversation.

Example:

"A Meeting with Hassaan"

​
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.

Example:

"https://tavus.daily.co/c123456"

​
status
string

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

Example:

"active"

​
callback_url
string

The url that will receive webhooks with updates of the conversation state.

Example:

"sample.com/callback"

​
created_at
string

The date and time the conversation was created.

Example:

"<string>"

​
meeting_token
string

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..."