Wie können wir helfen?

Eingehende Webhook-Integration

Erstellt am

TimelinesAI ermöglicht es Ihnen, den Versand von WhatsApp-Nachrichten als Reaktion auf Ereignisse oder Aktionen in den von Ihnen bereits verwendeten Tools zu automatisieren: CRM, Support, Rekrutierungssysteme, usw.

"Nachricht senden" Ereignis

Es ist möglich, TimelinesAI anzuweisen, eine Nachricht (mit oder ohne Dateianhang) an einen bestimmten Kontakt (kann eine Gruppe sein) zu senden. Wenn mehrere WhatsApp-Konten in Ihrem Arbeitsbereich verbunden sind, ist es auch möglich, ein bestimmtes WhatsApp-Konto anzugeben, das für das Senden der Nachricht verwendet werden soll.

Um die Integration einzurichten, sollte ein Arbeitsbereichseigentümer zum Bildschirm "Integrationen / Eingehende Webhooks" navigieren und eine neue URL erstellen. Das externe System sollte Nachrichten in einem bestimmten Format (siehe Details unten) an diese URL senden.

Beschränkungen

  • Die maximale Größe des Anhangs beträgt 2 MB.
  • Es gibt keine unmittelbare Validierung des Telefonnummernformats des Empfängers oder der Verbindung zu WhatsApp. Navigieren Sie zur Timelines-Benutzeroberfläche, um den Sende-/Lesestatus von Nachrichten zu überprüfen.

Senden von Dateien über eingehende Webhooks

Versenden einer Datei: Direktes Herunterladen vs. Datei-Hosting-Dienste

Es ist unbedingt erforderlich, Dateien über direkte Download-Links zu versenden. So kann der Empfänger die Datei tatsächlich erhalten.

Ein Dateihosting-Dienst sollte hingegen so genutzt werden, dass er einen direkten Download-Link bereitstellen kann. Ein solcher Link lässt sich am besten durch inkognito/privates Surfen testen, indem man den Link in die Suchleiste einfügt. Wenn der Dateidownload sofort startet, ist der Link akzeptabel. Wenn stattdessen eine beliebige Webseite angezeigt wird, kann der Link nicht für den Versand von Dateien verwendet werden.

Bei File Hosting Service-Links können die Dateien nicht heruntergeladen werden. Was stattdessen heruntergeladen und gesendet wird, ist eine gemeinsame Webseite, die zu einer "beschädigten" Datei führen kann.

Dies wiederum wirkt sich auf Ihre Nachricht aus, da die Empfänger nicht auf die von Ihnen gesendeten Medien zugreifen können, wodurch die Dateien unbrauchbar werden. Daher ist es wichtig, dass Sie sicherstellen, dass Sie direkte Download-Links versenden, damit die Empfänger ohne Probleme auf die Datei zugreifen können.

Sie können diesen Test auch durchführen, indem Sie eine Webhook-Nachricht an eine Ihrer Testnummern senden. Wenn Sie eine Fehlermeldung wie "File is Corrupted", "Incompatible File" oder "Failed to load X document" erhalten, nachdem Sie auf den Anhang geklickt haben, handelt es sich um einen File Hosting Service Link und muss durch einen Direct Download Link ersetzt werden.

Kreditinanspruchnahme

  • Das Versenden einer Nachricht verbraucht 1 Guthaben aus dem Nachrichtenversandkontingent.
  • Das Versenden einer Nachricht mit nicht leerem Text und Anhang verbraucht 2 Credits aus dem Nachrichtenversandkontingent.
  • Wenn eine Nachricht nicht gesendet werden kann (ungültige oder nicht mit der WhatsApp-Nummer verbundene Nummer, WhatsApp-Serverfehler), wird die Quote für den Nachrichtenversand wiederhergestellt (normalerweise innerhalb weniger Stunden).

Geschwindigkeit der Nachrichtenübermittlung

  • Die Nachrichten werden mit einer zufälligen Verzögerung von etwa 2 Sekunden zwischen zwei Nachrichten gesendet (um die Spam-Erkennungsmechanismen von WhatsApp zu umgehen).
  • Wenn Sie Webhooks mit einer Frequenz von weniger als 2 Sekunden aktivieren, werden die Nachrichten in eine Warteschlange gestellt und mit Verzögerung versendet. Jede Nachricht in der Warteschlange verbraucht ein Guthaben für den Nachrichtenversand, so dass die Anzahl der Nachrichten in der Warteschlange das verfügbare Kontingent nicht überschreiten kann.

Webhook-Konfiguration und -Aktionen

  • "Webhook aktiviert" - ermöglicht es, den Webhook zu deaktivieren, ohne ihn ganz zu entfernen
  • "Neue URL generieren" - erstellt eine neue eindeutige URL, die Benachrichtigungen akzeptiert. Die vorherige URL wird nicht mehr verfügbar sein.
  • "Letzte Sendeversuche" - Status der letzten Webhook-Aktivierungsversuche
  • "Download-Protokoll" - ein detailliertes Protokoll der letzten 100 Aktivierungsversuche, hilfreich bei der Fehlersuche bei Formatierungsproblemen.

Format der Webhook-Anfrage

Der Webhook akzeptiert Daten im JSON-Format mittels einer POST-Anfrage.

  • "action" (obligatorisch) - derzeit wird nur ein möglicher Wert "send" unterstützt
  • "text" (obligatorisch) - eine in UTF-8 kodierte Nachricht, die gesendet werden soll (keine Markdown-Unterstützung, außer "\n" als Zeilentrennzeichen), kann leer gelassen werden, wenn eine Datei angegeben ist.
  • "file_url" (optional) - eine öffentlich zugängliche URL einer Datei, die heruntergeladen und als Anhang versendet wird.
  • "file_name" (optional) - ein Name für den Anhang (muss angegeben werden, wenn eine URL angegeben wird).

Der Empfänger kann durch Angabe eines der folgenden Parameter angegeben werden:

  • "chat_id" - eine ID des Chats, wie sie in TimelinesAI erscheint (kann in der URL der Chatseite oder in der Nutzlast des ausgehenden Webhooks gefunden werden). Dies unterstützt das Senden von Nachrichten an eine Gruppe.
  • "jid" - eine WhatsApp JID, die den Kontakt oder die Gruppe angibt
  • "phone" - eine Telefonnummer, formatiert nach dem internationalen Telefonnummernstandard, d. h.:
    [+][Landesvorwahl][Ortsvorwahl][lokale Telefonnummer] (zum Beispiel: +14151231234)
  • "chat_name" - ein genauer Name des Chats, wie er in TimelinesAI erscheint

Wenn mehrere WhatsApp-Konten mit dem Arbeitsbereich verbunden sind, verwenden Sie den folgenden zusätzlichen Parameter, um das zu verwendende WhatsApp-Konto anzugeben:

  • "whatsapp account phone" (optional) - gibt (als Telefonnummer, im internationalen Format) das WhatsApp-Konto an, das für den Versand verwendet werden soll. Wird dieser Parameter weggelassen, wird das zuletzt verbundene aktive WhatsApp-Konto im Arbeitsbereich zum Senden verwendet. Hinweis: Wenn der Parameter "chat_id" angegeben wird, wird "whatsapp account phone" nicht berücksichtigt, da jeder Chat bereits mit einem bestimmten WhatsApp-Konto verbunden ist.

Webhook-Antwort

Im Erfolgsfall (die Anfrage wurde validiert und zum Senden akzeptiert) antwortet der Webhook mit dem HTTP-Status 200 und JSON, das die message_id der erstellten Nachricht enthält:

{
    "status": "success",
    "data": {
        "message_id": "wa_backend:3EB09FCC85FE99662E46"
    }
}

 

Im Falle eines Fehlers antwortet der Webhook mit dem HTTP-Status 40X und JSON mit den Details des Fehlers, zum Beispiel:

{
"status": 40X,
"data": {},
"message": "Webhook not found"
}

Beispiele

Beispiel 1 - Senden einer Nachricht über ein bestimmtes WA-Konto an eine bestimmte Telefonnummer:

{
"action": "send",
"whatsapp account phone" : "+15105566777", 
"phone": "+14151231234", 
"text": "lorem ipsum"
}

Beispiel 2 - Senden einer Nachricht mit Text und Anhang an einen Chat (oder eine Gruppe), der/die durch id:

{
"action": "send", 
"chat_id": "77234", 
"text": "lorem ipsum"
"file_url" : "https://150588669.v2.pressablecdn.com/logo.png",
"file_name" : "logo.png"
}
Letzte Beiträge von admin (alle anzeigen)
Inhaltsübersicht