WebSocket

Overview

The Engagement API uses WebSockets to open a two-way interactive communication session between the user's browser and a server. With a WebSocket, you can send messages to a server and receive event-driven responses without having to poll the server for a reply.

Steps

After creating a user, you will need to establish a WebSocket connection.

Once the WebSocket connection is established, join the chat channel chat:{CHAT_ID} by using the join function of the Elixir/Channels library (see an example Phoenix Channels JavaScript client) in order to receive messages from Pypestream and to send and receive the heartbeat protocol messages to keep the connection established. Join the chat channel before you start the engagement, otherwise, you will not receive the initial messages from the microapp you are interacting with.

After you send the request to start the engagement, you need to wait until you receive the chat:ready event through the Websocket. This will indicate that you can proceed and use the other endpoints such as sending a message. If a request is sent before receiving the chat:ready event, the API will return an error 428.

When receiving a response, the event incoming:msg will received in the WebSocket.

URLs

Connection Variables

A sample WebSocket connection requires the following variables are included in the request:

For example, a Websocket connection using the Phoenix Channels JavaScript client would look like this, where MY_TOKEN is the token retrieved through the Create User:

let socket = new Socket("wss://{URL}/socket/websocket", {params: {token: {MY_TOKEN}}})
socket.connect()

Joining a Channel

In order to join a channel, use the join function including the topic you're connecting to and the authorization information for that channel. Once connected to the WebSocket using the Phoenix Channels JavaScript client and establishing a connection on the channel variable, this step would look like this:

let channel = socket.channel("chat:{ChatID}", {user_id: "{UserID}", access_token: "{AccessToken}"})
channel.join()
  .receive("ok", ({messages}) => {YourSuccessFunction} )
  .receive("error", ({reason}) => {YourFailureFunction} )
  .receive("timeout", () => {YourTimeoutFunction})

Replace the {ChatID}, {UserID} and {AccessToken} with their respective value.

📘

What is a topic?

A topic is the representation of the chat. The topic will always be a string in the following form "chat:{ChatID}", for example "chat:42c6a240-1bf9-4164-8d75-9a608f1117c9". Before sending or receiving any messages, we join the "topic" by using the join function from the library you're using.

Events

The following messages can be sent through the WebSocket connection:

chat:start

The chat:start message payload has the following fields:

chat:ready

The chat:ready message payload has the following fields:

new:ping

The new:ping message payload has the following fields:

new:pong

The new:pong message payload has the following fields:

msg:send

The msg:send message payload has the following variables:

incoming:msg

The incoming:msg message payload has the following variables:

chat:end

The chat:end message payload has the following variables:

chat:snapshot

The chat:snapshot message payload has the following variables:

chat:snapshot_response

The chat:snapshot_response message payload has the following variables:

Example

Here is an example to push events to the channel and listen to events. In the following example, the channel is set up to listen for the "new_msg" event and send the "new_msg" event back to the Websocket.

Please see the Phoenix Channels JavaScript client documentation

let channel = socket.channel("room:123", {token: roomToken})
channel.on("new_msg", msg => console.log("Got message", msg) )
$input.onEnter( e => {
  channel.push("new_msg", {body: e.target.val}, 10000)
    .receive("ok", (msg) => console.log("created message", msg) )
    .receive("error", (reasons) => console.log("create failed", reasons) )
    .receive("timeout", () => console.log("Networking issue...") )
})

channel.join()
  .receive("ok", ({messages}) => console.log("catching up", messages) )
  .receive("error", ({reason}) => console.log("failed join", reason) )
  .receive("timeout", () => console.log("Networking issue. Still waiting..."))

Status Codes

The following are the possible response codes based on the requests: