Skip to main content

​
Uploading Conversations

This guide describes how to programmatically upload recorded conversations so that Rulebase can ingest and review them.

​
Upload Methods

Rulebase supports two methods for uploading conversations:
  1. Presigned URL workflow (recommended for large files) - Two-step process using presigned URLs
  2. Direct upload (simpler for smaller files) - Single request with multipart form data

​
Method 1: Presigned URL Workflow

The presigned URL workflow consists of two HTTP requests and is recommended for larger files:
  1. Generate a presigned upload URL (HTTP POST).
  2. Upload the ZIP archive to the returned URL (HTTP PUT).

​
1 · Generate a presigned URL

Send a POST /conversations/upload/presign request, passing the filename and source that describe the ZIP archive you intend to upload. 
curl -X POST https://api.rulebase.co/conversations/upload/presign \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "upload": {
      "filename": "your-filename.zip",
      "source": "[source]"
    }
  }'
Successful responses contain the upload id and a time-limited url to which you must upload the archive: 
{
  "upload": {
    "id": "unique_upload_id",
    "url": "https://presigned-url-to-upload"
  }
}
For the full REST spec see Generate a presigned URL for conversation upload.

​
2 · Upload the archive

Upload the ZIP archive with an HTTP PUT request to the url from step 1. The request must use Content-Type: application/octet-stream. 
curl -X PUT "https://presigned-url-to-upload" \
  -H "Content-Type: application/octet-stream" \
  --data-binary "@your-filename.zip"
⚠️ The presigned URL expires 30 minutes after it is issued.

​
Method 2: Direct Upload

For simpler integration and smaller files, you can upload conversations directly using a single POST request with multipart form data.

​
Upload a conversation directly

Send a POST /conversations/upload request with the source, metadata, and call recording as multipart form data. 
curl -X POST https://api.rulebase.co/conversations/upload \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "upload[source]=xcally" \
  -F "upload[metadata][unique_id]=abc123" \
  -F "upload[metadata][type]=inbound" \
  -F "upload[metadata][caller]=+2348012345678" \
  -F "upload[metadata][called]=+2349098765432" \
  -F "upload[metadata][recorded_at]=2025-07-02T12:00:00Z" \
  -F "upload[file][email protected]"
Successful responses contain the upload id and processing status: 
{
  "data": {
    "id": "unique_upload_id",
    "status": "processing",
    "created_at": "2025-07-02T12:00:00Z",
    "updated_at": "2025-07-02T12:00:00Z"
  }
}

​
Direct upload requirements

  • Content-Type: multipart/form-data
  • Maximum file size: 100MB
  • Supported audio formats: .wav, .mp3, .m4a
  • Metadata format: Individual form fields for each metadata attribute

​
Supported sources for direct upload

Source keyDescription
xcallyXCALLY voice recordings
⚠️ Direct upload currently supports XCALLY sources only. For other sources, use the presigned URL workflow.

​
Supported sources

The source attribute defines how Rulebase should interpret the contents of the archive. All sources follow the same two-step upload flow shown above, but each imposes its own file-naming and payload requirements.
Source keyDescription
outreach_kaiaOutreach Kaia conversation exports
xcallyXCALLY voice recordings
Detailed requirements for each source are provided below.

​
Outreach Kaia (outreach_kaia)

​
1 · Presign request example

curl -X POST https://api.rulebase.co/conversations/upload/presign \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "upload": {
      "filename": "KAIA-2024-03-20T10:00:00Z+instance123.zip",
      "source": "outreach_kaia"
    }
  }'

​
2 · ZIP file requirements

  • Filename convention: KAIA-<RFC3339 DateTime>+<InstanceID>.zip
  • Contents:
    FileNaming convention
    Transcript (.txt)KAIA-<DateTime>+<InstanceID>.txt
    Media (.mp4)KAIA-<DateTime>+<InstanceID>.mp4
    Metadata (.json)KAIA-<DateTime>+<InstanceID>.json

​
3 · Example ZIP structure

KAIA-2024-03-20T10:00:00Z+instance123.mp4
KAIA-2024-03-20T10:00:00Z+instance123.txt
KAIA-2024-03-20T10:00:00Z+instance123.json
For a complete description of the export schema, refer to the official Outreach Kaia export documentation.

​
XCALLY (xcally)

​
1 · Presign request example

curl -X POST https://api.rulebase.co/conversations/upload/presign \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "upload": {
      "filename": "xcally-2025-07-02-call-abc123.zip",
      "source": "xcally"
    }
  }'

​
2 · ZIP file requirements

  • Contents:
    Required fileNotes
    Audio (.wav or .mp3)Recording of the call
    Metadata (.json)Call attributes (see below)
  • Filename convention: none—any archive name is accepted as long as exactly one audio file and one JSON file are present.

​
3 · Example ZIP structure

call-abc123.wav
call-abc123.json

​
4 · Metadata JSON schema (example)

{
  "unique_id": "abc123",
  "type": "inbound",
  "caller": "+2348012345678",
  "called": "+2349098765432",
  "connected": "ext-1001",
  "queue": "customer_support",
  "disposition": "resolved",
  "recorded_at": "2025-07-02T12:00:00Z"
}
FieldDescription
unique_idUnique identifier of the call
typeCall type (inbound, outbound, internal, or dialer)
callerCaller phone number
calledCallee phone number
connectedExtension/agent that handled the call
queueQueue name
dispositionCall disposition label
recorded_atISO 8601 timestamp when the call was recorded
For additional reference see the XCALLY voice recordings documentation.