curl --request POST \
--url https://tavusapi.com/v2/conversations \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"face_id": "r4b03c679d42",
"pal_id": "p22f53b7b4b9"
}
'{
"conversation_id": "c123456",
"conversation_name": "A Meeting with Hassaan",
"room_url": "https://maker.tavus.io/room/c123456",
"conversation_url": "https://tavus.daily.co/c123456",
"status": "active",
"callback_url": "sample.com/callback",
"created_at": "<string>",
"meeting_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}Create conversation
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.
curl --request POST \
--url https://tavusapi.com/v2/conversations \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"face_id": "r4b03c679d42",
"pal_id": "p22f53b7b4b9"
}
'{
"conversation_id": "c123456",
"conversation_name": "A Meeting with Hassaan",
"room_url": "https://maker.tavus.io/room/c123456",
"conversation_url": "https://tavus.daily.co/c123456",
"status": "active",
"callback_url": "sample.com/callback",
"created_at": "<string>",
"meeting_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}https://docs.tavus.io/openapi.yaml for the full HTTP API contract.Body
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 theface_idfield. - If your PAL already has a valid
face_idand you provide one in the request, theface_idprovided in the request will be used instead of the one defined in your PAL.
"p22f53b7b4b9"
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.
"https://yourwebsite.com/webhook"
Optional shared secret for signing this conversation’s callbacks. Without an explicit callback URL, the PAL’s default URL and secret are inherited; this field can override just the secret. An explicit callback_url or webhook_url overrides the PAL’s URL and requires its own secret to enable signing. Limited to 256 UTF-8 bytes. See Signed callbacks.
1 - 256Optional 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.
false
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.
11["user_12345"]
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.
["doc_1234567890"]
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.
["sales", "marketing"]
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.
false
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.
"https://meet.google.com/xgq-epxn-ccp"
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: autobehaves likelimited(Raven-1 does not attach biometric-derived emotion).disclosure_type: autodelivers the spoken and on-screen AI disclosure for that conversation.- Explicit settings (
full,limited,always,off) are honored as-is and are not overridden bypolicy.
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.
eu "eu"
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.
"o12345"
Response
A link to the Tavus-hosted room page, which supports all Tavus conversation features. For private rooms, append the meeting_token as ?t=TOKEN. See Room URL vs conversation URL.
"https://maker.tavus.io/room/c123456"
The call URL. Use it to join the call programmatically with an SDK. To test or share the call in a browser, use room_url. See Room URL vs conversation URL.
"https://tavus.daily.co/c123456"

