> This is a page from the ElevenLabs documentation. For a complete page index, fetch https://elevenlabs.io/docs/llms.txt. For the full documentation in a single file, fetch https://elevenlabs.io/docs/llms-full.txt. # 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](https://business.facebook.com/latest/whatsapp_manager/message_templates), 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](https://developers.facebook.com/documentation/business-messaging/whatsapp/pricing). * 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. > **Note** > > Meta ogranicza liczbę [szablonów marketingowych ](https://developers.facebook.com/documentation/business-messaging/whatsapp/templates/marketing-templates/per-user-limits), > które jeden użytkownik może otrzymać w danym okresie. Jeśli szablon marketingowy nie zostanie po cichu dostarczony, > często wynika to z tego limitu (błąd Meta 131049). ## 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 Przejdź do [strony WhatsApp](https://elevenlabs.io/app/agents/whatsapp), wybierz konto i kliknij przycisk ***Wychodzące -> Wiadomość***. Wybierz agenta, podaj identyfikator użytkownika WhatsApp oraz wybierz szablon wiadomości i jego parametry: ![Okno wiadomości wychodzącej WhatsApp](/docs/_fern-img/13913c2ccc1d92cb59e7332b6fdb4a8c8c64760a334d1a311fa2007831eeb986.webp) #### Python ```python from elevenlabs import ElevenLabs elevenlabs = ElevenLabs() elevenlabs.conversational_ai.whatsapp.outbound_message( whatsapp_phone_number_id="524029457612345", whatsapp_user_id="12213231492", template_name="welcome", template_language_code="en", template_params=[ { "type": "body", "parameters": [ { "type": "text", "parameter_name": "name", "text": "Daniele", } ], } ], agent_id="agent_9201kwcrbq9qfxaa2t8nnnkqf2w9", conversation_initiation_client_data={ "dynamic_variables": {"customer_name": "Daniele"}, }, ) ``` #### TypeScript ```typescript import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js"; const elevenlabs = new ElevenLabsClient(); await elevenlabs.conversationalAi.whatsapp.outboundMessage({ whatsappPhoneNumberId: "524029457612345", whatsappUserId: "12213231492", templateName: "welcome", templateLanguageCode: "en", templateParams: [ { type: "body", parameters: [ { type: "text", parameterName: "name", text: "Daniele", }, ], }, ], agentId: "agent_9201kwcrbq9qfxaa2t8nnnkqf2w9", conversationInitiationClientData: { dynamicVariables: { customer_name: "Daniele" }, }, }); ``` #### cURL ```bash curl -X POST https://api.elevenlabs.io/v1/convai/whatsapp/outbound-message \ -H "xi-api-key: $ELEVENLABS_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "whatsapp_phone_number_id": "524029457612345", "whatsapp_user_id": "12213231492", "template_name": "welcome", "template_language_code": "en", "template_params": [ { "type": "body", "parameters": [ {"type": "text", "parameter_name": "name", "text": "Daniele"} ] } ], "agent_id": "agent_9201kwcrbq9qfxaa2t8nnnkqf2w9", "conversation_initiation_client_data": { "dynamic_variables": {"customer_name": "Daniele"} } }' ``` Pełny schemat żądania znajdziesz w [dokumentacji API](/docs/pl/api-reference/whats-app/outbound-message). > **Tip** > > Asystent AI może dostosować te przykłady do twojego szablonu. Wskaż mu plik ElevenLabs > [llms.txt](/docs/pl/llms.txt) (lub bardziej szczegółowy [llms-full.txt](/docs/pl/llms-full.txt)), wklej definicję > szablonu z WhatsApp Manager i poproś o żądanie — utworzy polecenie cURL > lub wywołanie SDK z poprawnym `template_params` dla twojego szablonu. ### 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`. > **Warning** > > W niektórych krajach identyfikator WhatsApp dla danej osoby różni się od jej wybieranego numeru — na > przykład numery meksykańskie mają dodatkową cyfrę `1` po kodzie kraju (`521...`), a numery brazylijskie > mogą zawierać lub nie zawierać dziewiątej cyfry. Jeśli użytkownik pisał do ciebie wcześniej, użyj raczej > `whatsapp_user_id` z tej wcześniejszej rozmowy, który możesz skopiować z historii > rozmów. ### Zmienne dynamiczne, gałęzie i środowiska Pole `conversation_initiation_client_data` pozwala ustawić [zmienne dynamiczne](/docs/pl/eleven-agents/customization/personalization/dynamic-variables) dla rozmowy i przypiąć ją do konkretnej [gałęzi agenta](/docs/pl/eleven-agents/operate/versioning) oraz [środowiska](/docs/pl/eleven-agents/integrate/environment-variables): ```json { "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](/docs/pl/eleven-agents/whatsapp#initialization-context). > **Note** > > Parametry szablonu uzupełniają tylko tekst szablonu — agent ich nie widzi. Jeśli agent potrzebuje > wartości z szablonu (np. imienia klienta), przekaż ją ponownie w > `dynamic_variables`. ### 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](/docs/pl/eleven-agents/whatsapp/troubleshooting). ## Planowanie połączenia wychodzącego Wychodzące połączenia WhatsApp wymagają zgody użytkownika — zobacz [zgody użytkownika na połączenia](https://developers.facebook.com/documentation/business-messaging/whatsapp/calling/user-call-permissions). Utwórz szablon wiadomości z komponentem **prośby o zgodę na połączenie** w [WhatsApp Manager](https://business.facebook.com/latest/whatsapp_manager/message_templates). 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 Przejdź do [strony WhatsApp](https://elevenlabs.io/app/agents/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: ![Okno połączenia wychodzącego WhatsApp](/docs/_fern-img/1fcf7968f1651ce8e9474e770aad4dce4e702c69b4522f5bcc65efcd8bf8a3e4.webp) #### Python ```python from elevenlabs import ElevenLabs elevenlabs = ElevenLabs() elevenlabs.conversational_ai.whatsapp.outbound_call( whatsapp_phone_number_id="524029457612345", whatsapp_user_id="12213231492", whatsapp_call_permission_request_template_name="call_permission", whatsapp_call_permission_request_template_language_code="en", agent_id="agent_9201kwcrbq9qfxaa2t8nnnkqf2w9", conversation_initiation_client_data={ "dynamic_variables": {"customer_name": "Daniele"}, }, ) ``` #### TypeScript ```typescript import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js"; const elevenlabs = new ElevenLabsClient(); await elevenlabs.conversationalAi.whatsapp.outboundCall({ whatsappPhoneNumberId: "524029457612345", whatsappUserId: "12213231492", whatsappCallPermissionRequestTemplateName: "call_permission", whatsappCallPermissionRequestTemplateLanguageCode: "en", agentId: "agent_9201kwcrbq9qfxaa2t8nnnkqf2w9", conversationInitiationClientData: { dynamicVariables: { customer_name: "Daniele" }, }, }); ``` #### cURL ```bash curl -X POST https://api.elevenlabs.io/v1/convai/whatsapp/outbound-call \ -H "xi-api-key: $ELEVENLABS_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "whatsapp_phone_number_id": "524029457612345", "whatsapp_user_id": "12213231492", "whatsapp_call_permission_request_template_name": "call_permission", "whatsapp_call_permission_request_template_language_code": "en", "agent_id": "agent_9201kwcrbq9qfxaa2t8nnnkqf2w9", "conversation_initiation_client_data": { "dynamic_variables": {"customer_name": "Daniele"} } }' ``` Pełny schemat żądania znajdziesz w [dokumentacji API](/docs/pl/api-reference/whats-app/outbound-call). 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. > **Note** > > Meta pobiera opłaty za połączenia wychodzące oraz prośby o zgodę na połączenie wysłane poza [oknem obsługi klienta ](https://developers.facebook.com/documentation/business-messaging/whatsapp/messages/send-messages#customer-service-windows). > Dodaj metodę płatności w WhatsApp Manager przed planowaniem połączeń. ## Kampanie i grupowe wysyłanie Aby dzwonić do wielu użytkowników, użyj [połączeń grupowych](/docs/pl/eleven-agents/phone-numbers/batch-calls) 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](/docs/pl/api-reference/whats-app/outbound-message) raz dla każdego odbiorcy i przestrzegaj limitów wiadomości Meta dla swojego numeru — zobacz [limity wiadomości](https://developers.facebook.com/documentation/business-messaging/whatsapp/messages/messaging-limits).