Skip to main content
POST
/
v2
/
conversations
curl --request POST \
  --url https://tavusapi.com/v2/conversations \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "replica_id": "rfe12d8b9597",
  "persona_id": "pdced222244b"
}
'
{
  "conversation_id": "c123456",
  "conversation_name": "A Meeting with Hassaan",
  "conversation_url": "https://tavus.daily.co/c123456",
  "status": "active",
  "callback_url": "sample.com/callback",
  "created_at": "<string>"
}
Required parameters vary depending on the use case:Full Pipeline Conversation:
  • persona_id
  • replica_id
Audio-Only Conversation:
  • persona_id
  • replica_id
  • audio_only
  • replica_id is required if the persona does not have a default replica.
  • replica_id is optional if the persona does have a default replica.
  • If both a default replica and replica_id are provided, the supplied replica_id will override the default.

Authorizations

​
x-api-key
string
header
required

Body

application/json
​
replica_id
string

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:

"rfe12d8b9597"

​
persona_id
string

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:

"p9a95912"

​
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

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

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

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

Example:

"Hey there!"

​
memory_stores
string[]

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

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

Example:
["doc_1234567890"]
​
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 replica 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:
["sales", "marketing"]
​
test_mode
boolean

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

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