Inkomende Webhook Integratie

Gemaakt op15 maart 2021

Met TimelinesAI kun je het versturen van WhatsApp-berichten automatiseren als reactie op gebeurtenissen of acties in tools die je al gebruikt: CRM, Support, Recruitmentsystemen, enz.

"Gebeurtenis "Bericht verzenden

Het is mogelijk om TimelinesAI de opdracht te geven een bericht (met of zonder bestandsbijlage) te sturen naar een specifiek contact (kan een groep zijn). Als meerdere WhatsApp accounts verbonden zijn in je werkruimte, is het ook mogelijk om een specifiek WhatsApp account te specificeren om te gebruiken voor het verzenden van het bericht.

Om de integratie in te stellen, moet een workspace-eigenaar naar het scherm "Integraties / Inkomende Webhooks" gaan en een nieuwe URL genereren. Het externe systeem moet berichten in een specifiek formaat (zie onderstaande details) naar die URL sturen.

Beperkingen

De maximale grootte van een bijlage is 2 MB.
Er is geen onmiddellijke validatie van de indeling van het telefoonnummer van de ontvanger of verbinding met WhatsApp. Navigeer naar Tijdlijn UI om de verzend-/leesstatus van berichten te verifiëren.

Bestanden verzenden via inkomende webhooks

Een bestand verzenden: rechtstreeks downloaden vs bestandshostingservices

Het is noodzakelijk om bestanden te verzenden via Direct Download Links. Hierdoor kan de ontvanger het bestand daadwerkelijk ontvangen.

Er moet een bestandshostingservice worden gebruikt die een directe downloadlink kan leveren. Zo'n link kun je het beste testen via incognito/private browsing; door de link in de zoekbalk te plakken. Als het downloaden van het bestand meteen begint, is de link acceptabel. Als er in plaats daarvan een webpagina wordt weergegeven, dan kan de link niet worden gebruikt voor het verzenden van bestanden.

Het geval met File Hosting Service links is dat bestanden niet kunnen worden gedownload. In plaats daarvan wordt een gedeelde webpagina gedownload en verzonden, wat kan leiden tot een "corrupt" bestand.

Dit heeft op zijn beurt invloed op je bericht omdat ontvangers geen toegang hebben tot de media die je hen stuurt, waardoor de bestanden onbruikbaar worden. Het is dus van cruciaal belang dat je ervoor zorgt dat je directe downloadlinks verstuurt, zodat ze het bestand zonder problemen kunnen openen.

Je kunt deze test ook uitvoeren door een webhook-bericht naar een van je testnummers te sturen. Je kunt bepalen hoe het bestand zich zal gedragen op basis van wat we hier hebben besproken; als je een foutmelding krijgt zoals "Bestand is beschadigd", "Incompatibel bestand"; of "Kan X-document niet laden", nadat je op de bijlage hebt geklikt, dan is dit een File Hosting Service Link en moet deze worden vervangen door een Direct Download Link.

Kredietgebruik

Het verzenden van een bericht verbruikt 1 krediet van de quota voor het verzenden van berichten.
Het verzenden van een bericht met niet-lege tekst en bijlage verbruikt 2 credits van de quota voor het verzenden van berichten.
Als een bericht niet kan worden verzonden (ongeldig of geen verbinding met WhatsApp-nummer, fout op de WhatsApp-server), wordt het quotum voor het verzenden van berichten hersteld (meestal binnen een paar uur).

Verzendsnelheid berichten

Berichten worden verzonden met een willekeurige vertraging van ongeveer 2 seconden tussen elke twee berichten (om spamdetectiemechanismen van WhatsApp te vermijden).
Als je webhooks activeert met een frequentie van minder dan 2 seconden, worden berichten in een wachtrij geplaatst en met vertraging verzonden. Elk bericht in de wachtrij verbruikt een berichtverzendtegoed, dus het aantal berichten in de wachtrij mag het beschikbare quotum niet overschrijden.

Webhook configuratie en acties

"Webhook ingeschakeld" - hiermee kunt u de webhook uitschakelen zonder deze helemaal te verwijderen
"Genereer nieuwe URL" - maakt een nieuwe unieke URL aan, die meldingen accepteert. De vorige URL zal niet langer beschikbaar zijn.
"Laatste verzendpogingen" - status van laatste webhook activeringspogingen
"Downloadlogboek" - een gedetailleerd logboek van 100 laatste activeringspogingen, handig om problemen met formatteren op te lossen.

Webhook verzoekformaat

De Webhook accepteert gegevens in JSON-indeling door middel van een POST-verzoek.

"action" (verplicht) - momenteel wordt slechts één mogelijke waarde "send" ondersteund
"text" (verplicht)- een platte tekst UTF-8 gecodeerd bericht om te verzenden (geen markdown ondersteund, behalve "\n" regel scheidingsteken), kan leeg gelaten worden als bestand is gespecificeerd.
"file_url" (optioneel) - een publiek toegankelijke URL van een bestand dat wordt gedownload en verzonden als bijlage.
"file_name" (optioneel) - een naam voor de bijlage (moet worden opgegeven als URL is gespecificeerd).

De ontvanger kan worden gespecificeerd door een van de volgende parameters op te geven:

"chat_id" - een id van de chat zoals deze verschijnt in TimelinesAI (kan gevonden worden in de URL van de chatpagina, of in de payload van uitgaande webhook). Dit ondersteunt het versturen van berichten naar een groep.
"jid" - een WhatsApp JID die het contact of de groep specificeert.
"phone" - een telefoonnummer, geformatteerd volgens de internationale telefoonnummerstandaard, d.w.z.:
[+][landcode][netnummer][lokaal telefoonnummer] (bijvoorbeeld: +14151231234)
"chat_name" - een exacte naam van de chat zoals die verschijnt in TimelinesAI

Als meerdere WhatsApp-accounts zijn verbonden in de werkruimte, gebruik je de volgende aanvullende parameter om het te gebruiken WhatsApp-account op te geven:

"whatsapp account phone" (optioneel) - specificeert (als een telefoonnummer, in internationaal formaat) de WhatsApp-account die weе moeten gebruiken voor het verzenden. Als deze wordt weggelaten, wordt de meest recent verbonden actieve WhatsApp-account in de werkruimte gebruikt voor verzending. Opmerking: als de parameter "chat_id" is opgegeven, wordt "whatsapp-account telefoon" genegeerd omdat elke chat al is verbonden met een specifieke WhatsApp-account.

Webhook antwoord

In geval van succes (het verzoek is gevalideerd en geaccepteerd voor verzending), zal de Webhook reageren met HTTP-status 200 en JSON, met daarin message_id van het aangemaakte bericht:

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

In geval van een fout zal de Webhook reageren met HTTP status 40X en JSON met details van de fout, bijvoorbeeld:

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

Voorbeelden

Voorbeeld 1 - een bericht verzenden via een specifiek WA-account naar een specifiek telefoonnummer:

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

Voorbeeld 2 - een bericht met tekst en bijlage verzenden naar een chat (of groep) die is gespecificeerd door id:

{
"action": "send", 
"chat_id": "77234", 
"text": "lorem ipsum"
"file_url" : "https://150588669.v2.pressablecdn.com/logo.png",
"file_name" : "logo.png"
}

Auteur
Recente berichten

admin

Laatste berichten van admin (Bekijk alle)

Hoe kunnen we helpen?