​
Create a Conversation with Custom Duration and Timeout

1

Step 1: Get an API Key

  1. Go to the Tavus platform and select API Key from the sidebar menu.
  2. Click Create New Key to begin generating your API key.
  3. Enter a name for the key and (optional) specify allowed IP addresses, then click Create API Key.
  4. Copy your newly created API key and store it securely.

We cannot recover your API Key if you lose it.

2

Step 2: Create Your Conversation

In this example, we will use stock replica ID rfe12d8b9597 (Nathan) and stock persona ID pdced222244b (Sales Coach).

Use the following request body example:

cURL
curl --request POST \
  --url https://tavusapi.com/v2/conversations \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api_key>' \
  --data '{
  "persona_id": "pdced222244b",
  "replica_id": "rfe12d8b9597",
  "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.",
  "properties": {
    "max_call_duration": 1800,
    "participant_left_timeout": 60,
    "participant_absent_timeout": 120
   }
}'

Note: Replace <api_key> with your actual API key.

The request example above includes the following customizations:

ParameterDescription
max_call_durationsSets the maximum call length in seconds. Maximum: 3600 seconds.
participant_left_timeoutTime (in seconds) to wait before ending the call after the last participant leaves. Default: 0.
participant_absent_timeoutTime (in seconds) to end the call if no one joins after it’s created. Default: 300.
3

Step 3: Join the Conversation

To join the conversation, click the link in the conversation_url field from the response:

{
  "conversation_id": "ca4301628cb9",
  "conversation_name": "Improve Sales Technique",
  "conversation_url": "<conversation_link>",
  "status": "active",
  "callback_url": "https://yourwebsite.com/webhook",
  "created_at": "2025-05-13T06:42:58.291561Z"
}

Based on the call time settings above:

  • The conversation will automatically end after 1800 seconds (30 minutes), regardless of activity.
  • If the participant leaves the conversation, it will end 60 seconds after they disconnect.
  • If the participant is present but inactive (e.g., not speaking or engaging), the conversation ends after 120 seconds of inactivity.