1. Create an S3 Bucket

Create an S3 bucket and name it according to your own practices. If you’re new to S3 buckets, follow this guide.

The bucket can be in any AWS region.

Versioning must be enabled. Please be sure to select “Enable” under “Bucket Versioning” when creating your S3 bucket for recording storage.

Make note of the region and bucket name you chose. You will need them going forward.

2. Create an IAM Policy

In AWS, navigate to the IAM dashboard. Click on “Policies” in the left-hand menu. Next, click “Create” to paste the following policy into the JSON definition:

Be sure to first replace your-bucket-name in the “Resource” property with the name of your designated S3 bucket.
{
  "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/*"
      ]
    }
  ]
}

3. Create an IAM Role

You can find role creation in the same IAM service dashboard used to create the policy. Click on “Roles” in the left-hand menu, then click “Create Role”. Follow these steps to create your role:

  1. For “Trusted Entity Type”, select “AWS Account”
  2. Under “An AWS Account”, select “Another AWS account”
  3. Enter 291871421005 as the Account ID (this is Daily’s account)
  4. Use the word tavus as the “Require External ID” value.

  1. Click “Next” and attach the policy you just created to the role:

  1. Click “Next” again, give your role a name, and click “Create role”.

  2. Once the role is created, find it in your IAM Roles list and click “Edit”. Set the “Maximum session duration” to “12 hours”:

  1. Finally, copy the ARN (Amazon Resource Name) of the role you just created on the role page in IAM:

4. Create a Conversation with Recording Enabled

You can now make an API call using the create-conversation endpoint. Here are the pertinent properties related to recording:

  • enable_recording: Set this to true. This will allow the user to start the recording but will not automatically start it. If you want automatic recording, use frontend code.
  • aws_assume_role_arn: Copy this from the IAM role page. Example: arn:aws:iam::123456789012:role/YourRoleName
  • recording_s3_bucket_region: The region you selected when creating the bucket. Example: us-east-1
  • recording_s3_bucket_name: The bucket name you entered when creating the bucket. Example: recordings-cvi-daily

Here is a sample CURL request that properly specifies the recording properties:

curl --request POST \
  --url https://tavusapi.com/v2/conversations \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: f4k3d4t4f4k3d4t4f4k3d4t4f4k3d4t4' \
  --data '{
  "properties": {
    "enable_recording": true,
    "aws_assume_role_arn": "arn:aws:iam::123456789012:role/YourRoleName",
    "recording_s3_bucket_region": "us-east-1",
    "recording_s3_bucket_name": "recordings-cvi-daily"
  },
  "replica_id": "r1e69411f2"
}'
This API call uploads a test file named daily-co-test-upload.txt to your bucket to verify permissions. If the recording itself is never started (manually by a user or via frontend code), this will be the only file written to the bucket.