Um ein API-Channel-Postfach in Chatwoot-Installationen zu erstellen und zu konfigurieren, befolgen Sie die nachfolgend beschriebenen Schritte.
API-Kanal einrichten
Schritt 1. Gehen Sie zu Einstellungen → Postfächer → „Postfach hinzufügen“.
Schritt 2. Klicken Sie auf das "API"-Symbol.
Schritt 3. Geben Sie einen Namen für den Channel und eine Callback-URL an. Hier ein Beispiel:
Schritt 4. „Agenten hinzufügen“ zu Ihrem API-Postfach.
Die Einrichtung des Postfachs ist abgeschlossen.
Nachrichten an den API-Kanal senden
Um Nachrichten an den API-Kanal zu senden, stellen Sie sicher, dass Sie die folgenden Modelle und die Nomenklatur verstehen, die in Chatwoot verwendet werden.
-
Channel: Ein Channel definiert den Typ der Quelle der Konversationen. Zum Beispiel Facebook, Twitter, API usw.
-
Postfach: Sie können mehrere Quellen für Konversationen desselben Channel-Typs erstellen. Beispielsweise können Sie mehr als eine Facebook-Seite mit einem Chatwoot-Konto verbinden. Jede Seite wird in Chatwoot als Postfach bezeichnet.
-
Konversation: Eine Konversation ist eine Sammlung von Nachrichten.
-
Kontakt: Jeder Konversation ist eine reale Person zugeordnet, genannt Kontakt.
-
Kontakt-Postfächer: Dies ist die Sitzung jedes Kontakts in einem Postfach. Ein Kontakt kann mehrere Sitzungen und mehrere Konversationen im selben Postfach haben.
Wie sende ich eine Nachricht in einem API-Kanal?
Um eine Nachricht in einem API-Kanal zu senden, erstellen Sie einen Kontakt, starten eine Konversation und senden schließlich die Nachricht.
APIs erfordern das api_access_token im Request-Header. Sie können diesen Token in Ihren Profileinstellungen → Access Token einsehen.
1. Kontakt erstellen
Ref: API-Dokumentation
Übergeben Sie die Postfach-ID des API-Kanals zusammen mit den anderen angegebenen Parametern. Dadurch wird automatisch eine Sitzung für Sie erstellt. Eine Beispielantwort sieht wie unten aus.
{
"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"
}
Wie Sie in der Antwort sehen können, sehen Sie die contact_inboxes und jeder contact_inbox hat eine source_id. Die Source ID kann als Sitzungskennung angesehen werden. Sie werden diese source_id verwenden, um eine neue Konversation zu erstellen wie unten beschrieben.
2. Konversation erstellen
Ref: API-Dokumentation
Verwenden Sie die source_id aus dem vorherigen API-Aufruf. Sie erhalten eine Konversations-ID, die verwendet werden kann, um eine Nachricht zu erstellen.
{
"id": 0
}
3. Neue Nachricht erstellen
Ref: API-Dokumentation
Es gibt 2 Nachrichtentypen.
-
Eingehend: Nachrichten, die vom Endnutzer gesendet werden, gelten als eingehende Nachrichten.
-
Ausgehend: Nachrichten, die vom Agenten gesendet werden, gelten als ausgehende Nachrichten.
Wenn Sie die API mit dem korrekten Inhalt aufrufen, erhalten Sie eine Antwort wie diese:
{
"id": 0,
"content": "Dies ist eine eingehende Nachricht vom API-Kanal",
"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"
}
}
Wenn alles erfolgreich ist, sehen Sie die Konversation im Dashboard wie folgt.
Sie werden benachrichtigt, wenn eine neue Nachricht auf der beim Erstellen des API-Kanals angegebenen URL erstellt wird. Sie können mehr über die Nachrichten-Nutzlast hier lesen.
Nachrichten über Callback-URL empfangen
Wenn eine neue Nachricht im API-Kanal erstellt wird, erhalten Sie einen POST-Request an die beim Erstellen des API-Kanals angegebene Callback-URL. Die Nutzlast sieht so aus.
Eine vollständige Liste der vom Webhook unterstützten Events finden Sie hier.
Event-Typ: message_created
{
"id": 0,
"content": "Dies ist eine eingehende Nachricht vom API-Kanal",
"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"
}
Schnittstellen mit Client-APIs erstellen
Die verfügbaren Client-APIs für den API-Kanal helfen Ihnen dabei, kundenorientierte Schnittstellen für Chatwoot zu erstellen.
Diese APIs sind nützlich für folgende Anwendungsfälle:
-
Verwenden Sie eine eigene Chat-Oberfläche anstelle des Chatwoot-Chat-Widgets.
-
Bauen Sie Konversationsschnittstellen in Ihre mobilen Apps ein.
-
Fügen Sie Chatwoot zu anderen Plattformen hinzu, für die Chatwoot kein offizielles SDK hat.
Kundenobjekte erstellen
Sie können Kunden-Datenobjekte mit Hilfe des inbox_identifier und customer_identifier erstellen und abrufen.
Inbox Identifier
Sie erhalten den inbox_identifier in Ihrem API-Kanal → Einstellungen → Konfiguration.
Customer Identifier
Der customer_identifier oder die source_id wird beim Erstellen des Kunden über die create API bereitgestellt. Sie müssen diesen Bezeichner clientseitig speichern, um im Auftrag des Kunden weitere Anfragen stellen zu können. Dies kann z.B. in Cookies, lokalem Speicher usw. erfolgen.
Verfügbare APIs
Die verfügbaren Client-APIs sind hier dokumentiert. Mit den APIs können Sie folgendes tun:
-
Kontakt erstellen, anzeigen und aktualisieren
-
Konversationen erstellen und auflisten
-
Nachrichten erstellen, auflisten und aktualisieren
HMAC-Authentifizierung
Die Client-APIs unterstützen auch die HMAC-Authentifizierung. Das HMAC-Token für den Channel kann durch Ausführen des folgenden Befehls in Ihrer Rails-Konsole abgerufen werden.
# Ersetzen Sie api_inbox_id durch Ihre Postfach-ID
Inbox.find(api_inbox_id).channel.hmac_token
Verbindung zu Chatwoot WebSockets
Um Echtzeit-Updates aus dem Agenten-Dashboard zu erhalten, verbinden Sie sich mit Chatwoot WebSockets über folgende URL.
<your installation url>/cable
WebSocket-Verbindung authentifizieren
Nachdem Sie sich mit dem pubsub_token des Kunden angemeldet haben, erhalten Sie Ereignisse, die auf Ihr Kundenobjekt ausgerichtet sind. Das pubsub_token wird beim API-Aufruf zur Kundenanlage bereitgestellt.
Beispiel
const connection = new WebSocket('ws://localhost:3000/cable');
connection.send(JSON.stringify({ command:"subscribe", identifier: "{\\"channel\\":\\"RoomChannel\\",\\"pubsub_token\\":\\""+ customer_pubsub_token+"\\"}" }));
Eine vollständige Liste der von WebSockets unterstützten Events finden Sie hier.
Webhook-Verifizierung
Sobald Sie einen API-Kanal erstellen, generieren wir automatisch ein Secret, mit dem Sie die von Ihrer Anwendung empfangene Nutzlast verifizieren können. Mehr über die Webhook-Verifizierung erfahren Sie hier.
Umsetzung
Hier ist ein Beispiel für eine Chat-Oberfläche, die auf den Client-APIs basiert.