Les WebSockets établissent une connexion continue entre le client et le serveur, permettant une communication bidirectionnelle. Chatwoot 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 Chatwoot, 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 Chatwoot. 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 Chatwoot ?
Pour configurer une connexion WebSocket avec Chatwoot, vous devez initier une connexion avec le jeton d'authentification PubSub fourni par Chatwoot. L'URL pour la connexion est wss://<your-installation-url>/cable. Si vous utilisez Chatwoot 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 Chatwoot, 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 : Chatwoot 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 Chatwoot.
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 Chatwoot ?
Pour se connecter au WebSocket de Chatwoot, 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 à Chatwoot.
// 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 Chatwoot, vous pouvez envoyer un événement de mise à jour de présence à Chatwoot 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 Chatwoot 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