API Reference

The Daily Conversation Audio Recordings API allows authorized clients to retrieve daily conversation audio recordings in ZIP format. This is essential for meeting legal compliance requirements.

1. Creating an Application

In order to utilize the The Daily Conversation Audio Recordings API, an application with dataservice_external scope must be created. This application enables secure authentication and authorization of client requests.

📄 For setup instructions, please refer to the official guide.

2. Getting an Access Token

To authenticate API requests, an access token must be obtained using the credentials of your registered application.

📄 For getting an access token, please refer to the official guide.

3. The Daily Conversation Audio Recordings API

Endpoint:

• Method: GET
• URL: {{BaseUrl}}/api/external/conversations/daily-audio-recordings/{{utcDay}}

Path Parameters

Responses

3.1. Example Request & Response

Here's an example of a request:

curl --location '{{BaseUrl}}/api/external/conversations/daily-audio-recordings/2025-12-12' \
--header 'Authorization: Bearer {{Token}}'

Here's an example of a response:

{
  "date": "2025-12-12",
  "totalSessions": 287,
  "totalFiles": 1543,
  "totalSizeBytes": 1567890432,
  "generatedAt": "2025-12-13T02:15:32Z",
  "retentionDays": 3,
  "expiresAt": "2024-12-16T02:15:32Z",
  "links": [
    {
      "hour": "00",
      "url": "https://minio-domain.com/presigned-url?token=...",
      "sessionCount": 12,
      "fileCount": 67,
      "sizeBytes": 15360000,
      "status": "available"
    },
    {
      "hour": "01",
      "url": null,
      "sessionCount": 0,
      "fileCount": 0,
      "sizeBytes": 0,
      "status": "no_data"
    },
    {
      "hour": "02",
      "url": "https://minio-domain.com/presigned-url?token=...",
      "sessionCount": 8,
      "fileCount": 42,
      "sizeBytes": 9870000,
      "status": "available"
    },
    {
      "hour": "23",
      "url": "https://minio-domain.com/presigned-url?token=...",
      "sessionCount": 9,
      "fileCount": 45,
      "sizeBytes": 12300000,
      "status": "available"
    }
  ]
}

3.2. Metadata Field of the Response

Each ZIP file also includes a metadata.json file with detailed information:

{
  "generatedAt": "2025-12-13T02:15:32Z",
  "utcDay": "2025-12-12",
  "hour": "14",
  "totalSessions": 12,
  "sessions": [
    {
      "externalConversationId": "conv-123",
      "sessionId": "session-456",
      "files": [
        {
          "fileName": "message_789_agent_tts.opus",
          "originalPath": "knovvu-va/tenant/project/conversations/...",
          "messageId": 789,
          "type": "agent_tts",
          "timestamp": "2025-12-12T14:23:45Z",
          "originalSizeBytes": 45000
        }
      ]
    }
  ]
}

3.2. Error Responses