Cartesia Line Agents

Example: Answering an incoming call

View as MarkdownOpen in Claude

This example answers an inbound Voximplant call and bridges audio to Cartesia Line Agents for real-time speech-to-speech conversations.

Jump to the Full VoxEngine scenario.

Prerequisites

Session setup

Create a Cartesia.AgentsClient with your API key, API version, and agent ID:

Create Cartesia client
1voiceAIClient = await Cartesia.createAgentsClient({
2  apiKey: (await ApplicationStorage.get("CARTESIA_API_KEY")).value,
3  cartesiaVersion: "2025-04-16",
4  agentId: (await ApplicationStorage.get("CARTESIA_AGENT_ID")).value,
5});

After client creation, send a start event with optional metadata:

Start session
1voiceAIClient.start({
2  metadata: {
3    channel: "voice",
4    provider: "voximplant",
5    mode: "inbound"
6  }
7});

Events

The example logs key lifecycle and debugging events:

Events (example from the scenario)
1voiceAIClient.addEventListener(Cartesia.AgentsEvents.ACK, (event) => {
2  Logger.write("===Cartesia.Agents.ACK===");
3  if (event?.data) Logger.write(JSON.stringify(event.data));
4});

Notes

See the VoxEngine API Reference for more details.

Full VoxEngine scenario

voxeengine-cartesia-inbound.js
1/**
2 * Voximplant + Cartesia Line Agents connector demo
3 * Scenario: answer an incoming call and bridge it to Cartesia.
4 */
5
6require(Modules.Cartesia);
7require(Modules.ApplicationStorage);
8
9VoxEngine.addEventListener(AppEvents.CallAlerting, async ({call}) => {
10    let voiceAIClient;
11
12    // Termination handlers
13    call.addEventListener(CallEvents.Disconnected, () => VoxEngine.terminate());
14    call.addEventListener(CallEvents.Failed, () => VoxEngine.terminate());
15
16    try {
17        call.answer();
18        // Optional: record & transcribe the call. Note:`require(Modules.ASR)` needed for TranscriptionProvider enum
19        // call.record({hd_audio: true, stereo: true, transcribe: true, provider: TranscriptionProvider.GOOGLE });
20
21        // Create client and connect to Cartesia Agents
22        voiceAIClient = await Cartesia.createAgentsClient({
23            apiKey: (await ApplicationStorage.get("CARTESIA_API_KEY")).value,
24            cartesiaVersion: "2025-04-16",
25            agentId: (await ApplicationStorage.get("CARTESIA_AGENT_ID")).value,
26            onWebSocketClose: (event) => {
27                Logger.write("===Cartesia.WebSocket.Close===");
28                if (event) Logger.write(JSON.stringify(event));
29                VoxEngine.terminate();
30            },
31        });
32
33        // Start the client and pass optional metadata
34        voiceAIClient.start({
35            metadata: {channel: "voice", provider: "voximplant", mode: "inbound"},
36        });
37
38        // Send the call media to the Agent
39        VoxEngine.sendMediaBetween(call, voiceAIClient);
40
41        // Consolidated log only handlers for debugging
42        [
43            Cartesia.AgentsEvents.ACK,
44            Cartesia.AgentsEvents.Clear,
45            Cartesia.AgentsEvents.ConnectorInformation,
46            Cartesia.AgentsEvents.DTMF,
47            Cartesia.AgentsEvents.Unknown,
48            Cartesia.AgentsEvents.WebSocketError,
49            Cartesia.Events.WebSocketMediaStarted,
50            Cartesia.Events.WebSocketMediaEnded,
51        ].forEach((eventName) => {
52            voiceAIClient.addEventListener(eventName, (event) => {
53                Logger.write(`===${event.name}===>${JSON.stringify(event.data) || ""}`);
54            });
55        });
56    } catch (error) {
57        Logger.write("===UNHANDLED_ERROR===");
58        Logger.write(error);
59        voiceAIClient?.close();
60        VoxEngine.terminate();
61    }
62});