> ## 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. 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.**

<Warning>
  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 Meta odrzuci wiadomość. Wysyłka po rozmowie ma
  sens dla kontaktów, które piszą do Ciebie na WhatsAppie - w pozostałych
  przypadkach użyj SMS-a po rozmowie. Wysyłka po rozmowie nie korzysta z
  zatwierdzonych szablonów wiadomości Meta, więc nie obejdzie tego ograniczenia.
</Warning>

## 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 | Zamknięte okno 24 godzin - patrz ostrzeżenie wyżej. |


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