Voice uses a persistent Socket.IO connection. Set config.modality to voice and enable config.audioEvents in client.start to receive streamed speech audio. Choose an audioEncoding your playback pipeline supports; input and output audio formats are configured separately.

Session identity

A session holds the conversation state an agent uses across turns. Your application creates a session when a customer starts a conversation, then keeps its sessionKey to continue that conversation. Creating a session and sending a message are separate actions.

Choosing an Environment

Select the Environment when starting a session. An Environment alias, such as main, identifies the target without using its display name.

Traffic-split routing uses the user identifier to assign the Environment consistently. Configure the distribution in Environments. This selects where a new session runs; an existing session key continues its existing conversation.

Continuing a conversation

Keep the user’s session key in your application’s conversation state. A userID alone does not replace the session credential.

After the handshake is ready, send action.send on that session. With server-managed voice turns, the runtime submits recognized speech; do not submit the same utterance again.

Resuming a session

A Socket.IO connection and a conversation session have different lifetimes. After a temporary disconnection:

  • Reconnect: reconnect the socket, then emit client.start with the same project, user, Environment choice and saved sessionKey.
  • Resume: wait for client.started. When newSessionRequired is false, continue the existing session.
  • Replace when required: when newSessionRequired is true, create a new session and replace the saved key with the one from session.created.

Connection configuration

Use socket.io-client, with the runtime URL and path below. This is a Socket.IO connection; a raw WebSocket client cannot perform its handshake. Install the client in your application:

Install the Socket.IO client
Create the connection

autoConnect: false lets you register the following handlers before connecting. Socket.IO owns reconnection timing and transport selection; use its client options when configuring those settings.

Lifecycle

Initialization sequence

On both the first connection and a reconnect:

1

Initialize the client

Wait for Socket.IO’s connect event, then emit client.start with your project ID, user ID, Environment alias and any saved session key.

2

Check session readiness

Read client.started.newSessionRequired. If it is false, the existing session is ready. If it is true, emit session.create and wait for session.created.

3

Retain the session key

Save the key from session.created in application state. Use it on the next connection instead of creating a replacement session.

This example continues from the socket created above. It uses a project with public API access; private projects require an authenticated trusted client.

Initialize or resume the session

Register the handlers once, outside connect, so each reconnect does not add another copy. A successful connection and session handshake does not confirm that an interrupted action completed.

Action lifecycle

Send an action only after the session is ready, then track its status:

Use messageID to correlate status and traces. See action.send for action shapes and Playback and responses for listeners.

Conversation lifecycle

Start

Once ready is true, send launch once to start the conversation. Later user messages use text with the same session.

Start the conversation

To trigger a configured event, send its name in an event action:

Trigger a configured event

End

session.ended ends the conversation, including when the runtime ends an inactive session. Clear the key and stop sending actions to that session. A Socket.IO disconnect alone does not mean the conversation ended.

Reconnect after an interruption

On reconnect, repeat client.start with the saved key and wait for client.started. Create a replacement session only if newSessionRequired is true. Resolve an interrupted action’s effects before resending it; messageID correlates events and is not an idempotency guarantee.

The Socket.IO client API defines connect, disconnect and connect_error. The sections below define Voiceflow’s application events.

Client events

client.start

Initializes the Voiceflow connection after Socket.IO connects. Send it on each connection, including a reconnect, with the same userID, project and saved session key. The server responds with client.started.

For browser clients, include projectID. Omit authorization only when the project allows public API access. Private projects require an authorized trusted client; keep its API credential on your server.

Create a personal key or service key with the needed permissions. Supplying a saved sessionKey resumes conversation state; it does not bypass this project access check. Keep private-project credentials on your server and relay your application’s audio and runtime events through that trusted connection.

config.completionEvents and config.audioEvents are optional and default to false. The fields below describe the connection settings used by this reference.

?: denotes optional properties.

client.start payload
client.start example

session.create

Creates a new session for the user. Should be sent after client.started indicates newSessionRequired: true. Server will respond with session.created.

session.create example

action.send

Sends a user action to the server. A valid session must already exist. Server will respond with action.status and action.trace events.

Supply messageID to correlate the returned trace and status events with your action; the server generates an ID when you omit it. Voice clients use these actions:

action.send payload
action.send example

Server events

client.started

Acknowledges client.start with the resolved versionID and whether a new session is required. If newSessionRequired is false, the supplied session is ready; otherwise emit session.create.

client.started payload
client.started listener example

session.created

Confirms that a new session has been created. Client should store the sessionKey for future reconnections.

session.created payload
session.created listener example

session.ended

Indicates that the conversation session has ended. Client should close the session and optionally display a workflow to create a new one.

session.ended payload

action.trace

Represents agent responses and debugging information for an action. See possible trace types.

action.trace payload
action.trace listener example

action.status

Indicates the status of an action that was sent via action.send. This event is sent when an action is accepted, rejected, or completed.

action.status payload

server.restart

Server is gracefully shutting down and informing the client to reconnect to a different server instance.

server.restart payload

error

Reports a runtime error through the error event. Read error for the message; code is optional. Socket.IO connection errors arrive separately through connect_error.

error payload

Use the up and down arrow keys to select a result, Enter to open it, and Escape to close the search.