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“. ![](https://app.chatwoot.com/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBBMGFsVHc9PSIsImV4cCI6bnVsbCwicHVyIjoiYmxvYl9pZCJ9fQ==--32734baff90933097fa9e1d5d2cb9c0a824de9ed/adding%20an%20inbox%20in%20chatwoot.png) **Schritt 2.** Klicken Sie auf das "API"-Symbol. ![](https://app.chatwoot.com/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBBMWlsVHc9PSIsImV4cCI6bnVsbCwicHVyIjoiYmxvYl9pZCJ9fQ==--cf2f9535e7e9e5feb146122da5bd42ce5e5e151b/api%20channel%20inbox%20in%20chatwoot.png) **Schritt 3.** Geben Sie einen Namen für den Channel und eine Callback-URL an. Hier ein Beispiel: ![](https://app.chatwoot.com/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBBMXFsVHc9PSIsImV4cCI6bnVsbCwicHVyIjoiYmxvYl9pZCJ9fQ==--4d27a3aa27c07d14a098f148fdf5fb15d6ff06b6/api%20channel%20settings.png) **Schritt 4**. „Agenten hinzufügen“ zu Ihrem API-Postfach. ![](https://app.chatwoot.com/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBBMDJsVHc9PSIsImV4cCI6bnVsbCwicHVyIjoiYmxvYl9pZCJ9fQ==--d7190cf613e5630ab61790dbaf922bf1005e7c6a/adding%20agents%20to%20a%20chatwoot%20inbox.png) 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](https://www.chatwoot.com/hc/user-guide/articles/1784681471-chatwoot_glossar) verstehen, die in Chatwoot verwendet werden. 1. **Channel**: Ein Channel definiert den Typ der Quelle der Konversationen. Zum Beispiel Facebook, Twitter, API usw. 2. **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. 3. **Konversation**: Eine Konversation ist eine Sammlung von Nachrichten. 4. **Kontakt**: Jeder Konversation ist eine reale Person zugeordnet, genannt Kontakt. 5. **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](https://www.chatwoot.com/developers/api/#operation/contactCreate) Ü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](https://www.chatwoot.com/developers/api/#operation/newConversation) 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](https://www.chatwoot.com/developers/api/#operation/create-a-new-message-in-a-conversation) Es gibt 2 Nachrichtentypen. 1. **Eingehend**: Nachrichten, die vom Endnutzer gesendet werden, gelten als eingehende Nachrichten. 2. **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. ![](https://app.chatwoot.com/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBBMktsVHc9PSIsImV4cCI6bnVsbCwicHVyIjoiYmxvYl9pZCJ9fQ==--110186260cba7057ce9b0cbb48ec5b45c12e8875/api%20inbox.png) 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](https://www.chatwoot.com/hc/user-guide/articles/1784681463-wie-erstellt-man-einen-api_kanaleingang) 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](https://www.chatwoot.com/hc/user-guide/articles/1784681468-wie-verwendet-man-webhooks). **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: 1. Verwenden Sie eine eigene Chat-Oberfläche anstelle des Chatwoot-Chat-Widgets. 2. Bauen Sie Konversationsschnittstellen in Ihre mobilen Apps ein. 3. 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](https://www.chatwoot.com/developers/api#operation/create-a-contact) 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](https://www.chatwoot.com/developers/api#tag/Contacts-API) 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](https://www.chatwoot.com/hc/user-guide/articles/1784681452-wie-aktiviert-man-die-identitatsuberprufung-in-chatwoot). 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. ``` /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](https://www.chatwoot.com/hc/user-guide/articles/1784681468-wie-richtet-man-eine-web_socket_verbindung-ein). ### 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](https://www.chatwoot.com/hc/user-guide/articles/1784681468-wie-verwendet-man-webhooks). ### Umsetzung [Hier ist ein Beispiel](https://github.com/chatwoot/client-api-demo) für eine Chat-Oberfläche, die auf den Client-APIs basiert.