> ## 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.
# Przegląd integracji
> Połącz Brosbots z zewnętrznymi usługami i platformami.
## Wprowadzenie
Brosbots oferuje elastyczną architekturę integracji z zewnętrznymi usługami.
Integracje konfigurujesz raz na poziomie organizacji, a potem włączasz je w
poszczególnych agentach.
Katalog w zakładce **Integracje** to jedna ciągła siatka kafelków. Zawężasz ją
wyszukiwarką, filtrem kategorii i filtrem **Wszystkie / Połączone /
Niepołączone**. Na początku siatki stoją narzędzia agenta - przekierowanie
rozmowy, zakończenie rozmowy i własne HTTP API - bo potrzebuje ich prawie
każdy agent; zob. [Narzędzia](/pl/voice-agent/tools).
Obok katalogu jest zakładka **Własne**: kreator integracji z systemem, którego
nie ma w katalogu. Buduje zapytania do Twojego API w trakcie rozmowy, webhooki
ze zdarzeniami i adresy dla formularzy z leadami; zob.
[Własne integracje](/pl/integrations/custom) i [Webhooki](/pl/integrations/webhooks).
## Kategorie integracji
### Numery telefonów
Numerami zarządza platforma - kupujesz je i przypisujesz agentom w panelu,
w zakładce **Numery**. Nie potrzebujesz konta u zewnętrznego operatora.
### Kalendarz i rezerwacje
Rezerwacje w trakcie rozmowy dla biznesów wizytowych (salony, kliniki,
restauracje).
Agent widzi wolne terminy w Twoim kalendarzu i zapisuje w nim wizyty - logujesz się raz, bez kluczy API
Pozwól rozmówcom umawiać wizyty bezpośrednio w trakcie rozmowy przez Cal.com
### Leady i oddzwanianie
Agent może sam zadzwonić do nowego klienta: do osoby, która wypełniła
[formularz na stronie](/pl/integrations/leads/lead-webhook) albo
[formularz Google Ads](/pl/integrations/leads/ad-leads), zostawiła numer
w reklamie na Facebooku, LinkedInie czy TikToku ([szablony Make i
Zapier](/pl/integrations/leads/make-zapier)), pojawiła się jako [nowy kontakt
w HubSpot albo Pipedrive](/pl/integrations/leads/crm-leads) albo [nie
dodzwoniła się](/pl/integrations/leads/missed-calls) na Twój numer.
### CRM i automatyzacje
Agent może w trakcie rozmowy lub po niej: zapisywać leady w **HubSpot**,
**Pipedrive** lub **Dakteli**, wysyłać **SMS-y** i **e-maile** follow-up, powiadamiać na
**Slacku**, wyzwalać **Zapiera**, uruchamiać [workflow
**n8n**](/pl/integrations/n8n) albo [scenariusz **Make**](/pl/integrations/make)
(i słyszeć, co odpowiedzą) oraz wysyłać **webhooki** do dowolnego systemu
(własny backend). Potrafi też
czytać: **lookup w Google Sheets** w
trakcie rozmowy odpowiada na pytania na podstawie arkusza, który już
prowadzisz - patrz [Odczyt z arkusza w trakcie
rozmowy](#odczyt-z-arkusza-w-trakcie-rozmowy). Może też sprawdzić coś, czego
nikt mu nie wpisał - patrz [Szukanie w internecie w trakcie
rozmowy](#szukanie-w-internecie-w-trakcie-rozmowy). Zamówienia i stany
sklepu odczytuje z BaseLinkera - patrz [BaseLinker: zamówienia i stany
magazynowe](/pl/integrations/ecommerce/baselinker) - z Shopify, patrz
[Shopify: zamówienia i dostępność
produktów](/pl/integrations/ecommerce/shopify), z WooCommerce, patrz
[WooCommerce: zamówienia i dostępność
produktów](/pl/integrations/ecommerce/woocommerce) - albo wprost z konta
Allegro, patrz [Allegro: zamówienia i oferty](/pl/integrations/ecommerce/allegro).
Powiadomienie na Slacku, e-mail, Zapier i wpis do kalendarza agent potrafi
wykonać jeszcze w trakcie rozmowy - patrz [Slack, e-mail, Zapier i kalendarz w
trakcie rozmowy](#slack-e-mail-zapier-i-kalendarz-w-trakcie-rozmowy).
Konfigurację znajdziesz w panelu w zakładce **Integracje** oraz w
ustawieniach poszczególnych agentów.
#### SMS po rozmowie
Treść SMS-a piszesz w zakładce **Integracje** agenta. Pole ma menu **Wstaw
zmienną** - wybierasz z listy tego, co ten konkretny agent zbiera w rozmowie,
faktów o samym połączeniu (`{{caller_number}}`, `{{call_date}}`,
`{{call_time}}`, `{{call_duration}}`, `{{call_disposition}}`, `{{agent_name}}`)
i tego, co było znane przed rozmową - więc żadnej nazwy nie trzeba pamiętać.
Pod polem
widzisz, na ile płatnych SMS-ów rozbija się wiadomość, a gdy wyjdzie z jednej -
ostrzeżenie, że operator policzy ją tyle razy. Jeden SMS to 160 znaków, ale
już jeden polski ogonek skraca go do 70, o czym łatwo się przekonać dopiero na
fakturze. Licznik mierzy sam szablon; po podstawieniu zmiennych wiadomość
będzie dłuższa.
Streszczenia rozmowy nie da się wstawić do SMS-a. W szablonie to jedna zmienna,
a po wysyłce akapit - czyli trzy płatne wiadomości przy każdym połączeniu.
Gotowa wiadomość jest dodatkowo przycinana do 320 znaków, a pojedyncza zmienna
do 80.
#### Limit 10 SMS na godzinę z numeru plfon
Operator plfon przyjmuje z jednego numeru 10 SMS na godzinę. Kolejne nie
przepadają: platforma sama pilnuje limitu i odkłada nadmiar do kolejki, a SMS
wychodzi, gdy numer znów może wysyłać (najpóźniej po około godzinie).
W zakładce **SMS** taka wiadomość ma znacznik **W kolejce** z godziną
wysyłki, na ekranie rozmowy status „w kolejce”. Raz na godzinę na numer
dostajesz powiadomienie (dzwonek i e-mail, według Twoich ustawień), że SMS-y
czekają. Opłata za SMS jest pobierana w chwili wysyłki, nie dodania do
kolejki.
Jeśli w międzyczasie odbiorca odpisze `STOP` albo trafi na
[listę Nie dzwonić](/pl/features/contacts#lista-nie-dzwonić), SMS z kolejki
nie wychodzi i dostaje status „niewysłany”.
plfon nie wysyła potwierdzeń doręczenia, więc ostatni status SMS-a z numeru
plfon to **wysłany**: operator go przyjął. Czy telefon odbiorcy go dostał,
nie wiadomo. SMS-y z numerów Telnyx dostają status **doręczony** albo
**niedoręczony** od operatora.
#### SMS na stały numer (alert)
Drugi kierunek: wiadomość do Ciebie, nie do rozmówcy. W tej samej sekcji
włączasz **SMS na stały numer**, podajesz numer (kilka oddziel przecinkiem) i
piszesz treść alertu - np. `Połączenie {{call_time}} od {{caller_number}},
wynik: {{call_disposition}}`. Wybierasz też, kiedy alert ma iść: przy każdej
próbie, tylko po odebranych albo tylko po nieodebranych połączeniach.
Tylko w alercie działa `{{call_summary_short}}` - streszczenie przycięte do 140
znaków. Alert idzie z numeru agenta i jest rozliczany jak każdy inny SMS, więc
przy kilku odbiorcach płacisz za każdą wiadomość osobno.
Przycisk **Zaproponuj treść** czyta prompt systemowy agenta i proponuje kilka
gotowych wiadomości na różne cele rozmowy - potwierdzenie ustaleń,
podsumowanie z następnym krokiem, próbę kontaktu po nieodebranym połączeniu.
Każda propozycja mieści się w jednym SMS-ie - te dłuższe są odrzucane, zanim
je zobaczysz.
Propozycja wchodzi do pola dopiero, gdy ją wybierzesz, i nadal ją edytujesz.
Propozycje używają wyłącznie zmiennych, które naprawdę się wypełnią.
**Google Sheets** i kalendarze (Google, Outlook, Cal.com) działają już na
planie **Free** - agent zapisuje każdą rozmowę do Twojego arkusza i umawia
wizyty bez płacenia za nic. E-mail, Zapier, n8n, Make i webhooki zaczynają się
od planu **Start**, Slack i WhatsApp od **Pro**. Integracje CRM - **HubSpot**,
**Pipedrive** i **Daktela** - od planu **Business**.
## Szukanie w integracjach
Strona **Integracje** ma wyszukiwarkę (obok zakładek kategorii) i filtr
**Wszystkie / Połączone / Niepołączone**. Wyszukiwarka dopasowuje nazwę
dostawcy, opis i nazwę kategorii, więc „kalendarz" albo „arkusz" znajdzie
właściwy kafelek bez znajomości marki. Przy aktywnym wyszukiwaniu nagłówki
kategorii znikają, a wyniki układają się jednym gridem.
Ta sama para - wyszukiwarka i filtr **Wszystkie / Włączone / Wyłączone** - jest
w zakładce **Integracje** agenta, nad kartami akcji. Karty wyłączone stoją po
dwie w wierszu; włączona rozwija się na całą szerokość, bo tam pojawiają się jej
ustawienia.
## Zapis sprawdza połączenie
Przycisk **Zapisz połączenie** najpierw sprawdza podane dane u dostawcy, a
dopiero potem cokolwiek zapisuje. Jeśli sprawdzenie się nie powiedzie, nic nie
zostaje zapisane, a pod formularzem zobaczysz konkretny powód - na przykład
ucięty klucz prywatny albo arkusz nieudostępniony kontu serwisowemu.
Najczęstszy błąd przy Google Sheets to skopiowanie klucza prywatnego z pliku
JSON. Platforma sama radzi sobie ze znakami `\n`, cudzysłowami i przecinkiem
na końcu, a nawet z wklejeniem całego pliku JSON w pole klucza - ale klucz
ucięty w połowie zostanie odrzucony przy zapisie, a nie dopiero przy pierwszej
rozmowie.
Jeśli wiesz, że sprawdzenie jeszcze nie może przejść (np. arkusz udostępnisz
później), użyj przycisku **Zapisz mimo to**.
**Zapisz mimo to** nie przepuści klucza konta serwisowego Google, którego w
ogóle nie da się odczytać (uszkodzony, ucięty, to nie jest klucz prywatny):
połączenie nie zostanie zapisane, a formularz powie, co jest nie tak z
kluczem. Taki klucz nigdy nie dostanie tokenu, więc jego zapis przeniósłby
tylko błąd na każdą rozmowę. Zmiana nazwy istniejącego połączenia albo jego
domyślnej zakładki nie sprawdza klucza ponownie.
### Co sprawdza która integracja
| Integracja | Co sprawdzamy |
| - | - |
| **Google Sheets** | Podpisujemy się kluczem, otwieramy arkusz i **pytamy o prawo zapisu** - dopisujemy zero wierszy, więc w arkuszu nic nie przybywa. Arkusz udostępniony jako *Przeglądający* jest odrzucany od razu, a nie dopiero po pierwszej rozmowie. Osobno rozpoznajemy wyłączone Google Sheets API w projekcie Google Cloud. |
| **Cal.com** | Sprawdzamy klucz, a potem pytamy Cal.com o wolne terminy tego typu wydarzenia - czyli to samo, o co pyta rezerwacja w trakcie rozmowy. Typy wydarzeń należące do **zespołu** przechodzą tak samo jak prywatne. |
| **E-mail (SMTP)** | Logujemy się na konto, nic nie wysyłając. Działa i port **587** (STARTTLS), i **465** (SSL/TLS) - ten drugi podaje większość polskich hostingów. |
| **HubSpot** | Uprawnienia tokenu, odczytane z HubSpota - brakujące są wypisane po nazwie, zob. [Podłączenie HubSpota](#pod%C5%82%C4%85czenie-hubspota). |
| **Pipedrive** | Odczyt konta tym samym zapytaniem, którego agent używa w trakcie rozmowy. |
| **Daktela** | Kim jest użytkownik API tego tokenu, a potem lista kategorii zgłoszeń - komunikat wypisuje ich nazwy, bo nową kategorię trzeba wpisać w połączeniu po nazwie. Wpisana kategoria, której nie ma, jest zgłaszana tutaj, a nie po rozmowie. |
| **Kalendarz Google, Outlook** | Odczyt najbliższych 7 dni z połączonego konta oraz poprawność godzin i strefy czasowej. Wygasłe logowanie jest nazwane wprost. Starsze połączenie Google przez webhook: tylko poprawność adresu, bo test tworzyłby prawdziwe wydarzenie. |
| **Slack, Zapier, n8n, Make, webhooki** | Dostarczenie wiadomości testowej, patrz niżej. Dla n8n i Make z nagłówkiem sekretu, a adres testowy (`/webhook-test/`) jest nazwany jako taki. |
Slack, Zapier, n8n, Make i webhooki nie mają odczytu, więc jedynym sposobem sprawdzenia
jest wysłanie wiadomości. Przy pierwszym zapisie i po każdej zmianie adresu
zobaczysz na kanale wiadomość testową; sama zmiana nazwy połączenia niczego
nie wysyła.
## Podłączenie HubSpota
HubSpot wycofał stare klucze API, więc połączenie korzysta z **tokenu
prywatnej aplikacji**. Utwórz ją w HubSpocie w **Settings > Integrations >
Private Apps**, a w zakładce **Scopes** zaznacz wszystkie trzy uprawnienia:
| Uprawnienie | Do czego służy |
| - | - |
| `crm.objects.contacts.read` | Wyszukanie kontaktu w trakcie rozmowy, żeby agent rozpoznał dzwoniącego |
| `crm.objects.contacts.write` | Zapis po rozmowie, czyli utworzenie lub aktualizacja kontaktu |
| `crm.schemas.contacts.read` | Lista pól w mapowaniach agenta, żeby pokazały się Twoje własne właściwości kontaktu |
| `crm.objects.calls.write` | Zapis rozmowy na osi czasu kontaktu. W starszych prywatnych aplikacjach mieści się w `crm.objects.contacts.write`, więc jeśli nie ma go na liście uprawnień, nic nie dodawaj |
Zapisz aplikację, skopiuj jej token dostępu (zaczyna się od `pat-`) i wklej go
w połączeniu.
**Zapisz połączenie** odczytuje uprawnienia tokenu z HubSpota i wypisuje te,
których brakuje - token z samym odczytem kontaktów zostanie odrzucony już tutaj,
a nie dopiero po pierwszej prawdziwej rozmowie. Późniejsze dodanie uprawnienia
nie wymaga nowego tokenu - zaznacz je w HubSpocie, zapisz aplikację i kliknij
**Testuj połączenie**.
Bez `crm.objects.contacts.write` każdy zapis kończy się błędem
`403 This app hasn't been granted all required scopes` i żaden kontakt nie
powstaje. To najczęstszy problem z HubSpotem, a widać go w panelu
**Integracje** przy rozmowie.
## Mapowanie pól po rozmowie
CRM i Google Sheets zapisują dane po zakończonej rozmowie według mapowań,
które ustawiasz w konfiguracji agenta, w zakładce **Integracje**. Każde
mapowanie to trzy elementy:
| Element | Znaczenie |
| - | - |
| **Źródło** | Nazwa zmiennej z rozmowy lub z kontekstu początkowego. |
| **Kontekst** | `gathered` - dane zebrane przez agenta w trakcie rozmowy; `initial` - dane znane przed rozmową (zmienne agenta, `phone_number`, `campaign_id`, kolumny z kampanii); `call` - to, co platforma ustala **po** rozmowie, zob. niżej. |
| **Pole / kolumna** | Właściwość kontaktu w CRM albo kolumna w arkuszu. |
Nie musisz przepisywać nazw z pamięci - kliknij strzałkę w polu **Źródło**,
a zobaczysz listę zmiennych dostępnych dla wybranego kontekstu (dla
`gathered` razem z opisem, co agent ma ustalić). Listę zbieranych danych
znajdziesz i edytujesz w zakładce **Zmienne** - zob.
[Zmienne szablonowe](/pl/voice-agent/template-variables).
Żadnej z tych nazw nie trzeba pamiętać. Strzałka w polu **Źródło** pokazuje
zmienne dostępne w wybranym kontekście, a w polu **Do którego pola CRM** -
prawdziwe pola kontaktu z Twojego HubSpota, Pipedrive lub Dakteli, razem z ich etykietami
i polami własnymi. Przycisk **Dopasuj pola z CRM** wypełnia za jednym razem
wszystko, co da się rozpoznać po nazwie albo etykiecie. Nazwa pola pomylona o
jeden znak jest przyjmowana przez formularz i po cichu odrzucana przez CRM po
rozmowie - dlatego warto wybierać z listy.
### Nowy kontakt czy aktualizacja istniejącego
Zapis do HubSpota nigdy nie tworzy drugiego kontaktu dla kogoś, kto już jest w
CRM. Zanim cokolwiek powstanie, platforma szuka kontaktu w tej kolejności:
1. **Numer telefonu** - najpierw taki, jaki przyszedł z rozmowy, potem w postaci
E.164 (`+48537666648`) i w samych cyfrach, więc numer wpisany w HubSpocie ze
spacjami czy myślnikami też zostanie znaleziony. Sprawdzane są pola `phone`,
`mobilephone` oraz `hs_calculated_phone_number`, czyli znormalizowana kopia
HubSpota.
2. **Adres e-mail** - dopiero gdy numer nikogo nie znalazł, albo gdy rozmowa nie
ma numeru dzwoniącego (widget na stronie).
Numer idzie pierwszy celowo: przychodzi z sieci telefonicznej, a adres e-mail
agent usłyszał w rozmowie i zapisał z transkrypcji, więc jedna pomylona litera
zrobiłaby duplikat.
Kontakt znaleziony w ten sposób jest **aktualizowany** - nadpisywane są tylko te
właściwości, które masz w mapowaniach i które w tej rozmowie nie były puste;
reszta zostaje bez zmian. Gdy nie znajdzie się nikt, powstaje nowy kontakt.
Dopasowanie wymaga uprawnienia `crm.objects.contacts.read`. Token bez niego
nadal zapisuje, ale nie potrafi rozpoznać istniejącego kontaktu i za każdym
razem tworzy nowy.
### Rozmowa na osi czasu kontaktu
Sam zapis właściwości mówi, co się zmieniło, ale nie mówi, o czym była rozmowa.
Dlatego po zapisie kontaktu platforma dokłada mu **aktywność typu rozmowa** -
tę samą, którą HubSpot pokazuje w **Recent activities** na karcie kontaktu:
* podsumowanie rozmowy,
* kolejne kroki z listy zadań,
* wynik, nastawienie, tematy i nazwa agenta,
* link do nagrania,
* czas trwania i kierunek połączenia, w polach, które HubSpot sam wyświetla.
Aktywność jest zawsze podpinana pod kontakt, na którym właśnie zapisywaliśmy
dane. Jeśli HubSpot ją przyjmie, ale odmówi podpięcia, zostaje skasowana - nie
chcemy zostawiać w CRM notatek, których z kontaktu nie widać.
Przełącznik **Zapisz rozmowę na kontakcie** w zakładce **Integracje** agenta
wyłącza to zachowanie. Zapis aktywności nigdy nie psuje zapisu kontaktu: gdy
token nie ma uprawnień do aktywności, kontakt i tak się zapisze, a powód
odmowy zobaczysz w panelu **Integracje** przy rozmowie.
### Kiedy zapis się odpala
Każda karta zapisu po rozmowie ma dwa filtry:
* **Kiedy wysyłać dane** - *Po każdej próbie połączenia (także nieodebranej)*
albo *Tylko gdy rozmowa się odbyła*. Nieodebrane i zajęte zdarzają się tylko
w kampaniach wychodzących: przy połączeniach przychodzących obie opcje znaczą
to samo. W kampanii z ponowieniami pierwsza opcja zapisze kilka wpisów dla
tego samego numeru.
* **Tylko przy wybranym wyniku rozmowy** - lista pokazuje wyniki, które ten
agent **już zapisał** w swoich rozmowach (np. „umówiono wizytę", „brak
zainteresowania"). To nie są narzędzia ani kroki scenariusza. Wynik, który
jeszcze nie wystąpił, możesz dopisać ręcznie.
### Dane z podsumowania rozmowy (kontekst `call`)
To, co widzisz w historii połączeń - podsumowanie, zadania do wykonania,
intencje, nastawienie - możesz zapisywać do arkusza albo do CRM tak samo jak
zwykłe pola. Wybierz kontekst **`call`**, a lista podpowie dostępne pozycje:
| Źródło | Co trafia do komórki |
| - | - |
| `summary` | Podsumowanie rozmowy wygenerowane przez AI |
| `action_items` | Zadania do wykonania, każde w osobnej linii |
| `intents` | Intencje rozmówcy, po przecinku |
| `topics` | Poruszone tematy, po przecinku |
| `sentiment` / `sentiment_score` | Nastawienie i jego wynik od -1 do 1 |
| `success` / `success_reason` | Czy cel rozmowy osiągnięty (PRAWDA/FAŁSZ) i dlaczego |
| `call_date` / `call_time` | Data i godzina rozmowy |
| `duration_seconds` | Czas trwania w sekundach |
| `phone_number` / `disposition` | Numer rozmówcy i status rozmowy |
| `recording_url` / `transcript_url` | Linki do nagrania i transkrypcji. Nie wygasają; przestają działać po usunięciu rozmowy albo pliku przez politykę retencji. Każdy, kto ma link, może otworzyć plik |
| `call_id` / `agent_name` | ID rozmowy i nazwa agenta |
ID rozmowy znajdziesz w aplikacji w kolumnie **ID** historii rozmów oraz
w nagłówku samej rozmowy, gdzie kliknięcie kopiuje je do schowka.
Podsumowanie i analiza powstają w tle już po zakończeniu rozmowy. Gdy któreś
mapowanie ich używa, platforma **czeka na wynik** przed zapisem do arkusza, więc
kolumny nie przychodzą puste. Jeśli żadne mapowanie ich nie używa, analiza nie
jest wymuszana i nic Cię to nie kosztuje.
### Google Sheets
Po wskazaniu połączenia platforma odczytuje sam arkusz, a formularz mapowań
staje się tym arkuszem: **jedna linia na każdą prawdziwą kolumnę**, a przy niej
jedna decyzja - co ma tam trafić albo nic. Nie ma nazwy kolumny do wpisania,
więc nie ma czego pomylić. Dodasz kolumnę w arkuszu - **Odśwież kolumny**
wciągnie ją tutaj; **Dopasuj kolumny z arkusza** wypełnia za jednym razem
wszystko, co da się rozpoznać po nazwach kolumn.
Kolumny dopasowywane są do tego, co agent zbiera, po nazwie albo po pytaniu,
które za nią stoi - kolumna `email` i `Adres e-mail` trafią na tę samą zmienną.
Mapowanie wskazujące kolumnę, której nie ma w arkuszu, jest oznaczane, a nie po
cichu usuwane. Takie mapowania zbierają się w ramce **„Brakuje tych kolumn w
arkuszu"**: przy każdym widać nazwę nagłówka do dodania (z przyciskiem kopiowania,
a **Kopiuj wszystkie nagłówki** kopiuje je rozdzielone tabulatorem, do wklejenia
w pierwszy wiersz arkusza jednym ruchem) oraz opis tego, co się w niej znajdzie -
np. „Data rozmowy (Podsumowanie rozmowy). To zmienna systemowa - platforma
wylicza ją sama po rozmowie.". Dodaj nagłówek w arkuszu, kliknij **Odśwież
kolumny**, a mapowanie przeskoczy do listy zwykłych kolumn.
Jeśli odczyt się nie powiedzie (błędne konto serwisowe lub ID arkusza, brak
udostępnienia arkusza kontu serwisowemu), pola nadal działają jako zwykły
tekst - wpiszesz nazwy ręcznie.
### Jak wiersz trafia do kolumn
Mapowania to lista i domyślnie wiersz dopisywany jest w jej kolejności: pierwsze
mapowanie ląduje w kolumnie A, drugie w B i tak dalej. Wpisana nazwa kolumny jest
wtedy tylko etykietą dla Ciebie.
To przestaje działać, gdy arkusz nie trzyma tej samej kolejności - ktoś wstawił
kolumnę, zamienił dwie miejscami albo zbudował arkusz ręcznie z nazw zmiennych z
zakładki **Zmienne**. Dlatego platforma najpierw czyta wiersz nagłówkowy i jeśli
rozpozna **każdą opisaną kolumnę**, zapisuje wartości pod ich własnymi
nagłówkami, w dowolnej kolejności. Kolumna jest rozpoznana, gdy jej nagłówek to:
* **nazwa kolumny** podana w mapowaniu, albo
* **źródło** mapowania (`name`, `email`, `call_date`, ...), albo
* nazwa **zmiennej zebranej w rozmowie** - kolumna o nagłówku
`jaki_ma_wolumen_polaczen` wypełnia się sama, bez mapowania.
Mapowanie, które nie ma swojej kolumny, nie jest zapisywane: arkusz nie ma na nie
miejsca. Wystarczy jedna nierozpoznana kolumna, a cały wiersz wraca do kolejności
mapowań, więc arkusz działający dzisiaj działa dalej tak samo.
Mapowania **nie** powstają automatycznie z Twoich zmiennych po utworzeniu agenta.
Domyślna lista budowana jest raz, przy tworzeniu agenta, z pól wybranych w
kreatorze. Zmienna dodana później trafi do arkusza albo po dodaniu dla niej
mapowania, albo gdy nazwiesz kolumnę dokładnie tak jak ją.
### Logowanie przez Google
Najprostsze połączenie z arkuszem to logowanie: **Integracje** → **Google
Sheets** → **Zaloguj się przez Google** i wybierz konto, które może edytować
arkusz. Zaraz po powrocie z Google otworzy się lista arkuszy tego konta -
wybierz ten, do którego agent ma zapisywać, a jego nazwa pojawi się przy
połączeniu. Nie trzeba zakładać projektu w Google Cloud ani niczego
udostępniać.
BrosBots ma dostęp **tylko do arkuszy wybranych z tej listy**, nie do całego
Dysku Google. Dlatego arkusz wybierasz przyciskiem **Wybierz arkusz**, a nie
przez wklejenie adresu: wklejony adres zadziała tylko dla arkusza, który był już
wcześniej wybrany z listy. Ten sam przycisk jest:
* przy połączeniu w **Integracje** → **Google Sheets** (arkusz domyślny),
* w edytorze agenta: **Integracje** → kafelek arkusza, notatka albo
wyszukiwanie → **Arkusz tego agenta** (inny arkusz dla tego agenta; puste
pole = arkusz z połączenia),
* w kreatorze agenta przy adresie arkusza,
* w nowej kampanii ze źródłem **Arkusz Google**.
Edytor pokazuje nazwę arkusza, z którego czyta kolumny, więc widać, czy to ten
właściwy. Pod wybranym arkuszem (przy połączeniu i w edytorze agenta) jest
**Pokaż podgląd arkusza**: nagłówki i 5 ostatnich wierszy wybranej zakładki, z
przełącznikiem zakładek i linkiem do Google Sheets. Najnowsze wiersze to te,
które dopisał agent, więc tu od razu widać, czy rozmowy trafiają do właściwego
arkusza. Po wyborze arkusza z listy podgląd otwiera się sam. Gdy logowanie wygaśnie albo dostęp zostanie cofnięty, dostaniesz
powiadomienie z przyciskiem **Zaloguj się ponownie**.
Połączenie zalogowane przed wprowadzeniem listy arkuszy pokazuje komunikat
„To połączenie powstało przed wyborem arkusza z listy”. Kliknij **Zaloguj się
ponownie** i wybierz arkusze z listy jeszcze raz - przy połączeniu i w każdym
agencie, który ma własny arkusz.
Nowe połączenie z Google Sheets powstaje tylko przez logowanie przez Google -
formularza konta serwisowego (e-mail i klucz prywatny) nie ma już ani na
stronie Integracje, ani w kreatorze agenta. Wklejany klucz był jedynym
sposobem podłączenia, który regularnie zawodził przy prawdziwych rozmowach.
Połączenia z kontem serwisowym zrobione wcześniej działają dalej, a ich
formularz otwiera się przy edycji; zmieniony w nim klucz jest sprawdzany przy
zapisie. Żeby przenieść takie połączenie, edytuj je i kliknij **Zaloguj się przez
Google** - połączenie zachowuje swój identyfikator, więc agenci, którzy z niego
korzystają, działają dalej.
### Udostępnij arkusz kontu serwisowemu
Dotyczy połączeń z kontem serwisowym zrobionych przed logowaniem przez Google.
Konto serwisowe to osobny użytkownik Google i na start nie ma dostępu do
niczego. Samo utworzenie klucza nie wystarczy: otwórz arkusz, kliknij
**Udostępnij**, wklej **Service Account Email**
(`...@....iam.gserviceaccount.com`) i nadaj mu rolę **Edytor**.
To krok pomijany najczęściej - dopóki go nie zrobisz, każdy zapis kończy się
odmową `403 PERMISSION_DENIED`.
## Notatka w trakcie rozmowy
**Zapisz notatkę w Google Sheets**, w zakładce **Integracje** agenta, dopisuje
wiersz jeszcze na linii - prośbę o kontakt, wiadomość do przekazania, cokolwiek,
co ktoś musi później obsłużyć. Korzysta z tego samego połączenia co zapis po
rozmowie.
| Pole | Do czego służy |
| - | - |
| **Zakładka arkusza** | Gdzie trafiają notatki. Nie masz jeszcze takiej zakładki? Przycisk **Utwórz zakładkę** zakłada ją razem z wierszem nagłówków (data i godzina, telefon, imię i nazwisko, notatka) i od razu mapuje kolumny. |
| **Co ma znaleźć się w notatce** | Własnymi słowami, np. „Zanotuj, kto prosi o kontakt, w jakiej sprawie i kiedy jest dostępny.". Trafia wprost do agenta - im konkretniej, tym mniej notatek w stylu „klient dzwonił". |
| **Zwroty, po których agent zapisuje notatkę** | Przykłady w rodzaju „poproś żeby ktoś oddzwonił". Agent dopasowuje **sens**, nie dosłowne słowa. Bez nich pisze notatki raz na jakiś czas i nie sposób przewidzieć kiedy. |
| **Zbierz dane kontaktowe przed zapisem** | Agent dopyta o imię, nazwisko i numer do oddzwonienia, i powtórzy numer do potwierdzenia. |
| **Kolumny arkusza** | Jedna linia na każdą prawdziwą kolumnę zakładki. Przy każdej wybierasz, co ma tam trafić: notatka, imię i nazwisko, telefon, temat, data i godzina, albo zmienna zbierana w rozmowie. **Dopasuj automatycznie** wypełnia to, co da się rozpoznać po nazwach. |
Kolumny decydują też, o co agent pyta: zmapujesz kolumnę na imię i nazwisko -
narzędzie dostaje argument, który model musi wypełnić; nie zmapujesz - agent
nigdy o nie nie pyta. Data, godzina i numer dzwoniącego uzupełniają się same z
kontekstu rozmowy (model zapytany o godzinę ją zmyśla). Wiersz układany jest
według nagłówków arkusza, więc przestawienie kolumn w Google Sheets niczego nie
psuje, a kolumna skonfigurowana, ale nieobecna w zakładce, wraca do agenta i do
logu zamiast zniknąć po cichu.
## Odczyt z arkusza w trakcie rozmowy
Wszystko powyżej zapisuje. **Wyszukaj wiersz w Google Sheets**, w zakładce
**Integracje** agenta, działa w drugą stronę: agent czyta arkusz, gdy rozmówca
jest jeszcze na linii - status zamówienia, rezerwację, dane klienta, cenę.
Korzysta z tego samego połączenia co zapis, więc nie trzeba niczego dodatkowo
autoryzować.
Zanim to powstało, jedynym obejściem był webhook n8n albo Make postawiony przed
tym samym arkuszem - narzędzie HTTP samo nie wygeneruje tokenu konta serwisowego
Google. To nadal działa i nadal jest odpowiedzią na wszystko, czego zwykły
odczyt wiersza nie zrobi (zapis zwrotny, łączenie dwóch arkuszy, filtrowanie po
kilku kolumnach naraz) - ale do "znajdź wiersz i powiedz, co w nim jest"
webhook nie jest już potrzebny.
### Co ustawić
| Pole | Do czego służy |
| - | - |
| **Połączenie** | Które połączenie Google Sheets ma być czytane. |
| **Zakładka do przeszukania** | Zakładka, w której agent szuka. Zostaw puste, aby użyć zakładki z połączenia - przydatne, gdy agent zapisuje do `Rozmowy`, a czyta z `Zamówienia`. |
| **Co zawiera ten arkusz** | Jedno zdanie własnymi słowami, np. "Statusy zamówień. Szukaj po numerze zamówienia, który poda rozmówca." Trafia do agenta, żeby wiedział, *kiedy* zajrzeć do arkusza. |
Wypełnij **Co zawiera ten arkusz**. Samo włączenie narzędzia nie wystarczy -
agent, któremu nikt nie powiedział, że arkusz istnieje, odpowie "nie mam takiej
informacji" zamiast sprawdzić. To właśnie to pole sprawia, że sprawdza.
### Jak znajdowany jest wiersz
Wiersz 1 to nagłówki. Wszystko poniżej to dane, a agent szuka wartości podanej
przez rozmówcę - numeru zamówienia, e-maila, kodu - we wszystkich kolumnach albo
w jednej wskazanej. Znaleziony wiersz wraca jako pary nazwa kolumny / wartość,
więc agent może odpowiedzieć dowolnym polem z niego.
Dwie rzeczy są celowo pobłażliwe:
* **Wielkość liter i spacje nie mają znaczenia**, więc `ANNA KOWALSKA` znajdzie
`Anna Kowalska`.
* **Numery telefonów porównywane są po ostatnich dziewięciu cyfrach.** Caller ID
przychodzi jako `+48601234567`, a w arkuszu jest to, co komu wygodniej -
`601-234-567`, `0048 601 234 567`. Wszystkie trafią w ten sam wiersz.
Wywołany bez żadnej wartości, lookup szuka **numeru samego dzwoniącego**, więc
agent odbierający połączenie może rozpoznać stałego klienta, zanim o cokolwiek
zapyta.
### Ograniczenia
Arkusz nie ma silnika zapytań, więc lookup czyta zakładkę i ją przeszukuje. Przy
arkuszach, na których realnie stawia się agentów - do kilku tysięcy wierszy - to
w porządku, a każde wyszukanie dokłada do rozmowy mniej więcej pół sekundy.
Przeszukiwanie zatrzymuje się na **5000 wierszy**. Powyżej agent dostaje
informację, że arkusz został odczytany tylko częściowo, zamiast odpowiadać "nie
znaleziono" na podstawie połowy danych. Arkusz tej wielkości to sygnał, że dane
powinny być w bazie, a agent powinien sięgać do nich narzędziem HTTP API.
| Co mówi agent | Co to znaczy | Co zrobić |
| - | - | - |
| "Nie udało mi się odczytać arkusza" | Zły Spreadsheet ID albo arkusz nie jest udostępniony kontu serwisowemu | Udostępnij go na Service Account Email jako **Edytor**, sprawdź ID |
| Nic nie znajduje, choć wiersz tam jest | Przeszukiwana jest inna zakładka niż ta, na którą patrzysz | Ustaw **Zakładkę do przeszukania** wprost |
| Odpowiada z własnej wiedzy zamiast sprawdzić | Agentowi nigdy nie powiedziano, do czego jest ten arkusz | Wypełnij **Co zawiera ten arkusz** |
| Znajduje wiersz, ale czyta złe pole | Dwie kolumny mają ten sam nagłówek | Nadaj im różne nagłówki - duplikaty wracają jako `Telefon` i `Telefon (2)` |
## Slack, e-mail, Zapier i kalendarz w trakcie rozmowy
Sześć akcji z zakładki **Integracje** agenta wykonuje się jeszcze na linii:
**Powiadomienie Slack**, **Wyślij e-mail**, **Wyzwalacz Zapier**, **Workflow
n8n**, **Scenariusz Make** i **Umów spotkanie**. Ustawia się je tak samo jak
notatkę - poza wyborem połączenia mówisz agentowi, kiedy ma z akcji
skorzystać i co ma w niej napisać. Workflow n8n i scenariusz Make jako jedyne
potrafią odpowiedzieć: to, co odpowiedzą, agent przekazuje rozmówcy - patrz
[n8n](/pl/integrations/n8n) i [Make](/pl/integrations/make).
| Pole | Do czego służy |
| - | - |
| **Kiedy i co wysłać** | Własnymi słowami, np. „Wyślij powiadomienie, gdy dzwoni klient zainteresowany ofertą powyżej 10 tys. Napisz, czego dotyczy i na kiedy oczekuje odpowiedzi.". Trafia do agenta razem z narzędziem. |
| **Zdania, po których ma zadziałać** | Przykłady w rodzaju „chcę rozmawiać z handlowcem". Agent dopasowuje **sens**, nie dosłowne słowa. |
| **Dołącz dane rozmowy** (Slack, e-mail) | Do wiadomości dopisywany jest numer dzwoniącego, nazwa agenta i ID rozmowy. Agent ich nie podaje, więc nie może ich zmyślić. W Slacku domyślnie włączone, w e-mailu wyłączone. |
| **Domyślny odbiorca** (e-mail) | Adres, na który idzie poczta, gdy nikt nie poda go w rozmowie. Agent przestaje wtedy o niego pytać. |
| **Domyślny temat** (e-mail) | Używany, gdy agent nie poda własnego tematu. Bez tego temat powstaje od nowa przy każdej rozmowie. |
Zostaw oba pierwsze pola puste przy **Wyślij e-mail**, **Wyzwalaczu Zapier**,
**Workflow n8n**, **Scenariuszu Make** albo **Umów spotkanie**, a narzędzie działa jak wcześniej: agent sam decyduje,
czy go użyć - i w praktyce robi to rzadko. Model, który dostał narzędzie bez
informacji, po co je ma, zwykle mówi „przekażę zespołowi" i nic nie wysyła.
Jeśli te akcje się nie odpalają, to pierwsza rzecz do sprawdzenia.
**Powiadomienie Slack** jest wyjątkiem. Włączone z pustymi polami dostaje
polecenie, żeby przed końcem rozmowy wysłać krótką notatkę o tym, czego
dzwoniący chciał i co zostało ustalone. Wypełnione pola zastępują tę domyślną
treść Twoimi słowami.
Rozmowa nie rozłącza się, dopóki akcja rozpoczęta w tej samej turze się nie
zakończy - notatka na Slacka wysyłana w chwili, gdy dzwoniący się żegna, nie
zostanie przerwana w połowie.
Powiadomienie Slack i e-mail wysłane w trakcie rozmowy zapisują się w panelu
**Integracje** przy rozmowie, tak samo jak wysyłki po rozmowie - wiadomość,
której agent nigdy nie wysłał, i wiadomość odrzuconą przez Slacka widać tam
osobno.
Powiadomienie **po rozmowie** to osobna integracja, ustawiana w tej samej
zakładce (podsumowanie, wynik i nagranie na kanał). Obie mogą działać naraz:
akcja w trakcie rozmowy alarmuje o tym, co dzieje się na linii, a wysyłka po
rozmowie podsumowuje.
## Komu agent może wysłać SMS, WhatsApp i e-mail
Odbiorcę SMS-a, wiadomości WhatsApp, linku do płatności i e-maila w trakcie
rozmowy wybiera model. Żeby tekst wgrany do bazy wiedzy, strona znaleziona w
sieci albo sam rozmówca nie namówił agenta do wysyłki pod obcy numer czy adres,
obowiązują dwie zasady:
* **Odbiorca.** SMS, WhatsApp i link do płatności idą tylko na numer rozmówcy i
na numery wpisane w polu **Dodatkowi dozwoleni odbiorcy**. E-mail idzie tylko
na **Domyślnego odbiorcę**, adresy z tej samej listy i adres kontaktu z danych
rozmowy (lead, kontakt kampanii). Inny odbiorca jest odrzucany, a agent mówi
rozmówcy, że wiadomość nie wyszła.
* **Limit na rozmowę.** Najwyżej 3 SMS-y (linki do płatności się wliczają),
3 wiadomości WhatsApp i 3 e-maile w jednej rozmowie.
Jeśli agent ma wysyłać na numer albo adres podyktowany w rozmowie (np. „proszę
wysłać ofertę na [jan@firma.pl](mailto:jan@firma.pl)"), włącz przy akcji **Pozwól wysyłać na adresy
podane w rozmowie**. Limit na rozmowę obowiązuje także wtedy.
Agenty sprzed 19.10.2026, które wysyłały e-mail na adres podany przez
rozmówcę, po tej zmianie potrzebują tego przełącznika - inaczej e-mail
zostanie odrzucony.
## Gdy nic się nie zapisało
Odpowiadają na to dwa miejsca, każde na inne pytanie:
* **Konkretna rozmowa** - otwórz ją w historii rozmów. Panel **Integracje**
obok transkrypcji pokazuje, co każda integracja zrobiła z tą rozmową i
dlaczego nie zapisała wiersza, jeśli go nie zapisała. Przy udanym zapisie
jest zdanie z miejscem zapisu (np. „Row written to 'Leady' (row 42)"), a pod
nim **Show what was sent** rozwija wszystkie wartości, które poszły do
poszczególnych kolumn albo pól CRM - tak samo jak dane rozmowy wyżej.
* **Integracja włączona, ale bez żadnego wyniku dla tej rozmowy** - panel
oznacza to na żółto. Znaczy to, że zadanie po rozmowie nie doszło do tej
integracji (błąd albo przekroczony czas), a nie że nic nie było skonfigurowane.
* **Połączenie w ogóle** - **Ostatnie wysyłki** na stronie Integracje listują
próby z całej organizacji, od najnowszych.
Każda próba kończy się jednym z trzech stanów: **zapisano**, **błąd** (z
treścią błędu) albo **pominięto** - integracja jest włączona, ale rozmowa nie
pasowała do jej wyzwalacza lub filtra wyniku, więc nic nie miało powstać.
### Ponowienia i przycisk Ponów
Zapisy do HubSpota, Pipedrive, Daktela i Google Sheets same ponawiają próbę,
gdy usługa dostawcy jest chwilowo niedostępna: przy odpowiedzi `429` (za dużo
zapytań), `500`, `502`, `503`, `504`, przy nieudanym połączeniu albo przekroczonym
czasie odczytu. Każde zapytanie ma najwyżej trzy próby, w odstępie kilku
sekund; na `Retry-After` dłuższe niż 10 sekund zapis nie czeka. Jeśli zapis
potrzebował więcej niż jednej próby, panel Integracje rozmowy podaje ile.
Błędy, które same nie miną - cofnięty klucz (`401`), brak uprawnień (`403`),
dane odrzucone przez CRM (`400`) - nie są ponawiane. Nie jest też ponawiany
zapis kontaktu albo wiersza, któremu skończył się czas w połowie: mógł dojść,
a drugi raz zrobiłby duplikat.
Przy zapisie, który mimo to się nie udał, w panelu Integracje rozmowy jest
przycisk **Ponów**. Uruchamia ponownie tylko ten jeden zapis - nie SMS-a,
WhatsAppa, Slacka ani webhooków tej samej rozmowy - a wynik pojawia się w
panelu jako nowy wiersz po kilku sekundach. Zapis do CRM najpierw szuka
kontaktu, więc ponowienie zaktualizuje kontakt, który wcześniejsza próba mogła
już założyć, zamiast dodać drugi. Przycisk jest tylko przy najnowszym wyniku
danego zapisu: starszego błędu, który późniejsza próba już naprawiła, nie da
się powtórzyć.
| Co widzisz | Co to znaczy | Co zrobić |
| - | - | - |
| HubSpot `403` „This app hasn't been granted all required scopes” | Tokenowi prywatnej aplikacji brakuje uprawnienia | Dodaj `crm.objects.contacts.write` (i pozostałe dwa powyżej) w HubSpocie, zapisz aplikację i kliknij **Testuj połączenie** |
| `403` / brak dostępu do arkusza | Arkusz nigdy nie został udostępniony kontu serwisowemu | Udostępnij go adresowi Service Account Email jako **Edytor** |
| „The service account private key stored on this Google Sheets connection cannot be read” | Starsze połączenie z kontem serwisowym ma uszkodzony klucz | Edytuj połączenie i kliknij **Zaloguj się przez Google** albo wklej klucz ponownie z pliku JSON |
| HubSpot / Pipedrive / Daktela `429` albo `5xx` po 3 próbach | Dostawca był niedostępny dłużej, niż trwały ponowienia | Kliknij **Ponów** przy zapisie w panelu Integracje rozmowy |
| „BrosBots nie może otworzyć tego arkusza” (logowanie przez Google) | Arkusz nie został wybrany z listy (np. wklejony adres) | Kliknij **Wybierz arkusz** i wskaż go na liście. Jeśli go tam nie ma, konto nie może go edytować - poproś właściciela o udostępnienie |
| `403` z informacją o Sheets API | Sheets API jest wyłączone w projekcie Google Cloud | Włącz "Google Sheets API" w projekcie |
| `404` / brak arkusza o tym ID | Błędne Spreadsheet ID | Skopiuj fragment adresu arkusza między `/d/` a `/edit` |
| Zakładka nie istnieje | **Sheet name** nie pasuje do żadnej zakładki | Popraw nazwę zakładki w zakładce Integracje agenta |
| Brak mapowań kolumn | Połączenie działa, ale agent nie ma mapowań | Dodaj co najmniej jedno mapowanie w zakładce Integracje agenta |
| Wszystkie zmapowane pola puste | Mapowania wskazują nazwy, których ta rozmowa nie wypełniła | Zmapuj coś, co istnieje zawsze, np. `summary` lub `call_date` z kontekstu `call` |
| Pominięto: wyzwalacz / wynik | Filtr wykluczył tę rozmowę | Zmień **Wyzwalacz** lub listę wyników, albo zostaw tak jak jest |
| Zapisano, ale wiersza nie widać | Zapis poszedł do innego pliku albo daleko pod danymi | Kliknij link w opisie wysyłki - prowadzi do arkusza, a obok jest nazwa komórki, np. `Rozmowy!A2` |
| Nic w żadnej z list | Integracja jest wyłączona dla tego agenta | Włącz ją w zakładce Integracje agenta |
Wiersz trafia bezpośrednio pod ostatni wypełniony wiersz zakładki - puste
wiersze poniżej danych (a tak wygląda arkusz zbudowany na **Tabelach** Google
albo z importu) są pomijane. Wcześniej zapis szedł przez „append" Google, który
w takim arkuszu ląduje za całym zarezerwowanym obszarem tabeli, czyli
kilkaset wierszy pod nagłówkiem. Jeśli szukasz starszych rozmów, których nie
ma pod nagłówkiem, przewiń arkusz w dół - najpewniej są tam.
Rozmowy przez przeglądarkę (WebRTC) zapisują wiersze dokładnie tak samo jak
telefoniczne. Jedyna różnica to `call.phone_number`, które zostaje puste, bo nie
ma numeru do zapisania.
## Szukanie w internecie w trakcie rozmowy
Wszystko inne, co agent wie, ktoś mu wpisał: prompt, wgrane dokumenty, arkusz.
To wystarcza do cen i godzin otwarcia, a nie wystarcza do niczego, co zmieniło
się w tym tygodniu - jakie nabory są otwarte, co dziś mówi rejestr. **Szukaj w
internecie**, w zakładce **Integracje** agenta, jest jedynym narzędziem, którego
odpowiedzi nie ma w naszej bazie.
Pod spodem jest **Brave Search API**: płatne API z licencją na zwracanie
wyników, odpowiadające w jednym zapytaniu. Darmowy plan wystarcza na pojedyncze
sprawdzenia w rozmowie.
### Konfiguracja
1. Wejdź na [brave.com/search/api](https://brave.com/search/api), zarejestruj się
i wybierz plan.
2. Skopiuj token subskrypcji z zakładki **API Keys**.
3. W panelu: **Integracje** → **Brave Search** → wklej klucz. Opcjonalnie podaj
kraj (`PL`) i język zapytań (`pl`), żeby zawęzić wyniki do swojego rynku.
4. W agencie: zakładka **Integracje** → **Szukaj w internecie** → wybierz
połączenie.
| Pole | Do czego służy |
| - | - |
| **Połączenie** | Które połączenie Brave Search ma być używane. |
| **Czego ma szukać** | Jedno zdanie własnymi słowami, np. „Przed odpowiedzią o terminy sprawdź aktualne nabory na gov.pl". Trafia do promptu, więc agent wie, co warto sprawdzać. |
Bez wypełnienia **Czego ma szukać** agent i tak szuka, ale tylko wtedy, gdy sam
uzna, że nie zna odpowiedzi. To pole przesuwa granicę: mówi mu, w jakich
sprawach ma nie ufać własnej pamięci.
### Co agent dostaje
Tytuł, fragment opisu i źródło, do trzech wyników. Celowo nie pobieramy treści
stron: wczytanie i streszczenie trzech artykułów to kilka sekund ciszy w
słuchawce, a wynik i tak trzeba powiedzieć w dwóch zdaniach. Agent czyta
sedno, mówi skąd to ma i proponuje wysłanie linku SMS-em albo mailem, jeśli
włączyłeś te narzędzia.
Nieudane wyszukiwanie nie przerywa rozmowy. Wyczerpany limit, odrzucony klucz i
przekroczony czas wracają jako zdanie, które agent mówi na głos („nie udało mi
się tego sprawdzić"), zamiast ciszy albo zmyślonej odpowiedzi.
## AgentMail: własny adres agenta
Wysyłka przez SMTP i czytanie przez IMAP wymagają serwera, portu i hasła
aplikacji. To najczęstsze źródło błędów przy konfiguracji, a sprawdzić je można
dopiero wtedy, gdy coś nie zadziała. **AgentMail** zastępuje te dane jednym
kluczem API i daje agentowi własny adres.
### Konfiguracja
1. Wejdź na [agentmail.to](https://agentmail.to), zarejestruj się i skopiuj
klucz API. Darmowy plan to trzy skrzynki i 3000 wiadomości miesięcznie.
2. W panelu: **Integracje** → **AgentMail** → wklej klucz. Pole skrzynki zostaw
puste: przy zapisie zakładamy agentowi adres na `agentmail.to` albo używamy
tego, który już masz na tym kluczu.
3. Własna domena (`agent@twojafirma.pl`) podpina się w panelu AgentMail, razem z
rekordami DKIM, SPF i DMARC.
### Co to zmienia
| Zastosowanie | Wcześniej | Z AgentMail |
| - | - | - |
| Wysyłka e-maila w trakcie rozmowy | host, port, login i hasło aplikacji SMTP | klucz API |
| Poczta w codziennej odprawie | serwer IMAP, port, login i hasło | klucz API plus przekierowanie w Twojej poczcie |
W zakładce **Integracje** agenta lista połączeń przy narzędziu e-mail pokazuje
teraz zarówno połączenia SMTP, jak i AgentMail - agent wysyła tym, które
wybierzesz.
### Odprawa bez IMAP-a
W sekcji **Codzienna odprawa** doszło pole **Skąd czytać pocztę**: własna
skrzynka przez IMAP albo skrzynka agenta. Przy skrzynce agenta ustawiasz w
swojej poczcie przekierowanie na jego adres (Gmail: Ustawienia → Przekazywanie),
a odprawa czyta to, co przyszło - bez podawania nam jakiegokolwiek hasła.
AgentMail **nie czyta Twojego Gmaila**. Wydaje nowe skrzynki, więc istniejąca
poczta trafia do agenta przekierowaniem. Bezpośredni odczyt konta Google to
albo IMAP z hasłem aplikacji, albo aplikacja OAuth z corocznym audytem
bezpieczeństwa Google - stąd ten wybór.
### Gdy test mówi, że klucz został odrzucony
**Testuj połączenie** sprawdza najpierw klucz na liście skrzynek, więc
"AgentMail odrzucił ten klucz API" oznacza teraz klucz i nic innego. Dwie inne
odpowiedzi dotyczą pola **Inbox**:
| Co pisze | Co zrobić |
| - | - |
| Klucz działa, ale nie ma skrzynki `x`. Ma za to: … | Wklej jeden z wypisanych adresów albo wyczyść pole |
| Klucz działa, ale nie ma żadnej skrzynki | Wyczyść pole **Inbox** i zapisz - agent dostanie własną |
Jeśli klucz faktycznie jest odrzucany, sprawdź go z terminala - to dokładnie
to samo wywołanie, które robi test:
```bash theme={null}
curl -i -H "Authorization: Bearer TWOJ_KLUCZ_API" https://api.agentmail.to/v0/inboxes
```
`200` znaczy, że klucz jest dobry i problemem jest skrzynka. `401` znaczy, że
AgentMail nie zna tego klucza: wygeneruj nowy w panelu AgentMail i wklej go bez
spacji dookoła.
## Sklepy internetowe
Agent odpowiada na dwa pytania, z którymi dzwonią klienci sklepów: "gdzie jest
moje zamówienie" i "macie to na stanie". Odpowiedź czyta na żywo z systemu,
w którym prowadzisz sprzedaż:
* [BaseLinker](/pl/integrations/ecommerce/baselinker) - status zamówienia,
numer przesyłki oraz stany i ceny z katalogu BaseLinkera.
* [Shopify](/pl/integrations/ecommerce/shopify) - status realizacji, numer
przesyłki i dostępność wariantów przez aplikację niestandardową w Twoim
panelu.
* [WooCommerce](/pl/integrations/ecommerce/woocommerce) - zamówienia
i dostępność produktów ze sklepu na WordPressie przez klucze REST API
z uprawnieniem do odczytu.
* [Allegro](/pl/integrations/ecommerce/allegro) - zamówienia i aktywne oferty
z konta sprzedającego, połączonego jednym logowaniem, bez klucza do
wklejenia.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.