Control Plane
Connects to an in-progress EVI chat session. The original chat must have been started with allow_connection=true. The connection can be used to send and receive the same messages as the original chat, with the exception that audio_input messages are not allowed.
Handshake
Path parameters
Query parameters
Access token used for authenticating the client. If not provided, an api_key must be provided to authenticate.
The access token is generated using both an API key and a Secret key, which provides an additional layer of security compared to using just an API key.
For more details, refer to the Authentication Strategies Guide.
Send
Settings for this chat session. Session settings are temporary and apply only to the current Chat session.
These settings can be adjusted dynamically based on the requirements of each session to ensure optimal performance and user experience. See our Session Settings Guide for a complete list of configurable settings.
User text to insert into the conversation. Text sent through a User Input message is treated as the user’s speech to EVI. EVI processes this input and provides a corresponding response.
Expression measurement results are not available for User Input messages, as the prosody model relies on audio input and cannot process text alone.
Assistant text to synthesize into spoken audio and insert into the conversation. EVI uses this text to generate spoken audio using our proprietary expressive text-to-speech model.
Our model adds appropriate emotional inflections and tones to the text based on the user’s expressions and the context of the conversation. The synthesized audio is streamed back to the user as an Assistant Message.
Return value of the tool call. Contains the output generated by the tool to pass back to EVI. Upon receiving a Tool Call message and successfully invoking the function, this message is sent to convey the result of the function call back to EVI.
For built-in tools implemented on the server, you will receive this message type rather than a ToolCallMessage. See our Tool Use Guide for further details.
Error message from the tool call, not exposed to the LLM or user. Upon receiving a Tool Call message and failing to invoke the function, this message is sent to notify EVI of the tool’s failure.
For built-in tools implemented on the server, you will receive this message type rather than a ToolCallMessage if the tool fails. See our Tool Use Guide for further details.
Pause responses from EVI. Chat history is still saved and sent after resuming. Once this message is sent, EVI will not respond until a Resume Assistant message is sent.
When paused, EVI won’t respond, but transcriptions of your audio inputs will still be recorded. See our Pause Response Guide for further details.
Resume responses from EVI. Chat history sent while paused will now be sent.
Upon resuming, if any audio input was sent during the pause, EVI will retain context from all messages sent but only respond to the last user message. See our Pause Response Guide for further details.
Receive
Indicates the conclusion of the assistant’s response, signaling that the assistant has finished speaking for the current conversational turn.
Transcript of the assistant’s message. Contains the message role, content, and optionally tool call information including the tool name, parameters, response requirement status, tool call ID, and tool type.
Expression measurement predictions of the assistant’s audio output. Contains inference model results including prosody scores for 48 emotions within the detected expression of the assistant’s audio sample.
Base64 encoded audio output. This encoded audio is transmitted to the client, where it can be decoded and played back as part of the user interaction. The returned audio format is WAV and the sample rate is 48kHz.
Contains the audio data, an ID to track and reference the audio output, and an index indicating the chunk position relative to the whole audio segment. See our Audio Guide for more details on preparing and processing audio.
The first message received after establishing a connection with EVI, containing important identifiers for the current Chat session.
Includes the Chat ID (which allows the Chat session to be tracked and referenced) and the Chat Group ID (used to resume a Chat when passed in the resumed_chat_group_id query parameter of a subsequent connection request, allowing EVI to continue the conversation from where it left off within the Chat Group).
Indicates a disruption in the WebSocket connection, such as an unexpected disconnection, protocol error, or data transmission issue.
Contains an error code identifying the type of error encountered, a detailed description of the error, and a short, human-readable identifier and description (slug) for the error.
Indicates the user has interrupted the assistant’s response. EVI detects the interruption in real-time and sends this message to signal the interruption event.
This message allows the system to stop the current audio playback, clear the audio queue, and prepare to handle new user input. Contains a Unix timestamp of when the user interruption was detected. For more details, see our Interruptibility Guide
Transcript of the user’s message. Contains the message role and content, along with a from_text field indicating if this message was inserted into the conversation as text from a UserInput message.
Includes an interim field indicating whether the transcript is provisional (words may be repeated or refined in subsequent UserMessage responses as additional audio is processed) or final and complete. Interim transcripts are only sent when the verbose_transcription query parameter is set to true in the initial handshake.
Indicates that the supplemental LLM has detected a need to invoke the specified tool. This message is only received for user-defined function tools.
Contains the tool name, parameters (as a stringified JSON schema), whether a response is required from the developer (either in the form of a ToolResponseMessage or a ToolErrorMessage), the unique tool call ID for tracking the request and response, and the tool type. See our Tool Use Guide for further details.
Return value of the tool call. Contains the output generated by the tool to pass back to EVI. Upon receiving a Tool Call message and successfully invoking the function, this message is sent to convey the result of the function call back to EVI.
For built-in tools implemented on the server, you will receive this message type rather than a ToolCallMessage. See our Tool Use Guide for further details.
Error message from the tool call, not exposed to the LLM or user. Upon receiving a Tool Call message and failing to invoke the function, this message is sent to notify EVI of the tool’s failure.
For built-in tools implemented on the server, you will receive this message type rather than a ToolCallMessage if the tool fails. See our Tool Use Guide for further details.
Settings for this chat session. Session settings are temporary and apply only to the current Chat session.
These settings can be adjusted dynamically based on the requirements of each session to ensure optimal performance and user experience. See our Session Settings Guide for a complete list of configurable settings.