---
title: "POST /v2/conversations"
method: POST
path: "/v2/conversations"
tags: ["Conversations"]
---

# POST /v2/conversations

`POST /v2/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.

## Request body

- object
  - `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**.
  - `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**.
  - `audio_only` boolean — Specifies whether the interaction should be voice-only. **This field is required if you want to create an audio-only conversation**.
  - `callback_url` string — A url that will receive webhooks with updates regarding the conversation state.
  - `conversation_name` string — A name for the conversation.
  - `conversational_context` string — Optional context that will be appended to any context provided in the PAL, if one is provided.
  - `custom_greeting` string — An optional custom greeting that the PAL will give once a participant joines the conversation.
  - `memory_stores` string[] — 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_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](/api-reference/documents/get-document) and the [Create Document](/api-reference/documents/create-document) endpoints.
  - `document_retrieval_strategy` string — The strategy to use for document retrieval. Possible values: `speed`, `quality`, `balanced`. Default is `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](/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.
  - `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.
  - `meeting_url` string — 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](/sections/conversational-video-interface/pal/meetings#join-a-google-meet-via-api).
  - `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.'
  - `max_participants` integer — Maximum number of participants allowed in the conversation room. Must be at least 2 (the PAL counts as one participant).
  - `properties` object — Optional properties that can be used to customize the conversation.
    - `max_call_duration` integer — 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.
    - `participant_left_timeout` integer — The duration in seconds after which the call will be automatically shut down once the last participant leaves.
    - `participant_absent_timeout` integer — 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).
    - `enable_recording` boolean — 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).
    - `enable_closed_captions` boolean — 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.
    - `apply_greenscreen` boolean — 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.
    - `language` string — The language of the conversation. Please provide the FULL language name, not the two letter code, or specify `multilingual` for automatic language detection. When set to `multilingual`, CVI will use STT language detection to identify the user's spoken language and respond accordingly. If you are using your own TTS voice, please ensure it supports the language you provide. If you are using a stock face or default PAL, please note that only Elevenlabs and Cartesia supported languages are available. You can find a full list of supported languages for Cartesia [here](https://docs.cartesia.ai/2024-11-13/build-with-cartesia/models#language-support), and for ElevenLabs [here](https://elevenlabs.io/languages).
    - `recording_s3_bucket_name` string — **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.
    - `recording_s3_bucket_region` string — **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.
    - `aws_assume_role_arn` string — **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.
    - `recording_storage` RecordingStorageConfig — 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.
      - `provider` 's3' | 'gcs' | 'azure_blob', required — Storage provider discriminator.
      - `bucket_name` string — Bucket name. Used when `provider` is `s3` or `gcs`.
      - `bucket_region` string — 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`.
      - `assume_role_arn` string — IAM role ARN that Tavus assumes to write to your bucket. Used when `provider` is `s3`.
      - `external_id` string — Optional `ExternalId` value to include in the AssumeRole call. Used when `provider` is `s3`.
      - `project_id` string — GCP project ID containing the bucket. Used when `provider` is `gcs`.
      - `workload_identity_provider` string — Resource name of your Workload Identity Pool Provider - without the `//iam.googleapis.com/` prefix (Tavus prepends it). Used when `provider` is `gcs`.
      - `service_account_email` string — Email of the service account that has `storage.objects.create` on the bucket. Used when `provider` is `gcs`.
      - `storage_account` string — Azure storage account name. Used when `provider` is `azure_blob`.
      - `container` string — Container within the storage account. Used when `provider` is `azure_blob`.
      - `tenant_id` string — Azure AD tenant UUID. Used when `provider` is `azure_blob`.
      - `client_id` string — App Registration client UUID. Used when `provider` is `azure_blob`.

## Response `200`

- object
  - `conversation_id` string — A unique identifier for the conversation.
  - `conversation_name` string — The name of the conversation.
  - `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.
  - `status` string — The status of the conversation. Possible values: `active`, `ended`.
  - `callback_url` string — The url that will receive webhooks with updates of the conversation state.
  - `created_at` string — The date and time the conversation was created.
  - `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.

## Other responses

- `400` — Bad Request. The response body contains either an `error` or `message` field depending on the error type.
- `401` — UNAUTHORIZED

---

[API](https://skmtc.dev/tavus/apis/tavus-developer-api-collection.md) · [All operations](https://skmtc.dev/tavus/apis/tavus-developer-api-collection/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/tavus/tavus-developer-api-collection/revisions/c878e2f6508d/schema)