Les WebSockets établissent une connexion continue entre le client et le serveur, permettant une communication bidirectionnelle. Super Chat utilise cette connexion pour fournir des mises à jour en temps réel concernant les événements de la plateforme. Pour se connecter au WebSocket de Super Chat, il suffit de fournir un jeton et de suivre les instructions d'installation décrites dans ce guide.
Remarque : Cette fonctionnalité est expérimentale, et la documentation peut évoluer à chaque version. De plus, la rétrocompatibilité ne peut pas être garantie, il est donc important de s'assurer d'utiliser la dernière version de l'implémentation.
Pourquoi utiliser une connexion WebSocket ?
Une connexion WebSocket permet la mise à jour des données en temps réel, ce qui la rend idéale pour les clients comme un SDK client Android ou iOS pour Super Chat. Cela permet de mettre à jour le tableau de bord sans avoir besoin de recharger la page. Ainsi, l'expérience utilisateur est améliorée et la productivité de l'agent est renforcée.
Comment configurer une connexion WebSocket avec Super Chat ?
Pour configurer une connexion WebSocket avec Super Chat, vous devez initier une connexion avec le jeton d'authentification PubSub fourni par Super Chat. L'URL pour la connexion est wss://<your-installation-url>/cable. Si vous utilisez Super Chat Cloud, vous pouvez utiliser wss://app.chatwoot.com/cable comme URL.
Un jeton PubSub est un jeton utilisé pour authentifier un client lors de la connexion à un service PubSub (publish-subscribe). Le client doit présenter ce jeton au service afin d'établir une connexion et de commencer à publier ou s'abonner à des messages.
Il existe deux types de jetons PubSub disponibles sur Super Chat, listés ci-dessous.
-
Jeton PubSub Utilisateur : Ce jeton possède les privilèges d'un agent/admin et recevra tous les événements listés plus bas sur cette page. Vous pouvez obtenir le jeton PubSub en appelant l'API Profil.
-
Jeton PubSub Contact : Super Chat génère un jeton PubSub unique pour chaque session d'un contact. Ce jeton peut être utilisé pour se connecter au WebSocket et recevoir les mises à jour en temps réel pour la même session. Lorsqu'un contact est créé via les API publiques, le
pubsub_tokenest inclus dans la réponse. Ce jeton n'accorde l'accès qu'aux événements relatifs à la session en cours, commeconversation.created,conversation.status_changed,message.created,message.updated,conversation_typing_on,conversation_typing_offetpresence.update.
Veuillez consulter les API Client pour construire des intégrations orientées client en temps réel à l'aide de Super Chat.
Remarque : Ce jeton peut être régulièrement renouvelé selon votre type d'installation. Veillez à utiliser le jeton le plus récent.
Comment se connecter au WebSocket de Super Chat ?
Pour se connecter au WebSocket de Super Chat, utilisez la commande subscribe et incluez votre pubSubToken, accountId et userId (si vous utilisez un jeton utilisateur) dans la requête de connexion. Voici un exemple de la manière de se connecter à Super Chat.
// Ajoutez une méthode utilitaire pour convertir un objet JSON en 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.chatwoot.com/cable"
);
connection.send(
stringify({
command: "subscribe",
identifier: stringify({
channel: "RoomChannel",
pubsub_token: pubSubToken,
account_id: accountId,
user_id: userId,
}),
})
);
// La chaîne attendue dans connection.send est du format :
// {"command":"subscribe","identifier":"{\\"channel\\":\\"RoomChannel\\",\\"pubsub_token\\":\\"your-pubsub-token\\",\\"account_id\\": account_id_integer,\\"user_id\\":user_id_integer }"}
Publier la présence au serveur WebSocket
Pour garder le statut de vos utilisateurs connectés sur Super Chat, vous pouvez envoyer un événement de mise à jour de présence à Super Chat toutes les 30 secondes. Cette action maintiendra le statut en ligne de l'agent/contact.
Comment mettre à jour la présence d'un agent/admin ?
Pour mettre à jour la présence d'un agent ou d'un administrateur, envoyez la charge utile suivante au serveur :
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);
// La chaîne attendue dans connection.send est du 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\\"}"}
Comment mettre à jour la présence d'un contact ?
Pour mettre à jour la présence d'un contact, envoyez la charge utile suivante au serveur :
const agentPayload = stringify({
command: "message",
identifier: stringify({
channel: "RoomChannel",
pubsub_token: "<user-pubsub-token>",
}),
data: stringify({ action: "update_presence" }),
});
connection.send(agentPayload);
// La chaîne attendue dans connection.send est du format :
// {"command":"message","identifier":"{\\"channel\\":\\"RoomChannel\\",\\"pubsub_token\\":\\"your-pubsub-token\\","data":"{\\"action\\":\\"update_presence\\"}"}
Charge utile WebSocket
Objets
Un événement peut contenir l'un des objets suivants comme charge utile. Les différents types d'objets pris en charge dans Super Chat sont les suivants.
Conversation
La charge utile suivante sera retournée pour une 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": {
// Objet Contact
},
"assignee": {
// Objet Utilisateur
}
},
"status": "string",
"unread_count": "integer",
"agent_last_seen_at": "unix-timestamp",
"contact_last_seen_at": "unix-timestamp",
"timestamp": "unix-timestamp",
"account_id": "integer"
}
Contact
La charge utile suivante sera retournée pour un contact.
{
"additional_attributes": "object",
"custom_attributes": "object",
"email": "string",
"id": "integer",
"identifier": "string or null",
"name": "string",
"phone_number": "string or null",
"thumbnail": "string"
}
Utilisateur
La charge utile suivante sera retournée pour un agent/admin.
{
"id": "integer",
"name": "string",
"available_name": "string",
"avatar_url": "string",
"availability_status": "string",
"thumbnail": "string"
}
Message
La charge utile suivante sera retournée pour un 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"
// Objet Utilisateur ou Contact
}
}
Notification
La charge utile suivante sera retournée pour une 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"
}
Identifiant
Chaque événement comportera un attribut identifier au format suivant.
{
"identifier": "{\\"channel\\":\\"RoomChannel\\",\\"pubsub_token\\":\\"token\\",\\"account_id\\":id,\\"user_id\\":user_id}"
}
Message
Chaque événement inclura un attribut message où nous renvoyons le nom de l'événement ainsi que les données qui lui sont associées. Pour voir la liste des événements, consultez la documentation ci-dessous.
Types d'événements
conversation.created
Cet événement est déclenché lorsqu'une nouvelle conversation est initiée. Si vous vous abonnez au jeton PubSub du contact, cet événement n'inclura que les données relatives à la session spécifique associée au jeton PubSub.
Disponible pour : agent/admin, contact
{
"message": {
"event": "conversation.created",
"data": {
// Objet Conversation disponible ici
}
}
}
conversation.read
Cet événement est déclenché et envoyé aux agents/admins ayant accès à la messagerie lorsqu'un contact a lu un message.
Disponible pour : agent/admin
{
"message": {
"event": "conversation.read",
"data": {
// Objet Conversation disponible ici
}
}
}
message.created
Cet événement est déclenché et envoyé aux agents, administrateurs, contacts lorsqu'un nouveau message est créé dans une conversation à laquelle ils ont accès.
Disponible pour : agent/admin, contact
{
"message": {
"event": "message.created",
"data": {
// Objet Message disponible ici
}
}
}
message.updated
Cet événement est déclenché et envoyé aux agents, administrateurs, contacts lorsqu'un message est mis à jour dans une conversation à laquelle ils ont accès.
Disponible pour : agent/admin, contact
{
"message": {
"event": "message.updated",
"data": {
// Objet Message disponible ici
}
}
}
conversation.status_changed
Cet événement est envoyé aux agents, administrateurs, contacts lorsqu'un statut de conversation est mis à jour.
Disponible pour : agent/admin, contact
{
"message": {
"event": "conversation.status_changed",
"data": {
// Objet Conversation disponible ici
}
}
}
conversation.typing_on
Cet événement est envoyé aux agents, administrateurs, contacts lorsqu'un contact ou un agent commence à rédiger une réponse.
Disponible pour : agent/admin, contact
{
"message": {
"event": "conversation.typing_on",
"data": {
"conversation": {
// Objet Conversation disponible ici
},
"user": {
// Objet Utilisateur Contact / Agent, Administrateur disponible ici
},
"is_private": "boolean", // Indique si l'agent tape une note privée ou non.
"account_id": "integer"
}
}
}
conversation.typing_off
Cet événement est envoyé aux agents, administrateurs, contacts lorsqu'un contact ou un agent arrête de rédiger une réponse.
Disponible pour : agent/admin, contact
{
"message": {
"event": "conversation.typing_off",
"data": {
"conversation": {
// Objet Conversation disponible ici
},
"user": {
// Objet Utilisateur / Contact disponible ici
},
"account_id": "integer"
}
}
}
assignee.changed
Cet événement est envoyé aux agents/administrateurs ayant accès à une messagerie lorsqu'un agent assigné est modifié.
Disponible pour : agent/admin
{
"message": {
"event": "assignee.changed",
"data": {
// Objet Conversation disponible ici
}
}
}
team.changed
Cet événement est envoyé aux agents/administrateurs ayant accès à une messagerie lorsqu'une équipe assignée est modifiée.
Disponible pour : agent/admin
{
"message": {
"event": "team.changed",
"data": {
// Objet Conversation disponible ici
}
}
}
conversation.contact_changed
Cet événement est envoyé aux agents/administrateurs lorsqu'une fusion de contacts regroupe toutes leurs conversations sous un seul contact.
Disponible pour : agent/admin
{
"message": {
"event": "conversation.contact_changed",
"data": {
// Objet Conversation disponible ici
}
}
}
contact.created
Cet événement est envoyé aux agents/administrateurs lorsqu'un contact est créé.
Disponible pour : agent/admin
{
"message": {
"event": "contact.created",
"data": {
// Objet Contact disponible ici
}
}
}
contact.updated
Cet événement est envoyé aux agents/administrateurs lorsqu'un contact est mis à jour.
Disponible pour : agent/admin
{
"message": {
"event": "contact.updated",
"data": {
// Objet Contact disponible ici
}
}
}
presence.update
Disponible à la fois pour l'agent et le contact, cet événement fournit des mises à jour en temps réel sur le statut de disponibilité des utilisateurs dans le système. L'événement transmis aux contacts n'inclura pas les informations de disponibilité des autres contacts.
Disponible pour : agent/admin
{
"message": {
"event": "presence.update",
"data": {
"account_id": "integer",
"users": {
"user-id": "string"
},
"contacts": {
"contact-id": "string"
}
}
}
}
notification_created
Cet événement est envoyé aux agents/administrateurs lorsqu'une notification est créée.
Disponible pour : agent/admin