Integracja z przychodzącymi usługami Webhook

Utworzono dnia15 marca 2021 r.

TimelinesAI pozwala zautomatyzować wysyłanie wiadomości WhatsApp w odpowiedzi na zdarzenia lub działania w narzędziach, z których już korzystasz: CRM, Support, systemy rekrutacyjne itp.

Zdarzenie "Wyślij wiadomość"

Możliwe jest poinstruowanie TimelinesAI, aby wysłał wiadomość (z załącznikiem lub bez) do określonego kontaktu (może to być grupa). Jeśli w obszarze roboczym połączonych jest wiele kont WhatsApp, możliwe jest również określenie konkretnego konta WhatsApp, które ma zostać użyte do wysłania wiadomości.

Aby skonfigurować integrację, właściciel obszaru roboczego powinien przejść do ekranu "Integrations / Inbound Webhooks" i wygenerować nowy adres URL. Zewnętrzny system powinien wysłać wiadomość w określonym formacie (szczegóły poniżej) na ten adres URL.

Ograniczenia

Maksymalny rozmiar załącznika to 2 MB.
Nie ma natychmiastowej weryfikacji formatu numeru telefonu odbiorcy ani połączenia z WhatsApp. Przejdź do interfejsu osi czasu, aby zweryfikować status wysyłania/odczytywania wiadomości.

Wysyłanie plików przez przychodzące usługi Webhooks

Wysyłanie plików: bezpośrednie pobieranie a usługi hostingu plików

Konieczne jest wysyłanie plików przy użyciu bezpośrednich linków do pobierania. Pozwala to odbiorcy na faktyczne otrzymanie pliku.

Podczas gdy usługa hostingu plików powinna być używana tak, aby mogła dostarczyć bezpośredni link do pobrania. Taki link najlepiej przetestować w trybie incognito/prywatnym, wklejając go w pasku wyszukiwania. Jeśli pobieranie pliku rozpocznie się natychmiast, link jest akceptowalny. Jeśli zamiast tego wyświetlana jest jakakolwiek strona internetowa, link nie może być używany do wysyłania plików.

W przypadku linków do usług hostingu plików nie można pobierać plików. Zamiast tego pobierana i wysyłana jest strona udostępniania, która może prowadzić do "uszkodzonego" pliku.

To z kolei wpłynie na Twoją wiadomość, ponieważ odbiorcy nie będą mogli uzyskać dostępu do przesłanych im multimediów, przez co pliki staną się bezużyteczne. Dlatego ważne jest, aby upewnić się, że wysyłasz bezpośrednie linki do pobrania, ponieważ pozwoli im to uzyskać dostęp do pliku bez żadnych problemów.

Możesz również uruchomić ten test, wysyłając wiadomość webhook na jeden z numerów testowych. Będziesz w stanie określić, jak plik będzie się zachowywał na podstawie tego, co tutaj sprawdziliśmy; jeśli po kliknięciu załącznika pojawi się komunikat o błędzie, taki jak "Plik jest uszkodzony", "Niezgodny plik" lub "Nie udało się załadować dokumentu X", oznacza to, że jest to link do usługi hostingu plików i należy go zastąpić linkiem do bezpośredniego pobierania.

Wykorzystanie kredytu

Wysłanie wiadomości zużywa 1 kredyt z limitu wysyłania wiadomości.
Wysłanie wiadomości z niepustym tekstem i załącznikiem zużywa 2 kredyty z limitu wysyłania wiadomości.
Jeśli wiadomość nie może zostać wysłana (nieprawidłowy numer WhatsApp lub brak połączenia z numerem WhatsApp, błąd serwera WhatsApp), limit wysyłania wiadomości zostanie przywrócony (zwykle w ciągu kilku godzin).

Szybkość wysyłania wiadomości

Wiadomości będą wysyłane z losowym opóźnieniem wynoszącym około 2 sekund między każdą wiadomością (aby uniknąć mechanizmów wykrywania spamu WhatsApp).
W przypadku aktywacji webhooków z częstotliwością mniejszą niż 2 sekundy, wiadomości będą kolejkowane i wysyłane z opóźnieniem. Każda wiadomość w kolejce zużywa kredyt na wysyłanie wiadomości, więc liczba wiadomości w kolejce nie może przekroczyć dostępnego limitu.

Konfiguracja i działania Webhook

"Webhook enabled" - pozwala wyłączyć webhook bez jego całkowitego usuwania.
"Generuj nowy adres URL" - utworzy nowy unikalny adres URL, który będzie akceptował powiadomienia. Poprzedni adres URL nie będzie już dostępny.
"Last sending attempts" - status ostatnich prób aktywacji webhooków.
"Dziennik pobierania" - szczegółowy dziennik 100 ostatnich prób aktywacji, pomocny w rozwiązywaniu problemów z formatowaniem.

Format żądania webhook

Webhook akceptuje dane w formacie JSON za pomocą żądania POST.

"action" (obowiązkowe) - obecnie obsługiwana jest tylko jedna możliwa wartość "send".
"text" (obowiązkowe) - zwykły tekst zakodowany w UTF-8 do wysłania (nie obsługuje markdown, z wyjątkiem separatora linii "\n"), może pozostać pusty, jeśli podano plik.
"file_url" (opcjonalnie) - publicznie dostępny adres URL pliku, który zostanie pobrany i wysłany jako załącznik.
"file_name" (opcjonalnie) - nazwa załącznika (musi być podana, jeśli podano adres URL).

Odbiorcę można określić, podając jeden z następujących parametrów:

"chat_id" - identyfikator czatu wyświetlany w TimelinesAI (można go znaleźć w adresie URL strony czatu lub w ładunku wychodzącego webhooka). Obsługuje to wysyłanie wiadomości do grupy.
"jid" - identyfikator JID WhatsApp określający kontakt lub grupę.
"phone" - numer telefonu, sformatowany zgodnie z międzynarodowym standardem numerów telefonów, tj:
[+][numer kierunkowy kraju][numer kierunkowy][lokalny numer telefonu] (na przykład: +14151231234).
"chat_name" - dokładna nazwa czatu wyświetlana w TimelinesAI.

Jeśli w obszarze roboczym połączonych jest wiele kont WhatsApp, użyj następującego dodatkowego parametru, aby określić konto WhatsApp, które ma być używane:

"whatsapp account phone" (opcjonalnie) - określa (jako numer telefonu, w formacie międzynarodowym) konto WhatsApp, które ma być używane do wysyłania. Jeśli zostanie pominięty, do wysyłania zostanie użyte ostatnio połączone aktywne konto WhatsApp w obszarze roboczym. Uwaga: jeśli określono parametr "chat_id", "whatsapp account phone" nie będzie brane pod uwagę, ponieważ każdy czat jest już połączony z określonym kontem WhatsApp.

Odpowiedź webhook

W przypadku powodzenia (żądanie zostało zweryfikowane i zaakceptowane do wysłania), Webhook odpowie statusem HTTP 200 i JSON, zawierającym message_id utworzonej wiadomości:

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

W przypadku błędu, Webhook odpowie statusem HTTP 40X i JSON ze szczegółami błędu, na przykład:

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

Przykłady

Przykład 1 - wysłanie wiadomości za pośrednictwem określonego konta WA na określony numer telefonu:

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

Przykład 2 - wysłanie wiadomości z tekstem i załącznikiem do czatu (lub grupy) określonego przez id:

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