Skip to main content

Use WebSocket Events to Get Real-Time Updates

WebSockets create a persistent connection between the client and the server allowing bi-directional communication. Hoory 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 Hoory and authorize themselves by providing the token and start receiving the updates. This guide will help you set up a WebSocket connection with Hoory 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 Hoory. 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 Hoory​

To set up a webocket connection with Hoory, you need to initiate a connection with the authentication pubsub token provided by Hoory. The URL for the connection is wss://<your-installation-url>/cable. E.g.: wss://app.hoory.com/cable.

There are two types of pubsub tokens available in Hoory.

  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 pubsub token by calling the Profile API.

  2. Contact PubSub Token: For every contact, Hoory would generate a pubsub 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 the pubsub_token in 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 Client APIs to build real time customer facing integrations using Hoory.

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

Connect to Hoory WebSocket​

You need to send a command "subscribe" to connect to Hoory. It expects a pubSub token, account ID and user ID (if using a user token). Here is an example on how you can connect with Hoory.

// 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-Hoory-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 Hoory, you can send a presence update event to Hoory every 30 seconds. This action would keep the status of the agent/contact to online.

Update 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 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 Hoory 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 will 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 pubsub token subscription, it sends only the events related to the session which pubsub 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 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/contacts when a contact or an agent starts 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 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. 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 the 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",
    }
  }
}
Last updated on by tajpouria