Wiadomości wychodzące i szablony

Omówienie

Agent może wysyłać dowolne wiadomości WhatsApp tylko w aktywnej rozmowie. Aby jako pierwszy dotrzeć do użytkownika — z powiadomieniem, ponownym kontaktem lub zaplanowanym połączeniem — wysyłasz zatwierdzony przez Meta szablon wiadomości. Ta strona opisuje tworzenie szablonów, wysyłanie wiadomości i połączeń wychodzących oraz ich obsługę na dużą skalę.

Tworzenie szablonów w WhatsApp Manager

Szablony tworzysz i zatwierdzasz w WhatsApp Manager, a nie w ElevenLabs.

Podczas tworzenia szablonu:

• Wybierz kategorię: Utility dla wiadomości transakcyjnych, Marketing dla promocyjnych lub Authentication dla kodów weryfikacyjnych. Meta inaczej wycenia i limituje każdą kategorię — zobacz cennik WhatsApp.
• Wybierz format parametrów: pozycyjny ({{1}}, {{2}}) lub nazwany ({{customer_name}}). Nazwane parametry wymagają parameter_name przy każdej wysyłanej wartości.
• Prześlij do zatwierdzenia. Zwykle trwa to od kilku minut do kilku godzin. Nie możesz wysłać szablonu oczekującego ani odrzuconego — API przyjmie żądanie, ale Meta nigdy nie dostarczy wiadomości.

Wysyłanie wiadomości wychodzącej

Wysłanie wiadomości z szablonu rozpoczyna nową rozmowę. Agent pozostaje cicho, dopóki użytkownik nie odpowie — szablon jest pierwszą wiadomością, a liczniki rozmowy nie uruchamiają się, dopóki użytkownik nie odpowie.

Panel

Python

TypeScript

cURL

Przejdź do strony WhatsApp, wybierz konto i kliknij przycisk Wychodzące -> Wiadomość. Wybierz agenta, podaj identyfikator użytkownika WhatsApp oraz wybierz szablon wiadomości i jego parametry:

Pełny schemat żądania znajdziesz w dokumentacji API.

Parametry szablonu

template_params to lista obiektów komponentów — po jednym dla każdego komponentu szablonu z parametrami:

• {"type": "body", "parameters": [...]} dla symboli zastępczych w treści
• {"type": "header", "parameters": [...]} dla nagłówka z parametrami (tekst, obraz, dokument lub lokalizacja)
• {"type": "button", "sub_type": ..., "index": ..., "parameters": [...]} dla parametrów przycisku

Każdy wpis w parameters to obiekt wartości, np. {"type": "text", "text": "Daniele"}. W szablonach z nazwanymi parametrami dodaj parameter_name przy każdej wartości. Pominięcie otoczki komponentu — na przykład przekazanie {"type": "text", ...} bezpośrednio w template_params — zostanie odrzucone.

Format numeru odbiorcy

whatsapp_user_id może zawierać tylko cyfry: kod kraju, a następnie numer, bez +, spacji ani myślników. Na przykład 14155552671, a nie +1 (415) 555-2671.

Zmienne dynamiczne, gałęzie i środowiska

Pole conversation_initiation_client_data pozwala ustawić zmienne dynamiczne dla rozmowy i przypiąć ją do konkretnej gałęzi agenta oraz środowiska:

{
  "dynamic_variables": { "customer_name": "Daniele" },
  "branch_id": "agtbrch_8721kwarbs83e233mg1fzkaf9pg0",
  "environment": "staging"
}

Te ustawienia pozostają dla całej rozmowy: gdy użytkownik odpowie, agent wznowi ją w żądanej gałęzi i środowisku. Gałąź i środowisko są najpierw sprawdzane — jeśli któreś nie istnieje, żądanie kończy się błędem, a wiadomość nie jest wysyłana.

To pole żądania przekazuje zmienne dynamiczne do rozmów wychodzących; rozmowy przychodzące otrzymują je z webhooka inicjującego rozmowę — zobacz kontekst inicjalizacji.

Po wysłaniu

Udane żądanie zwraca conversation_id, a rozmowa pojawia się w historii z wyrenderowanym szablonem jako pierwszą wiadomością. Agent nie działa, dopóki użytkownik nie odpowie. Wysłanie szablonu nie uruchamia ani licznika maksymalnego czasu trwania, ani licznika bezczynności; oba zaczynają działać po wznowieniu rozmowy. Odpowiedź 200 oznacza, że ElevenLabs przyjęło żądanie — Meta może nadal później odrzucić dostarczenie. Jeśli wiadomość nie dotrze, zobacz Rozwiązywanie problemów.

Planowanie połączenia wychodzącego

Wychodzące połączenia WhatsApp wymagają zgody użytkownika — zobacz zgody użytkownika na połączenia. Utwórz szablon wiadomości z komponentem prośby o zgodę na połączenie w WhatsApp Manager. Gdy planujesz połączenie, ElevenLabs sprawdza status zgody:

• Zgoda została już udzielona: połączenie jest wykonywane od razu.
• O zgodę jeszcze nie poproszono: wysyłany jest szablon prośby o zgodę, a połączenie jest wykonywane, gdy tylko użytkownik ją zatwierdzi.
• Zgoda została odrzucona: rozmowa jest oznaczana jako nieudana z powodem User declined the call permission request.

Panel

Python

TypeScript

cURL

Przejdź do strony WhatsApp, wybierz konto i kliknij przycisk Wychodzące -> Połączenie. Wybierz agenta, podaj identyfikator użytkownika WhatsApp i wybierz szablon prośby o zgodę na połączenie:

Pełny schemat żądania znajdziesz w dokumentacji API. Tak jak w przypadku wiadomości wychodzących, conversation_initiation_client_data ustawia zmienne dynamiczne i przypina rozmowę do gałęzi oraz środowiska, a nieznana gałąź lub środowisko zostaną odrzucone przed zaplanowaniem połączenia.

Kampanie i grupowe wysyłanie

Aby dzwonić do wielu użytkowników, użyj połączeń grupowych z whatsapp_params: podaj raz identyfikator numeru telefonu i szablon prośby o zgodę na połączenie, a następnie whatsapp_user_id dla każdego odbiorcy.

Nie ma jeszcze natywnego endpointu do grupowego wysyłania wiadomości wychodzących. W kampaniach z szablonami wywołaj endpoint wiadomości wychodzących raz dla każdego odbiorcy i przestrzegaj limitów wiadomości Meta dla swojego numeru — zobacz limity wiadomości.