Pour créer et configurer une boîte de réception du canal API dans les installations Chatwoot, suivez l'étape décrite ci-dessous.
Configurer le canal API
Étape 1. Allez dans Paramètres → Boîtes de réception → « Ajouter une boîte de réception ».
Étape 2. Cliquez sur l'icône "API".
Étape 3. Indiquez un nom pour le canal et une URL de callback. Voici un exemple :
Étape 4. « Ajouter des agents » à votre boîte de réception API.
La configuration de la boîte de réception est terminée.
Envoyer des messages vers le canal API
Pour envoyer des messages vers le canal API, assurez-vous de comprendre les modèles suivants ainsi que la nomenclature utilisée dans Chatwoot.
-
Canal : Le canal définit le type de source des conversations. Par exemple, Facebook, Twitter, API, etc.
-
Boîte de réception : Vous pouvez créer plusieurs sources de conversations du même type de canal. Par exemple, vous pouvez avoir plus d'une page Facebook connectée à un compte Chatwoot. Chaque page est appelée boîte de réception dans Chatwoot.
-
Conversation : Une conversation est un ensemble de messages.
-
Contact : Chaque conversation est associée à une personne réelle, appelée contact.
-
Contacts Boîtes de réception : Ceci correspond à la session de chaque contact dans une boîte de réception. Un contact peut avoir plusieurs sessions et plusieurs conversations dans la même boîte de réception.
Comment envoyer un message dans un canal API ?
Pour envoyer un message dans un canal API, créez un contact, initiez une conversation, puis envoyez le message.
Les API nécessitent le api_access_token dans l'en-tête de la requête. Vous pouvez obtenir ce jeton en visitant vos paramètres de Profil → Jeton d'accès.
1. Créer un contact
Réf : Documentation de l'API
Transmettez l’ID de la boîte de réception du canal API avec les autres paramètres spécifiés. Cela créera automatiquement une session pour vous. Une réponse exemple ressemblera à celle ci-dessous.
{
"email": "string",
"name": "string",
"phone_number": "string",
"thumbnail": "string",
"additional_attributes": {},
"contact_inboxes": [
{
"source_id": "string",
"inbox": {
"id": 0,
"name": "string",
"website_url": "string",
"channel_type": "string",
"avatar_url": "string",
"widget_color": "string",
"website_token": "string",
"enable_auto_assignment": true,
"web_widget_script": "string",
"welcome_title": "string",
"welcome_tagline": "string",
"greeting_enabled": true,
"greeting_message": "string"
}
}
],
"id": 0,
"availability_status": "string"
}
Comme vous pouvez le voir dans la charge utile, vous pouvez voir les contact_inboxes et chaque contact_inbox aura un source_id. Le Source ID peut être considéré comme l'identifiant de session. Vous utiliserez ce source_id pour créer une nouvelle conversation comme défini ci-dessous.
2. Créer une conversation
Réf : Documentation de l'API
Utilisez le source_id reçu lors de l'appel API précédent. Vous recevrez un ID de conversation qui pourra être utilisé pour créer un message.
{
"id": 0
}
3. Créer un nouveau message
Réf : Documentation de l'API
Il existe 2 types de messages.
-
Entrant : Les messages envoyés par l'utilisateur final sont classés comme messages entrants.
-
Sortant : Les messages envoyés par l'agent sont classés comme messages sortants.
Si vous appelez l'API avec le contenu correct, vous recevrez une charge utile similaire à celle-ci :
{
"id": 0,
"content": "Ceci est un message entrant via le canal API",
"inbox_id": 0,
"conversation_id": 0,
"message_type": 0,
"content_type": null,
"content_attributes": {},
"created_at": 0,
"private": false,
"sender": {
"id": 0,
"name": "Pranav",
"type": "contact"
}
}
Si tout fonctionne, vous verrez la conversation sur le tableau de bord comme suit.
Vous serez notifié lorsqu'un nouveau message est créé sur l'URL indiquée lors de la création du canal API. Vous pouvez en savoir plus sur la charge utile du message ici.
Recevoir des messages via l’URL de callback
Lorsqu’un nouveau message est créé dans le canal API, vous recevrez une requête POST à l’URL de callback mentionnée lors de la création du canal API. La charge utile ressemblera à ceci.
Trouvez la liste complète des événements pris en charge par le webhook ici.
Type d'événement : message_created
{
"id": 0,
"content": "Ceci est un message entrant via le canal API",
"created_at": "2020-08-30T15:43:04.000Z",
"message_type": "incoming",
"content_type": null,
"content_attributes": {},
"source_id": null,
"sender": {
"id": 0,
"name": "contact-name",
"avatar": "",
"type": "contact"
},
"inbox": {
"id": 0,
"name": "API Channel"
},
"conversation": {
"additional_attributes": null,
"channel": "Channel::Api",
"id": 0,
"inbox_id": 0,
"status": "open",
"agent_last_seen_at": 0,
"contact_last_seen_at": 0,
"timestamp": 0
},
"account": {
"id": 1,
"name": "API testing"
},
"event": "message_created"
}
Créer des interfaces avec les API client
Les API client disponibles pour le canal API vous aideront à construire des interfaces destinées aux clients pour Chatwoot.
Ces API sont utiles dans des cas comme ceux listés ci-dessous.
-
Utiliser une interface de chat personnalisée au lieu du widget de chat Chatwoot.
-
Intégrer des interfaces conversationnelles à vos applications mobiles.
-
Ajouter Chatwoot à d’autres plateformes pour lesquelles Chatwoot ne propose pas de SDK officiel.
Création d’objets client
Vous pouvez créer et récupérer des objets de données client en utilisant l’inbox_identifier et le customer_identifier.
Identifiant de la boîte de réception
Vous pouvez obtenir l’inbox_identifier depuis votre canal API -> Paramètres -> Configuration.
Identifiant client
Le customer_identifier ou source_id peut être obtenu lors de la création du client via l’API create. Vous devrez stocker cet identifiant côté client pour effectuer d’autres requêtes au nom du client. Cela peut être fait dans des cookies, le stockage local, etc.
APIs disponibles
Les API client disponibles sont documentées ici. Voici quelques actions possibles avec ces API :
-
Créer, consulter et mettre à jour un Contact
-
Créer et lister des Conversations
-
Créer, lister et mettre à jour des Messages
Authentification HMAC
Les API client prennent également en charge l’authentification HMAC. Le jeton HMAC pour le canal peut être obtenu en exécutant la commande suivante dans votre console rails.
# remplacez api_inbox_id par l'id de votre boîte de réception
Inbox.find(api_inbox_id).channel.hmac_token
Connexion aux WebSockets de Chatwoot
Pour recevoir des mises à jour en temps réel depuis le tableau de bord agent, connectez-vous aux WebSockets de Chatwoot en utilisant l’URL suivante.
<your installation url>/cable
Authentifier votre connexion WebSocket
Après avoir souscrit via le pubsub_token du client, vous recevrez des événements adressés à votre objet client. Le pubsub_token est fourni lors de l'appel API de création du client.
Exemple
const connection = new WebSocket('ws://localhost:3000/cable');
connection.send(JSON.stringify({ command:"subscribe", identifier: "{\\"channel\\":\\"RoomChannel\\",\\"pubsub_token\\":\\""+ customer_pubsub_token+"\\"}" }));
Retrouvez la liste complète des événements pris en charge par WebSockets ici.
Vérification des Webhooks
Une fois que vous avez créé un canal API, un secret est automatiquement généré que vous pouvez utiliser pour vérifier les charges utiles que votre application reçoit. Vous pouvez en savoir plus sur la vérification des webhooks ici.
Implémentation
Voici un exemple d’interface de chat construite par-dessus les API client.