prod - 20261013-083619 - cb7f8b630deb7a27a85ea2f9e79ca9d2dcc1341f

Websocket messages

In this chapter we'll take a look at all possible messages. Both the ones you can send and the ones that may arrive from Seamly.

Outgoing messages

Outgoing messages are messages sent from your implementation to Seamly. For exact specification see the Subscribe schema in the AsyncAPI specification.

Attach Channel

Send to Seamly to attach to the channel of the conversation and start interacting. Must be sent as the first message everything you connect the websocket.

Context

Send context information about the visitor to Seamly. Send any available information right before the StartConversation message, so the conversation can be started with this information in mind. This is required for the  locale  in case you have your bots (and livechat agents) in multiple locales. All other context information can be changed later on.

The information provided in the  environment  and  variables  properties can be used to configure the connection to the services. the currentUrl can for instance be sent to the livechat agents, so they know what page you're currently visiting.

A Context message can be sent at any time and may contain partial updates. If, for example just the currentUrl changes, just send a message with just that information. Seamly will merge the new information into the existing information.

StartConversation

The StartConversation message starts the conversation, meaning it will connect to the configured backend service to kick of the conversation. Only send this message once per conversation, ever.

Message

These outgoing messages are documented in the MessageOutgoing schema of the Async API specification.

Send a message from the visitor to the current bot or livechat agent service. For the best user experience we strongly recommend you to immediately render a text bubble when the user submits a message. Once the message has been successfully sent to the service, a message will be sent back over the websocket. See the MessageIncoming schema. These messages will have the  fromClient  property set to  true  and the  transactionId  will be the same as the  transactionId  you assigned to your message.

Please note that this message is only applicable for text messages as uploaded files are sent using a dedicated Api endpoint. See the  uploads feature  for more information.

Action

A client can perform different actions. Some are relevant for the conversation itself, such as selecting a choice in a choice prompt. And some are informative for livechat agents, such as typing indicators.

Incoming messages

Incoming messages are messages sent from Seamly (so the bot or a livechat agent) to your implementation. For exact specification see the Subscribe schema in the AsyncAPI specification.

AttachChannelResponse

When your AttachMessage message was handled a AttachChannelResponse message will be sent back. It contains a  success  flag indicating whether the channel was successfully attached. And in case an error was raised the error message is returned.

StartConversationResponse

When your StartConversation message was handled a StartConversationResponse message will be sent back. It contains a  success  flag indicating whether the conversation was successfully started. And in case an error was raised the error message is returned.

ServiceAttach

Every time a new service is attached this message is sent. This message contains information about the just attached service, such as whether uploads are allowed.

Error

In case anything went wrong, an error message is sent. The following types of errors can be distinguished:

  • conversation : In case an internal exception occurred or when the conversation somehow ended up in an erroneous state.
  • find_conversation : The conversation could not be found anymore. It probably crashed.
  • frame : The frame you sent over the websocket contains either invalid JSON or contains invalid or missing properties.

Please contact Seamly support in case you encounter any of the first two errors. And in case of the  frame  error, please have a look at the error message to correct the websocket frame payload.

MessageIncoming

Any message of the conversation. Either from the bot/agent to the user ( fromClient  = false), or from the user to the bot/agent ( fromClient  = true). Only a few type of messages are applicable to messages from the user. Cards and Video's for example can only be sent by bots or agents.

Info

Informative messages from the bot / livechat. These messages should be displayed inline in the conversation between the message bubbles.

ServiceData

Additional information related to the conversation. A service data message might for example contain input suggestions for the user. They might be displayed next to the conversation pane to aid the user.

Participant

Every time a new participant enters the conversation. There can only one participant on both sides (either  fromClient  = true for the user's participant, or  fromClient  = false for the bot/agent participant) at any point in time. So when an new participant message arrives it will overwrite the current participant (with the same  fromClient  value). All messages will reference the participant, so you might want to keep track of previous participants so you can still render their names along with their messages.

UI

Messages regarding suggested updates to the user interface. Such as typing indicators of an agent and showing a countdown timer in case the visitor has been idle for too long.