​
Prerequisite

Ensure that you have the following:

  • An S3 bucket with versioning enabled.

​
Enable Conversation Recording

1

Step 1: Set up IAM Policy and Role

  1. Create an IAM Policy with the following JSON definition:
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "VisualEditor0",
      "Effect": "Allow",
      "Action": [
        "s3:PutObject",
        "s3:GetObject",
        "s3:ListBucketMultipartUploads",
        "s3:AbortMultipartUpload",
        "s3:ListBucketVersions",
        "s3:ListBucket",
        "s3:GetObjectVersion",
        "s3:ListMultipartUploadParts"
      ],
      "Resource": [
        "arn:aws:s3:::your-bucket-name",
        "arn:aws:s3:::your-bucket-name/*"
      ]
    }
  ]
}

Note: Replace your-bucket-name with your actual bucket name.

  1. Create an IAM role with the following value:
    • Select “Another AWS account” and enter this account ID: 291871421005.
    • Enable “Require external ID”, and use: tavus.
    • “Max session duration” to 12 hours.

Note: Note down your ARN (e.g., arn:aws:iam::123456789012:role/CVIRecordingRole).

2

Step 2: 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.

3

Step 3: Create a Conversation with Recording Enabled

Use the following request body example:

Remember to change the following values:

  • <api_key>: Your actual API key.
  • aws_assume_role_arn: Your AWS ARN.
  • recording_s3_bucket_region: Your S3 region.
  • recording_s3_bucket_name: Your S3 bucket name.
cURL
curl --request POST \
  --url https://tavusapi.com/v2/conversations \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api_key>' \
  --data '{
  "properties": {
    "enable_recording": true,
    "aws_assume_role_arn": "<your_aws_arn>",
    "recording_s3_bucket_region": "<your_s3_bucket_region>",
    "recording_s3_bucket_name": "<your_s3_bucket_name>"
  },
  "replica_id": "ra066ab28864"
}'

Note: enable_recording allows recording to be possible, but it doesn’t start recording automatically. To begin and end recordings, users must do it manually or trigger it through frontend code.

4

Step 4: Join the Conversation

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


{
  "conversation_id": "c93a7ead335b",
  "conversation_name": "New Conversation 1747654283442",
  "conversation_url": "<conversation_link>",
  "status": "active",
  "callback_url": "",
  "created_at": "2025-05-16T02:09:22.675928Z"
}

Note: You can access the recording file in your S3 bucket.