Control Plane

The EVI control plane is a configuration and orchestration API that works alongside your active Chat’s data plane. The reference Chat connection is the data plane that carries live audio and assistant responses. The control plane lets you change how the session runs and observe it in real time, so you can update session settings, rotate provider keys, and attach mirrors from trusted servers without exposing secrets or disrupting the live stream.

Python Example

See the control plane API used to observe an active Chat in Python.

Next.js Example

See the control plane implemented in our Next.js quickstart to securely set a supplemental LLM API key.

When to use the control plane

Use the control plane when you:

• Need to update an active chat without exposing secrets on the client. For example:
  • Setting a supplemental LLM API key
  • Updating the system prompt privately
• Want to mirror a chat to another service for observation, analytics, or moderation while it is running.
• Orchestrate multiple services that coordinate around a single EVI Chat session.

Before you start

• You need an active Chat and its chatId.
• Authentication works the same as other HTTP and WSS endpoints:
  • POST /chat/:chatId/send expects an API key via the X-Hume-Api-Key header.
  • WSS /chat/:chatId/connect accepts an API key via header or an access token via query parameter.
• Control plane changes apply only to the chat identified by chatId.
• Only chats initialized with allow_connection can be connected to with WSS /chat/:chatId/connect

Endpoints (control plane)

Connect to an existing chat

Use WSS /v0/evi/chat/:chatId/connect to attach a secondary connection to a running Chat.

The socket is bi-directional for non-audio (sending audio_input is not permitted). On connect you receive the full session history, then live events in real time, using the same event schema as the reference Chat socket.

Use cases

• Observe and analyze events of an active Chat
• Complete tool use flows server-side

See sample requests below

1
import { HumeClient } from "hume";
2
3
const hume = new HumeClient({ apiKey: process.env.HUME_API_KEY! });
4
5
export async function connectControlPlane(chatId: string) {
6
  const socket = await hume.empathicVoice.controlPlane.connect({
7
    chatId
8
  });
9
10
  // history is replayed first, then live events
11
  socket.on("message", (event) => {
12
    console.log("[control-plane]", event);
13
  });
14
15
  // optional lifecycle hooks
16
  socket.on("open", () => console.log("Control plane connected"));
17
  socket.on("close", () => console.log("Control plane closed"));
18
19
  return socket;
20
}

Post messages to an active chat

Use POST /v0/evi/chat/:chatId/send to send control messages to the active chat.

You can send any message type that the Chat accepts, except audio_input. This includes updating session settings and any other publish messages supported by EVI.

Use cases

• Update the system prompt for the current session.
• Rotate or set a supplemental LLM API key server-side.
• Instruct EVI to communicate notifications from your server.

See sample requests below:

1
curl "https://api.hume.ai/v0/evi/chat/<CHAT_ID>/send" \
2
  -H "X-Hume-Api-Key: $HUME_API_KEY" \
3
  --json '{
4
    "type": "session_settings",
5
    "language_model_api_key": "<SUPPLEMENTAL_LLM_KEY>"
6
  }'