Session Link

Entwickler-API

Erhalten Sie aus Ihren eigenen Systemen einen direkten Link zur Konversation eines Kunden; Kunde und Konversation werden angelegt, falls sie noch nicht existieren.

• WhatsApp
• Instagram
• REST API

Aus dem MonoStore installierenAuf monochat.ai ansehen

Überblick

Ein API-Aufruf mit einem Kanal und der Telefonnummer oder E-Mail-Adresse eines Kunden liefert einen Link zurück, der die Konversation dieses Kunden in MonoChat öffnet. Existieren Kunde oder Konversation noch nicht, werden sie angelegt.

Setzen Sie den Link in Ihr CRM, Ihr Helpdesk oder Ihre Bestellansicht, und Ihr Team springt von dort direkt in den Chat.

Highlights

• Öffnen oder anlegen. Funktioniert für einen Kunden auf einem bestimmten WhatsApp-, Instagram- oder anderen Kanal, per Telefonnummer oder E-Mail-Adresse.
• Unterwegs weiterleiten. Weisen Sie die Konversation im selben Aufruf einem Mitarbeiter (per ID oder E-Mail-Adresse) oder einer Arbeitsgruppe zu.
• Derselbe Kunde, dieselbe Konversation. Ein erneuter Aufruf für denselben Kunden und Kanal liefert die bestehende Konversation zurück.

Installation und Einrichtung

1. Installieren Sie Session Link unter Einstellungen › MonoStore › Apps oder öffnen Sie den Installationslink app.monochat.ai/apps/vvKJe8Nbp4EQNy2KA. Ohne MonoChat-Konto können Sie sich über den Link zuerst registrieren; die App wird dann für Sie installiert.
2. Erstellen Sie unter Profil › API-Token ein API-Token. Das Token wird nur einmal angezeigt, kopieren Sie es also sofort. Siehe API-Token.
3. Öffnen Sie Einstellungen › Session Link API. Die dortige Dokumentation zeigt die genaue Endpunkt-Adresse Ihres Workspace und kopierfertige Beispielanfragen. Probieren Sie das Beispiel mit einem Ihrer Kanäle aus.
4. Fügen Sie Ihrem CRM, Ihrem Helpdesk oder Ihrer Bestellansicht eine Schaltfläche „Auf WhatsApp chatten“ hinzu, die die API aufruft und die zurückgelieferte url öffnet.

hinweis

• Der Link öffnet MonoChat für angemeldete Personen, die diese Konversation sehen dürfen.
• Der Aufruf öffnet nur die Konversation; er sendet dem Kunden keine Nachricht. Nutzen Sie WhatsApp Template API, um zuerst zu schreiben.

Funktionen

Link zur Konversation

Die Antwort enthält den Link, der die Konversation in MonoChat öffnet, und die ID der Konversation.

Kunde wird bei Bedarf angelegt

Ein neuer Kunde wird mit dem von Ihnen gesendeten Vor- und Nachnamen angelegt; die Antwort verrät, ob der Kunde bereits bekannt war.

Zuweisung

Weisen Sie per ID oder E-Mail-Adresse einem Mitarbeiter oder einer Arbeitsgruppe zu.

Dokumentationsseite

Die API-Referenz mit der genauen Endpunkt-Adresse Ihres Workspace und kopierfertigen Beispielanfragen.

API-Referenz

Der Aufruf ist ein POST mit einem JSON-Body und wird mit einem API-Token authentifiziert.

POST https://app.monochat.ai/api/<slug>/custom-functions/<app-folder>/methods/session-link.js
Authorization: Bearer <API_TOKEN>
Content-Type: application/json

• <slug> ist der Tenant-Slug Ihres Workspace, der Teil nach /tenants/ in Ihrer MonoChat-Adresse.
• <app-folder> ist der Ordner, in dem die App installiert wurde. Die Seite Einstellungen › Session Link API zeigt die vollständige Adresse mit beiden eingetragenen Werten.
• Erstellen Sie das Token unter Profil › API-Token. Siehe API-Token.

Anfragefelder

Feld	Pflicht	Beschreibung
connectorBrand	ja	Der Kanaltyp, zum Beispiel whatsapp oder instagram.
channelUsername	ja	Der Benutzername Ihres Kanals in MonoChat, zum Beispiel Ihre WhatsApp-Nummer ohne +.
customer.identityType	ja	phoneNumber oder email.
customer.identity	ja	Die Telefonnummer des Kunden (mit Ländervorwahl, ohne +) oder seine E-Mail-Adresse.
customer.firstname, customer.lastname	nein	Wird verwendet, wenn der Kunde in MonoChat neu ist. Standardwert -.
assignment.type	nein	agent (Benutzer-ID des Mitarbeiters), agentIdentity (E-Mail-Adresse des Mitarbeiters) oder workgroup (ID der Arbeitsgruppe).
assignment.value	mit assignment.type	Die ID oder E-Mail-Adresse, der die Konversation zugewiesen wird.

Beispielanfrage

curl --location 'https://app.monochat.ai/api/<slug>/custom-functions/<app-folder>/methods/session-link.js' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <API_TOKEN>' \
--data '{
  "connectorBrand": "whatsapp",
  "channelUsername": "905334445566",
  "customer": {
    "identityType": "phoneNumber",
    "identity": "905306667788",
    "firstname": "Ayşe",
    "lastname": "Yılmaz"
  },
  "assignment": { "type": "agentIdentity", "value": "sarah@yourcompany.com" }
}'

Antwort

{
  "result": {
    "url": "https://app.monochat.ai/tenants/<slug>?tab=messages&sessionTab=all&filter=…&_id=<sessionId>",
    "sessionId": "Zeii7vpeeFFnsJepZ",
    "isOldUser": true
  }
}

Feld	Beschreibung
url	Öffnet die Konversation in MonoChat.
sessionId	Die ID der Konversation. Derselbe Kunde auf demselben Kanal erhält immer dieselbe Konversation.
isOldUser	false, wenn der Kunde durch diesen Aufruf angelegt wurde.

Fehler

Ein fehlgeschlagener Aufruf antwortet mit einem Fehlerstatus und einer Meldung:

Meldung	Ursache
connectorBrand, channelUsername and customer fields are required	Ein erforderliches Feld der obersten Ebene fehlt.
customer.identityType must be one of: phoneNumber, email	identityType fehlt oder hat einen anderen Wert.
customer.identity field is required	Die Telefonnummer oder E-Mail-Adresse des Kunden fehlt.
Channel not found	In Ihrem Workspace gibt es keinen Kanal dieses Typs mit diesem Benutzernamen.
Customer Channel not found	Der Kunde konnte keiner Kanalidentität zugeordnet werden.
Agent user not found	Es gibt keinen Mitarbeiter mit der in assignment.value angegebenen E-Mail-Adresse.
401	Der Header Authorization fehlt oder das Token ist ungültig.

Screenshots

Ein CRM, ein Helpdesk und eine Bestellverwaltung, die jeweils die richtige Konversation in MonoChat öffnenDie Konversation im selben API-Aufruf einem Mitarbeiter oder einer Arbeitsgruppe zuweisenEin neuer Kunde und eine neue Konversation, automatisch aus der API-Anfrage angelegtEin API-Aufruf liefert den Link zur KonversationEine Schaltfläche „Auf WhatsApp chatten“ in einem CRM öffnet die Konversation des Kunden mit einem KlickEin erneuter API-Aufruf für denselben Kunden öffnet die bestehende Konversation

FAQ

Sendet Session Link eine Nachricht an den Kunden?

Nein. Es öffnet oder erstellt nur die Konversation und liefert einen Link dazu zurück. Um dem Kunden zuerst zu schreiben, nutzen Sie die App WhatsApp Template API.

Mit welchen Kanälen funktioniert es?

WhatsApp, Instagram und die anderen mit Ihrem MonoChat-Workspace verbundenen Kanäle. In der Anfrage nennen Sie den Kanaltyp und den Benutzernamen Ihres Kanals.

Entstehen doppelte Konversationen?

Nein. Derselbe Kunde auf demselben Kanal erhält immer dieselbe Konversation.

Wer kann den Link öffnen?

Personen, die bei MonoChat angemeldet sind und diese Konversation sehen dürfen.

Verwandte Themen

• WhatsApp Template API
• MonoStore-Apps
• Profileinstellungen
• Arbeitsgruppen