Sign in

v1

latestOpenAPI 3.0.32026-07-267015229.9 KB
Conversations

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.

post/v2/conversations

Request body

face_idstring

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.

pal_idstring

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

Specifies whether the interaction should be voice-only. This field is required if you want to create an audio-only conversation.

callback_urlstring

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

conversation_namestring

A name for the conversation.

conversational_contextstring

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

custom_greetingstring

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

memory_storesstring[]

The memory stores to use for the conversation. The PAL 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.

document_idsstring[]

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.

document_retrieval_strategystring

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

document_tagsstring[]

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.

test_modeboolean

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.

meeting_urlstring

A Google Meet URL for the PAL to join instead of a Tavus-hosted Daily room (for example https://meet.google.com/abc-defg-hij).

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.

require_authboolean

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

max_participantsinteger

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

Example request

{
  "face_id": "r90bbd427f71",
  "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.",
  "custom_greeting": "Hey there!",
  "memory_stores": [
    "anna"
  ],
  "document_ids": [
    "doc_1234567890"
  ],
  "document_retrieval_strategy": "balanced",
  "document_tags": [
    "sales",
    "marketing"
  ],
  "meeting_url": "https://meet.google.com/xgq-epxn-ccp",
  "max_participants": 2,
  "properties": {
    "max_call_duration": 3600,
    "participant_left_timeout": 60,
    "participant_absent_timeout": 300,
    "enable_recording": true,
    "enable_closed_captions": true,
    "apply_greenscreen": true,
    "language": "multilingual",
    "recording_s3_bucket_name": "conversation-recordings",
    "recording_s3_bucket_region": "us-east-1",
    "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",
      "project_id": "my-gcp-project",
      "workload_identity_provider": "projects/123456/locations/global/workloadIdentityPools/tavus-pool/providers/tavus-cf-worker",
      "service_account_email": "tavus-recording-writer@my-gcp-project.iam.gserviceaccount.com",
      "storage_account": "myrecordingsaccount",
      "container": "conversation-recordings",
      "tenant_id": "11111111-2222-3333-4444-555555555555",
      "client_id": "66666666-7777-8888-9999-000000000000"
    }
  }
}

Response

conversation_idstring

A unique identifier for the conversation.

conversation_namestring

The name of the conversation.

conversation_urlstring

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

statusstring

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

callback_urlstring

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

created_atstring

The date and time the conversation was created.

meeting_tokenstring

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 response

{
  "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>",
  "meeting_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}