Example: Answering an incoming call

For the complete documentation index, see llms.txt.

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

Set up an inbound entrypoint for the caller:
Create a routing rule that points the destination (phone number / WhatsApp / SIP username / app user alias) to this scenario.
Store your Cartesia API key in Voximplant Secrets under CARTESIA_API_KEY
Store your Cartesia Agent ID in Voximplant ApplicationStorage under CARTESIA_AGENT_ID (the agent ID is not sensitive, so it can live in key-value storage)

Session setup

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

Create Cartesia client

1 voiceAIClient = await Cartesia.createAgentsClient({
2   apiKey: VoxEngine.getSecretValue('CARTESIA_API_KEY'),
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

1 voiceAIClient.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)

1 voiceAIClient.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 
6 require(Modules.Cartesia);
7 require(Modules.ApplicationStorage);
8 
9 VoxEngine.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: VoxEngine.getSecretValue('CARTESIA_API_KEY'),
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 });