Import a Call

Import calls from external systems with transcripts, audio URLs, or S3 storage. Optionally trigger analysis and scorecard evaluation.

Import Modes

Choose one of four import modes based on your data source:

Mode	Required Fields	Description
`transcriptOnly`	`transcript`	Import with existing transcript (fastest, skips transcription)
`audioUrl`	`audioUrl`	Import from HTTP audio URL (transcribed via Deepgram)
`audioId`	`audioId`	Import from previously uploaded audio
`s3`	`bucket`, `key`, credentials	Import from S3-compatible storage

Request

curl -X POST "https://api.chanl.ai/api/v1/calls/import" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "transcript": "Agent: Hi, how can I help you today?\nCustomer: I need to check my order status.\nAgent: Sure, let me look that up for you.",
    "customerName": "John Smith",
    "externalReferenceIds": {
      "orderId": "ORDER-12345",
      "customerId": "cust_abc123"
    },
    "analysisFields": ["sentiment", "followups", "quality"],
    "webhookUrl": "https://your-api.com/webhooks/chanl"
  }'

curl -X POST "https://api.chanl.ai/api/v1/calls/import" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "audioUrl": "https://storage.example.com/calls/recording-123.mp3",
    "customerName": "Jane Doe",
    "callDirection": "inbound",
    "externalReferenceIds": {
      "callId": "ext_call_456"
    }
  }'

const response = await fetch('https://api.chanl.ai/api/v1/calls/import', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer ' + accessToken,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    transcript: 'Agent: Hi, how can I help you today?\nCustomer: I need to check my order status.',
    customerName: 'John Smith',
    externalReferenceIds: {
      orderId: 'ORDER-12345'
    },
    analysisFields: ['sentiment', 'followups'],
    scorecardId: 'scorecard_abc123'
  })
});

const { data } = await response.json();
console.log('Imported call:', data.import.callId);

import requests

response = requests.post(
    'https://api.chanl.ai/api/v1/calls/import',
    headers={'Authorization': f'Bearer {access_token}'},
    json={
        'transcript': 'Agent: Hi, how can I help you today?\nCustomer: I need to check my order status.',
        'customerName': 'John Smith',
        'externalReferenceIds': {
            'orderId': 'ORDER-12345'
        },
        'analysisFields': ['sentiment', 'followups'],
        'scorecardId': 'scorecard_abc123'
    }
)

call_id = response.json()['data']['import']['callId']

Response

{
  "success": true,
  "data": {
    "import": {
      "callId": "695d6957e21c0ceb325c394d",
      "audioId": "",
      "storageKey": "",
      "fileSize": 0,
      "processingStatus": "completed",
      "transcriptId": "695d6957e21c0ceb325c394c",
      "externalReferenceIds": {
        "orderId": "ORDER-12345",
        "customerId": "cust_abc123"
      },
      "importMode": "transcriptOnly"
    }
  }
}

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Transcript cannot be empty",
    "details": ["transcript: Path `transcript` is required"]
  }
}

Transcript Options

transcriptstring | array

Raw transcript text or array of structured segments.

Plain text format:

Agent: Hello, how can I help?
Customer: I have a question about my order.

Structured segments:

[
  { "speaker": "agent", "text": "Hello, how can I help?", "startTime": 0, "endTime": 2000 },
  { "speaker": "customer", "text": "I have a question.", "startTime": 2500, "endTime": 5000 }
]

Audio Options

audioUrlstring

Direct URL to audio file (MP3, WAV, M4A, etc.). Will be transcribed via Deepgram.

audioIdstring

ID of previously uploaded audio record.

S3 Import Options

bucketstring

S3 bucket name.

keystring

S3 object key (path to file).

regionstring

AWS region (e.g., "us-east-1").

accessKeyIdstring

AWS access key ID.

secretAccessKeystring

AWS secret access key.

Metadata

customerNamestring

Customer name or identifier.

customerPhonestring

Customer phone number.

agentNamestring

Agent display name.

callDirectionstring

Call direction: inbound or outbound.

callStartedAtstring

ISO 8601 timestamp when call started.

callEndedAtstring

ISO 8601 timestamp when call ended.

External References

externalReferenceIdsobject

Key-value pairs for correlating with your external systems.

{
  "orderId": "ORDER-12345",
  "customerId": "cust_abc123",
  "ticketId": "TICKET-789"
}

These IDs can be used to filter calls via GET /calls?externalRef.orderId=ORDER-12345.

Analysis Control

analysisFieldsarray

Which analysis fields to compute. When omitted, all fields are analyzed.

Options: followups, sentiment, topics, keywords, coaching, predictions, quality, speakers, upsell, metrics, extraction

scorecardIdstring

Scorecard ID to evaluate against after import.

Custom Data Extraction

customExtractionsarray

Custom fields to extract from the transcript.

[
  {
    "key": "policyNumber",
    "label": "Policy Number",
    "type": "string",
    "promptHint": "Look for policy IDs starting with POL-"
  },
  {
    "key": "claimAmount",
    "label": "Claim Amount",
    "type": "number"
  }
]

extractionTemplateIdstring

ID of a saved extraction template to use.

skipExtractionboolean

Skip data extraction entirely. Default: false.

Webhook Override

webhookUrlstring

Override workspace webhook URL for this import.

webhookSecretstring

HMAC signing secret for webhook verification.

Analysis Fields Reference

Field	Description	Output Location
`followups`	Action items, commitments, follow-up required	`summary.actionItems`
`sentiment`	Beginning/ending sentiment, trend	`summary.sentiment`
`topics`	Main topics discussed	`summary.topics`
`keywords`	Key phrases and terms	`summary.keywords`
`coaching`	Improvement opportunities, knowledge gaps	`summary.coaching`
`predictions`	FCR, callback probability, CSAT prediction	`summary.predictions`
`quality`	Resolution confidence, empathy, compliance	`summary.qualityMetrics`
`speakers`	Agent/customer identification	`summary.speakers`
`upsell`	Upsell opportunity detection	`summary.upsellOpportunity`
`metrics`	Talk time, response time, interruptions	`call.metrics`
`extraction`	Email, phone, order numbers	`call.extractedData`

Rate Limits

100 imports per minute per workspace
10 concurrent imports per workspace
Audio files: max 100MB, min 1KB

On this page