Websocket Events

"Utilize WebSocket events for real-time updates in Bevatel, establishing a persistent connection to receive event-based information."

Use WebSocket events to get real-time updates

WebSockets creates a persistent connection between the client and the server allowing bi-directional communication. Bevatel supports a WebSocket connection to get real-time updates about the events happening on the platform. Any client can connect to the WebSocket URL in Bevatel and authorize themselves by providing the token and start receiving the updates. This guide will help you set up a WebSocket connection with Bevatel and integrate available events.

Note: This is an experimental feature. Documentation can change on every release, and there is no guarantee of backward compatibility. Please make sure that you are using the updated version of the implementation.

Why should I use a WebSocket connection?​

Suppose you are building a client for Bevatel. For example, in An Android or iOS Client SDK, where you would need to listen to the latest messages to update the UI without a reload or An extension to the dashboard, if you want to improve an agent's productivity, you might need data in real-time.

Setup a WebSocket connection with Bevatel​

To set up a WebSocket connection with Bevatel, you need to initiate a connection with the authentication pub-sub token provided by Bevatel. The URL for the connection is wss://<your-installation-url>/cable. E.g.: wss://app.bevatel.com/cable.

There are two types of pub-sub tokens available in Bevatel.

1. User PubSub Token: This token has the privileges of an agent/admin and would receive all of the events documented below. You can get the pub-sub token by calling the Profile API.

2. Contact PubSub Token: For every contact, Bevatel would generate a pub-sub token for every session they had. You can connect to the WebSocket using this token to get the updates of the current session. When you create a contact using the public APIs, you will receive pubsub_token the payload. This token only has access to the current session-related events, you would only receive the events conversation.created, conversation.status_changed, message.created, message.updated, conversation_typing_on, conversation_typing_off and presence.update.

Please refer to Client APIs to build real-time customer-facing integrations using Bevatel.

Note: This token may be rotated regularly based on your installation type, make sure that you are using the latest token.

Connect to Bevatel Websocket​

You need to send a command "subscribe" to connect to Bevatel. It expects a pubSub token, accountId, and userId (if using a user token). Here is an example of how you can connect with Bevatel.

// Add a helper method to convert JSON to a string
const stringify = (payload = {}) => JSON.stringify(payload);

const pubSubToken = "<contact/user-pub-sub-token>";
const accountId = "<your-account-id-in-integer>";
const userId = "<user-id-in-integer-if-using-user-token>";
const connection = new WebSocket(
  "wss://<your-bevatel-installation-host-url>/cable"
);

connection.send(
  stringify({
    command: "subscribe",
    identifier: stringify({
      channel: "RoomChannel",
      pubsub_token: pubSubToken,
      account_id: accountId,
      user_id: userId,
    }),
  })
);

// The expected string in connection.send is of the format:
// {"command":"subscribe","identifier":"{\"channel\":\"RoomChannel\",\"pubsub_token\":\"your-pubsub-token\",\"account_id\": account_id_integer,\"user_id\":user_id_integer }"}

Publishing Presence to the WebSocket server​

To keep your users online in Bevatel, you can send a presence update event to Bevatel every 30 seconds. This action would keep the status of the agent/contact online.

Update the presence of an agent/admin user​

The payload that should be sent to the server for updating the presence of an agent/admin is as follows.

const userPayload = stringify({
  command: "message",
  identifier: stringify({
    channel: "RoomChannel",
    pubsub_token: "<user-pubsub-token>",
    account_id: accountId,
    user_id: userId,
  }),
  data: stringify({ action: "update_presence" }),
});

connection.send(userPayload);
// The expected string in connection.send is of the format:
// {"command":"message","identifier":"{\"channel\":\"RoomChannel\",\"pubsub_token\":\"your-pubsub-token\",\"account_id\": account_id_integer,\"user_id\":user_id_integer ","data":"{\"action\":\"update_presence\"}"}

Update the presence of a contact​

The payload that should be sent to the server for updating the presence of a contact is as follows.

const agentPayload = stringify({
  command: "message",
  identifier: stringify({
    channel: "RoomChannel",
    pubsub_token: "<user-pubsub-token>",
  }),
  data: stringify({ action: "update_presence" }),
});

connection.send(agentPayload);
// The expected string in connection.send is of the format:
// {"command":"message","identifier":"{\"channel\":\"RoomChannel\",\"pubsub_token\":\"your-pubsub-token\","data":"{\"action\":\"update_presence\"}"}

Websocket Payload​

Objects​

An event can contain any of the following objects as a payload. Different types of objects supported in Bevatel are as follows.

Conversation​

The following payload will be returned for a conversation.

{
  "additional_attributes": {
    "browser": {
      "device_name": "string",
      "browser_name": "string",
      "platform_name": "string",
      "browser_version": "string",
      "platform_version": "string"
    },
    "referer": "string",
    "initiated_at": {
      "timestamp": "iso-datetime"
    }
  },
  "can_reply": "boolean",
  "channel": "string",
  "id": "integer",
  "inbox_id": "integer",
  "contact_inbox": {
    "id": "integer",
    "contact_id": "integer",
    "inbox_id": "integer",
    "source_id": "string",
    "created_at": "datetime",
    "updated_at": "datetime",
    "hmac_verified": "boolean"
  },
  "messages": ["Array of message objects"],
  "meta": {
    "sender": {
      // Contact Object
    },
    "assignee": {
      // User Object
    }
  },
  "status": "string",
  "unread_count": "integer",
  "agent_last_seen_at": "unix-timestamp",
  "contact_last_seen_at": "unix-timestamp",
  "timestamp": "unix-timestamp",
  "account_id": "integer"
}

Contact​

The following payload will be returned for a contact.

{
  "additional_attributes": "object",
  "custom_attributes": "object",
  "email": "string",
  "id": "integer",
  "identifier": "string or null",
  "name": "string",
  "phone_number": "string or null",
  "thumbnail": "string"
}

User​

The following payload will be returned for an agent/admin.

{
  "id": "integer",
  "name": "string",
  "available_name": "string",
  "avatar_url": "string",
  "availability_status": "string",
  "thumbnail": "string"
}

Message​

{
  "id": "integer",
  "content": "string",
  "account_id": "integer",
  "inbox_id": "integer",
  "message_type": "integer",
  "created_at": "unix-timestamp",
  "updated_at": "datetime",
  "private": "boolean",
  "status": "string",
  "source_id": "string / null",
  "content_type": "string",
  "content_attributes": "object",
  "sender_type": "string",
  "sender_id": "integer",
  "external_source_ids": "object",
  "sender": {
    "type": "string - contact/user"
    // User or Contact Object
  }
}

Notification​

The following payload will be returned for a notification.

{
  "id": "integer",
  "notification_type": "string",
  "primary_actor_type": "string",
  "primary_actor_id": "integer",
  "primary_actor": {
    "can_reply": "boolean",
    "channel": "string",
    "id": "integer",
    "inbox_id": "integer",
    "meta": {
      "assignee": {
        "id": "integer",
        "name": "string",
        "available_name": "string",
        "avatar_url": "string",
        "type": "user",
        "availability_status": "string",
        "thumbnail": "string"
      },
      "hmac_verified": "boolean"
    },
    "agent_last_seen_at": "unix-timestamp",
    "contact_last_seen_at": "unix-timestamp",
    "timestamp": "unix-timestamp",
  },
  "read_at": "unix-timestamp",
  "secondary_actor": "object/null",
  "created_at":"unix-timestamp",
  "account_id": "integer",
  "push_message_title": "string"
}

Identifier​

Each event will have an identifier attribute which would be of the following format.

{
  "identifier": "{\"channel\":\"RoomChannel\",\"pubsub_token\":\"token\",\"account_id\":id,\"user_id\":user_id}"
}

Message​

Each event will have a message attribute which we return the event name as well as the data associated with it. To see the list of events, see the documentation below.

Events​

conversation.created​

This event is sent when a new conversation is created. For contact pub sub token subscription, it sends only the events related to the session with which the pub-sub token is associated to.

Available to: agent/admin, contact

{
  "message": {
    "event": "conversation.created",
    "data": {
      // Conversation object will be available here
    }
  }
}

conversation.read​

This event is sent to the agents/admins who access to the inbox when a message is read by a contact.

Available to: agent/admin

{
  "message": {
    "event": "conversation.read",
    "data": {
      // Conversation object will be available here
    }
  }
}

message.created​

This event is sent to the agents, admins/contacts when a new message is created in a conversation they have access to.

Available to: agent/admin, contact

{
  "message": {
    "event": "message.created",
    "data": {
      // Message object will be available here
    }
  }
}

message.updated​

This event is sent to the agents, admins/contacts when a message is updated in a conversation they have access to.

Available to: agent/admin, contact

{
  "message": {
    "event": "message.updated",
    "data": {
      // Message object will be available here
    }
  }
}

conversation.status_changed​

This event is sent to the agents, admins/contacts when a conversation status is updated.

Available to: agent/admin, contact

{
  "message": {
    "event": "conversation.status_changed",
    "data": {
      // Conversation object will be available here
    }
  }
}

conversation.typing_on​

This event is sent to the agents, admins/contact when a contact or an agent start typing a response.

Available to: agent/admin, contact

{
  "message": {
    "event": "conversation.typing_on",
    "data": {
      "conversation": {
        // Conversation object will be available here
      },
      "user": {
        // Contact / Agent,Admin User object will be available here.
      },
      "is_private": "boolean", // Shows whether the agent is typing a private note or not.
      "account_id": "integer"
    }
  }
}

conversation.typing_off​

This event is sent to the agents, admins/contacts when a contact or an agent ends up typing a response.

Available to: agent/admin, contact

{
  "message": {
    "event": "conversation.typing_off",
    "data": {
      "conversation": {
        // Conversation object will be available here
      },
      "user": {
        // Contact / User object will be available here.
      },
      "account_id": "integer"
    }
  }
}

assignee.changed​

This event is sent to the agents/admins who have access to the inbox when the assigned is changed.

Available to: agent/admin

{
  "message": {
    "event": "assignee.changed",
    "data": {
      // Conversation object will be available here
    }
  }
}

team.changed​

This event is sent to the agents/admins who have access to the inbox when the team assignment is changed.

Available to: agent/admin

{
  "message": {
    "event": "team.changed",
    "data": {
      // Conversation object will be available here
    }
  }
}

conversation.contact_changed​

This event is sent to the agents/admins when a contact is merged. The conversation object will have the new contact reference.

Available to: agent/admin

{
  "message": {
    "event": "conversation.contact_changed",
    "data": {
      // Conversation object will be available here
    }
  }
}

contact.created​

This event is sent to the agents/admins when a contact is created.

Available to: agent/admin

{
  "message": {
    "event": "contact.created",
    "data": {
      // Contact object will be available here
    }
  }
}

contact.updated​

This event is sent to the agents/admins when a contact is updated.

Available to: agent/admin

{
  "message": {
    "event": "contact.updated",
    "data": {
      // Contact object will be available here
    }
  }
}

presence.update​

This event would be available for both agent and the contact, it returns the availability status of the users in the system. The presence event delivered to contacts won't have information about other contacts.

Available to: agent/admin

{
  "message": {
    "event": "presence.update",
    "data": {
      "account_id": "integer",
      "users": {
        "user-id": "string"
      },
      "contacts": {
        "contact-id": "string"
      }
    }
  }
}

notification_created​

Available to: agent/admin

{
  "message": {
    "event": "string",
    "data": {
      "notification":{
        // Notification object will be available here
      },
      "unread_count": "integer",
      "count": "integer",
    }
  }
}