Calls Module

The Calls module handles the full lifecycle of call records: import transcripts or audio, query with filters, retrieve details, and clean up when done.

Installation

npm install @chanl/sdk

Setup

import { Chanl } from '@chanl/sdk';

const chanl = new Chanl({
  apiKey: process.env.CHANL_API_KEY,
});

import

Import call data from a transcript, audio URL, audio file reference, or S3 bucket. Only one input source per import.

From a transcript

const result = await chanl.calls.import({
  transcript: `
    Agent: Thank you for calling Acme Support, this is Sarah.
    Customer: Hi, I have a question about my bill.
    Agent: I'd be happy to help with that. Can you provide your account number?
  `,
  customerName: 'John Doe',
  customerPhone: '+1234567890',
  agentName: 'Sarah',
  direction: 'inbound',
  externalReferenceIds: {
    orderId: 'ORDER-12345',
    customerId: 'cust_abc123',
  },
});

console.log('Call ID:', result.callId);
console.log('Status:', result.processingStatus);

From an audio URL

const result = await chanl.calls.import({
  audioUrl: 'https://storage.example.com/recordings/call-123.mp3',
  customerName: 'Jane Smith',
});

With analysis and evaluation

const result = await chanl.calls.import({
  transcript: '...',
  analysisFields: ['sentiment', 'topics', 'quality', 'followups'],
  scorecardId: 'scorecard_abc123',
  customExtractions: [
    {
      key: 'order_number',
      description: 'Extract any order numbers mentioned',
      type: 'string',
    },
  ],
});

Parameters:

Parameter	Type	Required	Description
`transcript`	`string`	One source required	Plain text transcript
`transcriptSegments`	`array`	One source required	Structured transcript with speakers and timestamps
`audioUrl`	`string`	One source required	URL to audio file (MP3, WAV, M4A, FLAC, OGG, WEBM)
`audioId`	`string`	One source required	Reference to uploaded audio
`customerName`	`string`	No	Customer name
`customerPhone`	`string`	No	Customer phone number
`agentName`	`string`	No	Agent name
`direction`	`string`	No	`inbound`, `outbound`, or `web`
`externalReferenceIds`	`object`	No	Key-value pairs for linking to your systems
`analysisFields`	`string[]`	No	Which analyses to run (sentiment, topics, quality, etc.)
`scorecardId`	`string`	No	Auto-evaluate with this scorecard
`customExtractions`	`array`	No	Custom data fields to extract
`webhookUrl`	`string`	No	Override webhook URL for completion notification

Returns: Promise<CallImportResponse>

list

Query calls with filters and pagination.

// Basic list
const { calls, pagination } = await chanl.calls.list();

// With filters
const { calls } = await chanl.calls.list({
  status: 'ended',
  direction: 'inbound',
  startDate: '2026-01-01',
  endDate: '2026-01-31',
  limit: 50,
});

// Filter by external reference
const { calls } = await chanl.calls.list({
  externalRefs: { orderId: 'ORDER-12345' },
});

// Combine multiple external refs
const { calls } = await chanl.calls.list({
  externalRefs: {
    customerId: 'cust_abc123',
    campaignId: 'camp_2026',
  },
});

Parameters:

Parameter	Type	Required	Description
`status`	`string`	No	Filter by call status
`direction`	`string`	No	`inbound`, `outbound`, or `web`
`customerName`	`string`	No	Filter by customer name
`startDate`	`string`	No	Start of date range (ISO 8601)
`endDate`	`string`	No	End of date range (ISO 8601)
`externalRefs`	`object`	No	Filter by external reference IDs
`page`	`number`	No	Page number (1-indexed)
`limit`	`number`	No	Items per page (max 100)
`sortBy`	`string`	No	Field to sort by
`sortOrder`	`string`	No	`asc` or `desc`

Returns: Promise<{ calls: Call[]; pagination: Pagination }>

get

Retrieve detailed information for a single call, including analysis results and transcript.

const call = await chanl.calls.get('695d6957e21c0ceb325c394d');

console.log('Duration:', call.duration);
console.log('Sentiment:', call.summary?.sentiment);
console.log('Topics:', call.summary?.topics);

// Access transcript segments
call.transcript?.segments.forEach((segment) => {
  console.log(`${segment.speaker}: ${segment.text}`);
});

Parameters:

Parameter	Type	Required	Description
`callId`	`string`	Yes	The call ID to retrieve

Returns: Promise<Call>

delete

Remove a single call record.

await chanl.calls.delete('695d6957e21c0ceb325c394d');

Parameters:

Parameter	Type	Required	Description
`callId`	`string`	Yes	The call ID to delete

Returns: Promise<void>

bulkDelete

Remove multiple calls in one operation.

const result = await chanl.calls.bulkDelete({
  callIds: [
    '695d6957e21c0ceb325c394d',
    '695d6957e21c0ceb325c394e',
    '695d6957e21c0ceb325c394f',
  ],
  deleteStorageFiles: true,
});

console.log('Deleted:', result.deletedCount);

Parameters:

Parameter	Type	Required	Description
`callIds`	`string[]`	Yes	Call IDs to delete
`deleteStorageFiles`	`boolean`	No	Also delete associated audio files

Returns: Promise<BulkDeleteResponse>

Types

import type {
  Call,
  CallImportOptions,
  CallImportResponse,
  CallListOptions,
  CallDirection,
  CallStatus,
  TranscriptSegment,
  BulkDeleteOptions,
  BulkDeleteResponse,
} from '@chanl/sdk';

Installation

Setup

import

From a transcript

From an audio URL

With analysis and evaluation

list

get

delete

bulkDelete

Types

Next steps

Analyze Calls

Scorecards Module

On this page