Chanl

Chat Module

Test agents with text-based multi-turn conversations

The Chat module lets you test your AI agents with text-based conversations before they handle real users. Create a session, send messages, review the conversation, and validate that the agent behaves correctly.

Installation

npm install @chanl/sdk

Setup

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

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

Create a session

Start a new chat session with a specific agent. Each session is an independent conversation with its own context and history.

const session = await chanl.chat.createSession('agent_abc123');

console.log('Session ID:', session.sessionId);
console.log('Interaction ID:', session.interactionId);
console.log('Agent ID:', session.agentId);

Parameters:

ParameterTypeRequiredDescription
agentIdstringYesThe agent to chat with

Returns: Promise<ChatSessionResponse>

Send a message

Send a text message and get the agent's response. Each message is added to the conversation history, so the agent has full context of the session.

const response = await chanl.chat.sendMessage(
  session.sessionId,
  'Hi, I need help with my account.'
);

console.log('Agent:', response.message);

Parameters:

ParameterTypeRequiredDescription
sessionIdstringYesThe active session ID
messagestringYesThe user message to send

Returns: Promise<ChatMessageResponse>

Multi-turn conversations

The agent remembers everything said in the session. You can build up complex scenarios turn by turn.

const session = await chanl.chat.createSession('agent_abc123');

// Turn 1: Open with a question
const r1 = await chanl.chat.sendMessage(
  session.sessionId,
  'I need to return a laptop I bought last week.'
);
console.log('Agent:', r1.message);

// Turn 2: Provide details
const r2 = await chanl.chat.sendMessage(
  session.sessionId,
  'The order number is ORDER-12345. The screen arrived cracked.'
);
console.log('Agent:', r2.message);

// Turn 3: Follow up
const r3 = await chanl.chat.sendMessage(
  session.sessionId,
  'How long will the replacement take?'
);
console.log('Agent:', r3.message);

// Turn 4: Test edge case
const r4 = await chanl.chat.sendMessage(
  session.sessionId,
  'Actually, I changed my mind. I want a refund instead.'
);
console.log('Agent:', r4.message);

Get message history

Retrieve the full conversation from a session. Useful for reviewing what happened or running assertions in automated tests.

const history = await chanl.chat.getMessages(session.sessionId);

console.log(`${history.messages.length} messages:`);
history.messages.forEach((msg) => {
  console.log(`  ${msg.role}: ${msg.content}`);
});

Parameters:

ParameterTypeRequiredDescription
sessionIdstringYesThe session to retrieve

Returns: Promise<ChatMessagesResponse>

Each message in the response has:

FieldTypeDescription
rolestringuser or assistant
contentstringMessage text
timestampstringISO 8601 timestamp

End a session

Signal that the conversation is over. The agent stops processing after this call.

await chanl.chat.endSession(session.sessionId);

Returns: Promise<EndChatResponse>

Delete a session

Permanently remove a session and all its messages.

await chanl.chat.deleteSession(session.sessionId);

Returns: Promise<DeleteChatResponse>

Automated agent testing

Use the chat module in your test suite to verify agent behavior programmatically.

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

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

async function testAgentHandlesRefund(agentId: string) {
  const session = await chanl.chat.createSession(agentId);

  try {
    // Simulate a refund request
    await chanl.chat.sendMessage(session.sessionId, 'I want a refund for order ORDER-999.');

    const response = await chanl.chat.sendMessage(
      session.sessionId,
      'The item was defective.'
    );

    // Verify the agent handled the refund flow
    const history = await chanl.chat.getMessages(session.sessionId);
    const agentMessages = history.messages
      .filter((m) => m.role === 'assistant')
      .map((m) => m.content.toLowerCase());

    const mentionsRefund = agentMessages.some((m) => m.includes('refund'));
    const asksForDetails = agentMessages.some(
      (m) => m.includes('order') || m.includes('details')
    );

    console.log('Mentions refund:', mentionsRefund);
    console.log('Asks for details:', asksForDetails);

    return { mentionsRefund, asksForDetails };
  } finally {
    await chanl.chat.endSession(session.sessionId);
    await chanl.chat.deleteSession(session.sessionId);
  }
}

Test multiple scenarios

Run several conversation scenarios against the same agent to validate coverage.

const scenarios = [
  {
    name: 'Happy path - order status',
    messages: [
      'What is the status of my order?',
      'ORDER-12345',
      'Thanks!',
    ],
  },
  {
    name: 'Escalation - angry customer',
    messages: [
      'This is ridiculous, my package never arrived!',
      'I have been waiting for 3 weeks!',
      'I want to speak to a manager.',
    ],
  },
  {
    name: 'Edge case - off-topic',
    messages: [
      'What is the weather like today?',
      'Can you help me write a poem?',
    ],
  },
];

async function runScenarios(agentId: string) {
  for (const scenario of scenarios) {
    console.log(`\nRunning: ${scenario.name}`);
    const session = await chanl.chat.createSession(agentId);

    for (const message of scenario.messages) {
      const response = await chanl.chat.sendMessage(session.sessionId, message);
      console.log(`  User: ${message}`);
      console.log(`  Agent: ${response.message}`);
    }

    await chanl.chat.endSession(session.sessionId);
    console.log('  Done.');
  }
}

Full example

End-to-end workflow: create a session, run a conversation, review history, and clean up.

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

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

async function testSupportAgent(agentId: string) {
  // 1. Start a session
  const session = await chanl.chat.createSession(agentId);
  console.log('Session started:', session.sessionId);

  // 2. Run a multi-turn conversation
  const greeting = await chanl.chat.sendMessage(
    session.sessionId,
    'Hi, I have a question about my recent order.'
  );
  console.log('Agent:', greeting.message);

  const details = await chanl.chat.sendMessage(
    session.sessionId,
    'The order number is ORDER-12345. Can you check the status?'
  );
  console.log('Agent:', details.message);

  const followUp = await chanl.chat.sendMessage(
    session.sessionId,
    'When will it arrive?'
  );
  console.log('Agent:', followUp.message);

  // 3. Review the full conversation
  const history = await chanl.chat.getMessages(session.sessionId);
  console.log(`\nConversation (${history.messages.length} messages):`);
  history.messages.forEach((msg) => {
    console.log(`  ${msg.role}: ${msg.content}`);
  });

  // 4. Clean up
  await chanl.chat.endSession(session.sessionId);
  await chanl.chat.deleteSession(session.sessionId);
  console.log('\nSession ended and deleted.');
}

Types

import type {
  ChatSessionResponse,
  ChatMessageResponse,
  ChatMessage,
  ChatMessagesResponse,
  EndChatResponse,
  DeleteChatResponse,
} from '@chanl/sdk';

Next steps

Analyze Calls

Import and analyze real call recordings alongside chat testing.

Evaluate Quality

Score conversations against quality scorecards.

Automate with Tools

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

Calls Module

Import, query, and manage calls with the SDK

On this page

Installation
Setup
Create a session
Send a message
Multi-turn conversations
Get message history
End a session
Delete a session
Automated agent testing
Test multiple scenarios
Full example
Types
Next steps