Custom Voice Bot WebSocket interface

You can find here all the information that is required to build a WebSocket server that will serve your custom voice bot logic within a Buzzeasy workflow.

WebSocket handshake

For every conversation where the workflow reaches a Custom Voice Bot node, Buzzeasy will open a WebSocket connection to your server. The request will contain your Api Key in the x-api-key and header and the conversation metadata in query parameter:

Query parameters:

Key	Value
conversationId	Unique identifier of the conversation
botId	The id of the bot that has been activated from the workflow
tenantId	The identifier of the Buzzeasy tenant where conversation is coming from

Example: GET wss://custom-voice-bot.yourdomain.ai?conversationId=07a6c562b1cf40818e5c4724351c45d4&botId=29adeb50094b4bbaac7758370815bc86&tenantId=691ed11961a8290d7b008fcd
X-Api-Key: you_secret_key
Upgrade: websocket

Messages

These are the WebSocket messages between Buzzeasy (WebSocket client) and your bot (WebSocket server). Messages that you need to handle are called events, and messages that you can send are called commands.

Events

Session Initialized

SessionInitialized is sent after the WebSocket connection establishment, indicating that the service is ready to accept bot messages.

Properties:

Name	Type	Required	Value
messageType	string	✅	"SessionInitialized"
workflowData	object (string key value pairs)	✅	Conversation's Workflow data

Example:

{
  "messageType": "SessionInitialized",
  "workflowData": {
    "Your_key": "Your_value"
  }
}

Customer Message Received

CustomerMessageReceived is sent once there is a complete transcription segment from the customer. The length of the segment will vary based what is the Customer End Speech Detection Timeout configuration value and the way the customer actually speaks.

Properties:

Name	Type	Required	Value
messageType	string	✅	"CustomerMessageReceived"
text	string	✅	Customer message to your bot

Example:

{
  "messageType": "CustomerMessageReceived",
  "text": "Hello bot!"
}

Bot Message Played

BotMessagePlayed is sent once the given message (or message chunk) has been synthetized and played to the customer. In case the customer interrupted the bot, the text will include the actually played words only, otherwise each property value will reflect the values from the SendBotMessage.

Properties:

Name	Type	Required	Value
messageType	string	✅	"BotMessagePlayed"
text	string	✅	text from the SendBotMessage command
groupId	string	✅	groupId from the SendBotMessage command
sequenceNumber	integer	✅	sequenceNumber from the SendBotMessage command

Example:

{
  "messageType": "BotMessagePlayed",
  "text": "Hello customer!",
  "groupId": "5cb7619a-a8e7-468f-ab62-11a797ca3fbd",
  "sequenceNumber": 1
}

Customer Disconnected

CustomerDisconnected is sent when disconnects the call.

Example:

{
  "messageType": "CustomerDisconnected"
}

Commands

Send Bot Message

Use the SendBotMessage command to send messages to the customer in textual format, that will be synthetized into audio. You will receive audio progress in the BotMessagePlayed events.

Properties:

Name	Type	Required	Value
messageType	string	✅	"SendBotMessage"
text	string	✅	Bot message to the customer
groupId	string	✅	You can use the groupId to indicate that the text is just a chunk of a longer complete message
sequenceNumber	integer	✅	In case the group would have more than 1 message, this must be the proper index of the chunk

Example:

{
  "messageType": "SendBotMessage",
  "text": "Hello customer!",
  "groupId": "5cb7619a-a8e7-468f-ab62-11a797ca3fbd",
  "sequenceNumber": 1,
}

End Session

Use the EndSession command to end the conversation with the customer and let workflow to continue. This will also close the WebSocket connection from the client side.

Properties:

Name	Type	Required	Value
messageType	string	✅	"EndSession"
workflowData	object (string key value pairs)	✅	Additional Workflow data from your bot

Example:

{
  "messageType": "EndSession",
  "workflowData": {
    "Your_key": "Your_value"
  }
}