Messaging
Send messages and commands to the agent from your code
Voice is the primary way users talk to the agent — but your code can message it too. This page covers the SDK's sending surface: injecting messages into the conversation and driving the session with typed commands. For what you receive, see Events.
Send a message
Inject text as the user, or as silent system context
Command reference
Every command sendCommand accepts
From your backend
Injecting context server-side
Send a message
Use sendCommand with a SEND_MESSAGE command. Commands are typed as DataChannelCommand — a discriminated union keyed by type, from the exported DataChannelMessageType enum.
import {
NapsterCompanionApiSdk,
DataChannelMessageType,
} from "@touchcastllc/napster-companion-api";
// Send a text message as the user and trigger a response
instance.sendCommand({
type: DataChannelMessageType.SEND_MESSAGE,
data: {
text: "Hello",
role: "user",
trigger_response: true,
},
});The role decides how the message enters the conversation:
"user"— treated as if the user typed it. Pair withtrigger_response: trueso the agent answers."system"— a silent context update: the agent absorbs the information and uses it when relevant. Ideal for feeding page state or app events into the conversation ("The user just opened the billing page").
// Silent context: inform the agent without triggering a spoken response
instance.sendCommand({
type: DataChannelMessageType.SEND_MESSAGE,
data: {
text: "The user just opened the billing page.",
role: "system",
trigger_response: false,
delay: true,
},
});SendMessageData
| Field | Type | Required | Description |
|---|---|---|---|
text | string | Yes | The message text. |
role | "user" | "system" | Yes | Who the message is from. |
trigger_response | boolean | Yes | Whether the agent should respond. |
previous_item_id | string | No | ID of the previous message in the thread. |
delay | boolean | No | Hold the message until the agent finishes speaking. |
Command reference
sendCommand accepts the full command union:
DataChannelMessageType | Value | Payload | Purpose |
|---|---|---|---|
SEND_MESSAGE | "send_message" | SendMessageData | Send a text message into the conversation. |
CANCEL | "cancel" | — | Interrupt the agent's current response. |
SET_SETTINGS | "set_settings" | { modality?, functions?, inline_functions? } | Update session settings, including registering tools mid-session. |
START_VIDEO | "start_video" | null | Start the video stream. |
STOP_VIDEO | "stop_video" | null | Stop the video stream. |
FUNCTION_CALL_OUTPUT | "function_call_output" | { call_id, output } | Return the result of an agent function call. |
Most integrations don't send raw commands — the SDK sends start_video / stop_video for screen sharing, and stopAvatarTalking() wraps cancel. Reach for sendCommand when you need to inject a message or manage settings directly. For the protocol as a whole — the same commands over both WebRTC and WebSocket — see Client Commands.
From your backend
Your client isn't the only side that can put words into the conversation. A WebSocket-based explicit tool's functions server can inject context server-side with context_update — the backend sibling of send_message, typically used to deliver deferred tool results. See Updating the conversation context.