> ## Documentation Index
> Fetch the complete documentation index at: https://docs.brosbots.com/llms.txt
> Use this file to discover all available pages before exploring further.

# WhatsApp Business

> Agent rozmawia na WhatsAppie, odbiera połączenia z WhatsAppa i wysyła wiadomości z numeru Twojej firmy.

## Co daje integracja

Po podłączeniu numeru WhatsApp Business agent robi trzy rzeczy na tym samym
numerze:

* **Odpowiada na wiadomości.** Klient pisze na WhatsAppie, agent odpisuje
  swoim promptem i pamięta wątek rozmowy.
* **Odbiera połączenia.** Rozmowa dzwoniona z WhatsAppa trafia do tego samego
  agenta głosowego, który odbiera telefon - z jego głosem, narzędziami,
  transkrypcją i historią rozmów.
* **Wysyła wiadomości.** W trakcie rozmowy telefonicznej (narzędzie
  `send_whatsapp`) albo automatycznie po jej zakończeniu.

Wiadomości idą przez **Twoje konto Meta**, nie nasze. Nie doliczamy opłaty za
wiadomość - rozliczasz się bezpośrednio z Metą.

## Czego potrzebujesz

* Konta **Meta for Developers** i aplikacji typu **Business** z produktem
  **WhatsApp**.
* Numeru telefonu podpiętego do WhatsApp Business Platform (Cloud API).

<Note>
  **Numer z aplikacji WhatsApp Business.** Integracja nie obsługuje trybu
  współdzielenia (coexistence), w którym ten sam numer działa jednocześnie w
  aplikacji WhatsApp Business na telefonie i w API. Podłączenie numeru, którego
  używasz w aplikacji, wymaga przeniesienia go do Cloud API, a wtedy przestaje
  on działać w aplikacji. Jeśli chcesz dalej odbierać wiadomości w aplikacji,
  podłącz osobny numer albo zostań przy SMS-ie po rozmowie - może zawierać link
  `https://wa.me/48...`, który otwiera czat z numerem z aplikacji.
</Note>

## Konfiguracja

### 1. Skopiuj dane z aplikacji Meta

W panelu aplikacji, w zakładce **WhatsApp → API Setup**:

* **Phone Number ID** - identyfikator numeru, nie sam numer telefonu.
* **Access Token** - token dostępu.

<Warning>
  Token tymczasowy z tej zakładki wygasa po 24 godzinach. Do pracy na stałe
  wygeneruj token użytkownika systemowego z uprawnieniami
  `whatsapp_business_messaging` i `whatsapp_business_management`.
</Warning>

**App Secret** znajdziesz w **Ustawieniach aplikacji → Podstawowe**. Nie jest
wymagany, ale bez niego przyjmujemy webhooki bez weryfikacji podpisu - warto
go uzupełnić.

### 2. Podłącz numer w Brosbots

1. Wejdź na stronę **Integracje** i wybierz **WhatsApp Business**.
2. Wklej Phone Number ID, token dostępu i App Secret.
3. W polu **Agent** wskaż agenta, który ma odpowiadać na wiadomości i odbierać
   połączenia. Bez wskazania agenta wiadomości są tylko zapisywane.
4. Opcjonalnie: w polu **Szablon po rozmowie** wpisz nazwę szablonu
   wiadomości zatwierdzonego przez Meta, a w **Język szablonu** język, w którym
   go zatwierdzono (puste = `pl`). Tylko z szablonem agent może wysłać
   WhatsAppa po rozmowie - patrz [Po rozmowie](#po-rozmowie).
5. Zapisz połączenie. Sprawdzimy dane w Meta, zanim cokolwiek zapiszemy.

### 3. Wróć do Meta po webhook

Po zapisaniu pokażemy dwie wartości: **adres zwrotny (Callback URL)** i
**token weryfikacyjny**. W aplikacji Meta, w sekcji **WhatsApp → Configuration
→ Webhooks**:

1. Wklej oba pola i kliknij **Verify and save**.
2. Zasubskrybuj pola **messages** (wiadomości) oraz **calls** (połączenia).

Od tej chwili wiadomości i połączenia trafiają do agenta.

## Rozmowy tekstowe

Agent odpowiada swoim promptem, tym samym, którym mówi przez telefon. Dostaje
przy tym instrukcję, że pisze na WhatsAppie, więc odpowiada krótko i nie
dyktuje numerów cyfra po cyfrze.

Wątek pamiętamy przez **24 godziny** - tyle, ile trwa okno obsługi klienta w
WhatsAppie. Osoba, która odezwie się po tygodniu, zaczyna rozmowę od nowa.

Agent odpowiada tylko na tekst. Wiadomość głosową, zdjęcie czy dokument
zapiszemy i odpiszemy prośbą o napisanie wiadomością - zamiast milczeć.

## Wysyłanie wiadomości przez agenta

W edytorze agenta, w zakładce **Integracje**, włącz **Wyślij WhatsApp** i
wybierz, kiedy ma wysyłać:

* **W trakcie rozmowy** - model sam decyduje, kierując się Twoimi zasadami.
* **Po rozmowie** - z szablonu, z tymi samymi zmiennymi co SMS: tym, co agent
  zebrał, faktami o połączeniu (`{{caller_number}}`, `{{call_time}}`,
  `{{call_disposition}}`) i `{{gathered_context.*}}`. W przeciwieństwie do
  SMS-a działa tu też `{{call_summary}}` - WhatsApp rozlicza się za rozmowę, a
  nie za każde 160 znaków - ale trzeba je wpisać ręcznie, bo menu **Wstaw
  zmienną** go nie proponuje.
* **Obie opcje naraz.**

Opcje **Po rozmowie** i **Obie** pojawiają się dopiero, gdy połączenie WhatsApp
ma zatwierdzony szablon - patrz niżej. Do tego czasu edytor pokazuje
informację, a agent wysyła WhatsAppa tylko w trakcie rozmowy.

### Po rozmowie

WhatsApp pozwala napisać zwykłą wiadomość tylko do osoby, która odezwała się
do Twojego numeru w ciągu ostatnich 24 godzin. Po rozmowie telefonicznej to
okno zwykle jest zamknięte i wtedy Meta dostarcza tylko **szablon wiadomości,
który zatwierdziła** - zwykły tekst odrzuca. Dlatego wiadomość po rozmowie
wychodzi jako szablon:

1. W **WhatsApp Manager → Szablony wiadomości** utwórz szablon (do
   podziękowania po rozmowie pasuje kategoria *Utility*) z **jedną zmienną
   `{{1}}`** w treści, np. „Dziękujemy za rozmowę. `{{1}}`”. Poczekaj, aż Meta go
   zatwierdzi.
2. Na stronie **Integracje** edytuj połączenie WhatsApp i wpisz nazwę szablonu
   w **Szablon po rozmowie**, a kod języka w **Język szablonu** (np. `pl`,
   `en_US`).
3. W agencie wybierz **Po rozmowie** i napisz treść jak dotąd. Trafia ona w
   zmienną `{{1}}` szablonu, złożona w jedną linię (Meta odrzuca znaki nowej
   linii w zmiennej) i ucięta na 1000 znakach.

Agent ustawiony na wysyłkę po rozmowie, zanim to wprowadziliśmy, zachowuje to
ustawienie i dalej wysyła zwykły tekst, który dociera tylko do osób piszących
w ciągu ostatnich 24 godzin. Edytor pokazuje przy nim ostrzeżenie; dodaj
szablon do połączenia albo przełącz agenta z powrotem na **W trakcie
rozmowy**.

## Połączenia głosowe

Połączenie z WhatsAppa uruchamia dokładnie tę samą ścieżkę co rozmowa przez
widget na stronie, więc agent brzmi tak samo i ma te same narzędzia. Rozmowa
pojawia się w **Historii rozmów** i jest rozliczana jak każda inna - jeśli
saldo organizacji jest na zerze, połączenie nie zostanie odebrane.

## Najczęstsze problemy

| Objaw | Przyczyna |
| - | - |
| Meta nie weryfikuje adresu zwrotnego | Nie zgadza się token weryfikacyjny albo adres. Skopiuj oba pola ponownie ze strony Integracje. |
| Test połączenia zwraca błąd uwierzytelnienia | Token wygasł - wygeneruj token użytkownika systemowego. |
| Wiadomości przychodzą, ale agent nie odpisuje | W połączeniu nie wskazano agenta, albo połączenie jest wyłączone. |
| Wiadomość po rozmowie nie dociera | Połączenie nie ma zatwierdzonego szablonu, a okno 24 godzin jest zamknięte - patrz [Po rozmowie](#po-rozmowie). |
| W edytorze agenta nie ma opcji „Po rozmowie” | Połączenie WhatsApp nie ma jeszcze **Szablonu po rozmowie**. |
| Meta odrzuca wiadomość z szablonu (`#132000`, `#132001`) | Nazwa albo język nie zgadzają się z zatwierdzonym szablonem, albo jego treść nie ma dokładnie jednej zmiennej `{{1}}`. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.