跳到主要内容

使用 WebSocket 事件获取实时更新

WebSocket 创建了客户端和服务器之间的持久连接，允许双向通信。Voxsig 支持 WebSocket 连接以获取有关平台上发生的事件的实时更新。任何客户端都可以连接到 Voxsig 的 WebSocket URL，通过提供令牌进行授权，并开始接收更新。本指南将帮助您在 Voxsig 上创建 WebSocket 连接并集成可用的事件。

注意： 这是一个实验性功能。文档可能会在每个版本中更改，并且不保证向后兼容性。请确保您使用的是最新版本的实现。

信息

假如你无法阅读下方的内容，那么请不要尝试使用此功能，请联系我们取得帮助。

Why should I use a websocket connection?​

Suppose you are building a client for Voxsig. 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 Voxsig​

To set up a websocket connection with Voxsig, you need to initiate a connection with the authentication pubsub token provided by Voxsig. The URL for the connection is wss://app.voxsig.com/cable.

Connect to Voxsig Websocket​

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

// 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://app.voxsig.com/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 Voxsig, you can send a presence update event to Voxsig 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 type of objects supported in Voxsig 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 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 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/contact 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/contact 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/contact 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/contact 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 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",
    }
  }
}