WebSocket

Overview

The Engagement API utilizes WebSockets to create a bidirectional communication channel between the user's browser and the server. WebSockets enable sending messages to the server and receiving event-driven responses without the need for polling the server for a reply.

Steps

1. Create a user: Before establishing a WebSocket connection, make sure to create a user using the appropriate API method.
2. Establish a WebSocket connection: After the user has been created, establish a WebSocket connection as demonstrated in the example below.
3. Join the chat channel: Use the join function of the Elixir/Channels library (e.g., Phoenix Channels JavaScript client) to join the chat channel chat:{CHAT_ID}. This step is necessary to receive messages from Pypestream and to send and receive heartbeat protocol messages, which maintain the connection. Join the chat channel before starting the engagement to ensure receipt of initial messages from the microapp.
4. Wait for the chat:ready event: After sending the request to start the engagement, wait for the chat:ready event to be received via WebSocket. This event signifies that it is safe to proceed with using other endpoints, such as sending messages. If a request is sent before receiving the chat:ready event, the API will return a 428 error.
5. Receive responses: When a response arrives, the incoming:msg event will be received through the WebSocket, allowing further processing or interaction.

URLs

Connection Variables

To establish a sample WebSocket connection, you will need the following variables:

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

To join a channel, use the .join() function. Make sure to include the topic (see the definition of "topic" below) you're connecting to and the authorization information for that channel.

📘

What is a topic?

A topic represents a chat. It is always a string in the format chat:{ChatID}, such as "chat:42c6a240-1bf9-4164-8d75-9a608f1117c9". Before sending or receiving any messages, join the "topic" using the join function from the library you're using.

After connecting to the WebSocket with the Phoenix Channels JavaScript client, establish a connection on the channel variable. This step would appear as follows:

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.

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:

incoming:notice

The incoming:notice 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 of how to push events to the channel and listen for 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: