TAtavus
Conversations

POST /v2/conversations

Changed on

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.

Request

  • Base URL
    https://tavusapi.com
  • URL
    https://tavusapi.com/v2/conversations
  • Auth
    API key in header x-api-key

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 joins the conversation. When set, this is spoken verbatim and always wins over generated greetings.

dynamic_greetingboolean

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.

memory_storesstring[]

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

participant_tagsstring[]

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.

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

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

policy'eu'

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.

objectives_idstring

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 request

{
  "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.",
  "custom_greeting": "Hey there!",
  "memory_stores": [
    "user_12345-p123456789ab"
  ],
  "participant_tags": [
    "user_12345"
  ],
  "document_ids": [
    "doc_1234567890"
  ],
  "document_retrieval_strategy": "balanced",
  "document_tags": [
    "sales",
    "marketing"
  ],
  "meeting_url": "https://meet.google.com/xgq-epxn-ccp",
  "max_participants": 2,
  "policy": "eu",
  "objectives_id": "o12345",
  "properties": {
    "max_call_duration": 3600,
    "participant_left_timeout": 60,
    "participant_absent_timeout": 300,
    "enable_recording": true,
    "auto_start_recording": true,
    "enable_closed_captions": true,
    "apply_greenscreen": true,
    "language": "multilingual",
    "languages": [
      "en",
      "es",
      "pt"
    ],
    "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",
      "key_template": "recordings/{conversation_id}/{epoch_ms}.mp4",
      "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..."
}

Changes

  • 932c24e63be2Revision changes
    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the new optional request property /

    • info

      added the new optional request property /

    • info

      added the new optional request property //

    • info

      request property deprecated

    • info

      request property / deprecated

    • info

      request property // deprecated