SDK Overview

The Chanl SDK gives you programmatic access to the platform API: build agent capabilities, test them with simulated conversations, and monitor quality in production. For embedding chat or voice on your website, use the sibling package @chanl/widget-sdk.

Packages

Package	Install	Purpose
`@chanl/sdk`	`npm install @chanl/sdk`	Server-side platform API (agents, tools, scenarios, …)
`@chanl/widget-sdk`	`npm install @chanl/widget-sdk`	Browser embed script, React hooks, voice
`@chanl/cli`	`npm install -g @chanl/cli`	Command-line interface

Installation (`@chanl/sdk`)

npm install @chanl/sdk

Setup

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

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

Store your API key in environment variables. Never commit it to source control.

What you can do

The SDK maps to the three pillars of the Chanl platform.

Build

Give your agents tools, knowledge, and the ability to hold conversations.

// Create a tool your agent can call mid-conversation
const tool = await chanl.tools.create({
  name: 'lookup_order',
  description: 'Look up order details by order number',
  parameters: {
    type: 'object',
    properties: {
      order_id: { type: 'string', description: 'The order number' },
    },
    required: ['order_id'],
  },
  handlerUrl: 'https://api.yourstore.com/orders/lookup',
});

// Add documents to the knowledge base
const entry = await chanl.knowledge.create({
  title: 'Return Policy',
  source: 'text',
  content: 'Returns accepted within 30 days of purchase...',
});

// Test your agent with a chat session
const session = await chanl.chat.createSession('agent_abc123');
const response = await chanl.chat.sendMessage(
  session.sessionId,
  'What is your return policy?'
);

Test

Import calls and evaluate them against quality scorecards.

// Import a call transcript for analysis
const imported = await chanl.calls.import({
  transcript: `
    Agent: Thank you for calling Acme Support, this is Sarah.
    Customer: Hi, my order arrived damaged.
    Agent: I'm sorry to hear that. Let me process a replacement right away.
    Customer: That would be great, thanks!
  `,
  analysisFields: ['sentiment', 'topics', 'quality'],
});

// Evaluate the call against a scorecard
const evaluation = await chanl.scorecard.evaluate(
  imported.callId,
  { scorecardId: 'scorecard_abc123' }
);

console.log('Score:', evaluation.score + '%');
console.log('Passed:', evaluation.passed);

Monitor

Query calls, review results, and track quality over time.

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

// Get evaluation results for a specific call
const { results } = await chanl.scorecard.getResults(callId);

results.forEach((result) => {
  console.log(`${result.scorecardName}: ${result.score}%`);
  result.criteriaResults.forEach((cr) => {
    console.log(`  ${cr.passed ? 'PASS' : 'FAIL'} ${cr.name}: ${cr.score}%`);
  });
});

SDK modules

Module	Description	Phase
`chanl.tools`	Create and manage tools agents can call	Build
`chanl.toolsets`	Group tools into reusable collections	Build
`chanl.knowledge`	Ingest documents, search with hybrid queries	Build
`chanl.chat`	Test agents with text-based conversations	Build
`chanl.prompts`	Manage versioned prompt templates	Build
`chanl.calls`	Import, list, query, and delete calls	Test
`chanl.scorecard`	Create scorecards and evaluate calls	Test
`chanl.agents`	Sync and manage AI agents	Monitor
`chanl.mcp`	MCP server configuration	Build
`@chanl/widget-sdk`	Embed chat/voice on your site	Connect

See the Widget SDK reference and Chat widget guide.

Error handling

The SDK provides typed errors so you can handle each failure case precisely.

import {
  ChanlError,
  ValidationError,
  NotFoundError,
  AuthenticationError,
  RateLimitError,
} from '@chanl/sdk';

try {
  const call = await chanl.calls.get('call_123');
} catch (error) {
  if (error instanceof NotFoundError) {
    console.log('Call not found:', error.message);
  } else if (error instanceof ValidationError) {
    console.log('Validation failed:', error.details);
  } else if (error instanceof AuthenticationError) {
    console.log('Auth error - check your API key');
  } else if (error instanceof RateLimitError) {
    console.log('Rate limited, retry after:', error.retryAfter);
  } else if (error instanceof ChanlError) {
    console.log('API error:', error.code, error.message);
  }
}

TypeScript types

Full type definitions ship with the package. Your IDE gets autocompletion and compile-time safety out of the box.

import type {
  Call,
  CallImportOptions,
  Scorecard,
  ScorecardResult,
  Tool,
  Toolset,
  KnowledgeEntry,
  KnowledgeSearchResult,
  ChatSessionResponse,
  ChatMessageResponse,
} from '@chanl/sdk';

Next steps

Analyze Calls

Import recordings, transcribe audio, and extract insights with AI.

Evaluate Quality

Score calls with custom scorecards and track compliance.

Automate with Tools

Create tools, group them in toolsets, and connect via MCP.

Chat Module

Test agents with text-based multi-turn conversations.

Widget SDK

Embed chat and voice on your site with React hooks or a script tag.

Analyze Calls

Evaluate Quality

Automate with Tools

Chat Module

Widget SDK

On this page