---
title: "Uruchamiaj połączenia ze Slacka lub aplikacji czatowej"
description: "Zbuduj własnego bota dla Slacka, Teams lub czatu internetowego, który rozpoczyna połączenia, śledzi je na żywo, kieruje agentem i odpowiada na jego pytania, korzystając z publicznego API."
---

Możesz sterować agentem z aplikacji czatu, której Twój zespół już używa. Wiadomość
rozpoczyna połączenie. Połączenie przebiega na żywo w wątku. Odpowiedź w wątku
kieruje działaniem agenta. Gdy agent potrzebuje decyzji, pyta Cię tam i
czeka na Twoją odpowiedź.

ThunderPhone nie hostuje tego bota za Ciebie. Ty (lub Twój agent programistyczny) tworzysz
mały serwer, który łączy aplikację czatu z publicznym API. Ta strona pokazuje
elementy rozwiązania. Są takie same dla Slacka, Microsoft Teams, Discorda lub prywatnej
strony czatu internetowego; przykłady używają Slacka.

## Jak to działa

| Co robisz na czacie | Co wywołuje Twój bot | Co się dzieje |
|---|---|---|
| Wysyłasz „Zadzwoń do Comcast i ustal przewidywany czas usunięcia awarii” | [`POST /v1/call`](/api-reference/outbound-calls) z wiadomością jako `context` | Agent wykonuje połączenie. Twój bot otwiera wątek dla połączenia |
| Obserwujesz wątek | Odbiera webhooki [`telephony.turn`](/pl/webhooks/events) | Każda wypowiedź agenta lub drugiej osoby pojawia się w wątku |
| Odpowiadasz w wątku w trakcie połączenia | [`POST /v1/calls/{call_id}/whisper`](/api-reference/calls#whisper-to-the-agent) | Agent otrzymuje Twoją notatkę prywatnie i podejmuje działanie. Druga osoba nigdy jej nie słyszy |
| Odpowiadasz na pytanie agenta | Twój [endpoint narzędzia](/pl/guides/build-tool-integration) zwraca odpowiedź lub dostarcza ją później przez [`POST /v1/calls/{call_id}/tool-results`](/api-reference/calls#deliver-a-tool-result) | Agent kontynuuje połączenie, wykorzystując tę odpowiedź; w trybie oczekiwania druga osoba w tym czasie słyszy muzykę na czekanie |
| Odczytujesz wynik | Odbiera webhooki [`telephony.complete`](/pl/webhooks/events) | Twój bot publikuje podsumowanie i wynik |

Twój bot przechowuje jedno mapowanie: który wątek czatu należy do którego `call_id`.

## Zanim zaczniesz

- **Klucz API**, przechowywany na serwerze, nigdy w przeglądarce ani na czacie.
  Utwórz go w **Integracje → klucze API** (zobacz
  [Utwórz serwerowy klucz API](/pl/guides/api-keys)).
- **Numer z włączonymi połączeniami wychodzącymi i agent** do realizacji połączeń. Wiadomość
  staje się `context` dla danego połączenia, więc jeden ogólny agent obsługuje każde zadanie.
- **Serwer**, który może odbierać webhooki, taki jak Railway, Fly.io, Render lub
  własny host.
- **Punkt końcowy webhooka** wskazujący na ten serwer i subskrybujący
  `telephony.turn` oraz `telephony.complete`. Zdarzenia tur są wysyłane tylko do
  punktów końcowych, które je wymieniają. Zobacz [Webhooki](/pl/webhooks/endpoints).
  Zdarzenia tur wymagają włączonego nagrywania rozmów agenta, a końcowe
  `summary` wymaga włączenia przez agenta ustawienia **Generuj podsumowanie rozmowy**; bez
  nich te pola pozostają puste.
- **Własna aplikacja czatowa.** W przypadku Slack utwórz aplikację w swoim obszarze roboczym na
  [api.slack.com/apps](https://api.slack.com/apps).

<Tip>
  Użyj aplikacji Slack utworzonej dla własnego obszaru roboczego i odbieraj wiadomości
  przez API zdarzeń Slacka zamiast odczytywać historię kanałów. Slack
  nakłada ścisłe limity odczytu na aplikacje dystrybuowane do innych obszarów roboczych poza
  jego Marketplace; aplikacja utworzona dla własnego obszaru roboczego im nie podlega,
  a zdarzenia docierają do Ciebie w momencie ich wystąpienia, bez odczytów. Typowe
  zakresy bota: `chat:write`, `app_mentions:read`, `im:history` (wiadomości
  bezpośrednie), `channels:history` i `groups:history` (odpowiedzi w wątkach w
  publicznych i prywatnych kanałach, do których bot należy). Subskrybuj zdarzenia bota
  `app_mention`, `message.im`, `message.channels` i `message.groups` oraz
  włącz kartę Wiadomości w sekcji Strona główna aplikacji, aby użytkownicy mogli wysyłać botowi wiadomości bezpośrednie.
</Tip>

## 1. Rozpocznij połączenie z wiadomości

Gdy bot otrzyma wiadomość (wiadomość bezpośrednią lub wzmiankę @),
natychmiast potwierdź żądanie Slacka (Slack ponawia wszystko, co nie zostanie
potwierdzone w ciągu 3 sekund), a resztę wykonaj w tle. Sprawdź,
czy nadawca ma uprawnienia do wykonywania połączeń, a następnie rozpocznij
połączenie z wiadomością jako `context`:

```bash
curl -X POST https://api.thunderphone.com/v1/call \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from_number": "+15551234567",
    "to_number":   "+18005550100",
    "agent_id":    12,
    "context":     "Matthew asked: get the outage ETA for account 4471. Wait on hold if needed.",
    "idempotency_key": "slack-D012AB3CD-1731000000.000100"
  }'
```

Zapisz zwrócone `call_id` dla wątku Slacka (`channel` wraz z
wiadomością `ts`) i odpowiedz w wątku („Dzwonię…”). Zbuduj
`idempotency_key` z kanału i `ts` wiadomości (`ts` jest unikalne
tylko w obrębie swojego kanału), aby ponowione zdarzenie Slacka nie wykonało
drugiego połączenia. Jeśli żądanie wskazuje osobę zamiast numeru, bot
najpierw wyszukuje jej numer. ThunderPhone wybiera tylko przesłany przez Ciebie `to_number`.

## 2. Śledź połączenie w wątku

Każdy webhook `telephony.turn` zawiera `call_id`, mówcę (`role`:
`assistant` dla agenta, `user` dla drugiej osoby), `text` oraz
`position` tury. Wyszukaj wątek według `call_id` i
opublikuj wpis.

- **Weryfikuj każdy webhook** przed wykonaniem jakiejkolwiek akcji. Zobacz
  [Weryfikowanie podpisów webhooków](/pl/guides/verify-webhook-signatures).
- **Usuwaj duplikaty na podstawie `event_id` koperty i sortuj według `position`.**
  Dostarczanie odbywa się co najmniej raz, a tury mogą nadejść w niewłaściwej kolejności.
- **Grupuj wpisy**, jeśli aktywne połączenie mogłoby zalać wątek; publikowanie co kilka
  sekund czyta się lepiej niż jedna wiadomość na wiersz.

Gdy nadejdzie `telephony.complete`, opublikuj sposób zakończenia połączenia (jego `status`
i `end_reason`), `summary` oraz wszelkie wyodrębnione dane, a następnie zamknij
wątek. Informacje o polach znajdziesz w [Zakończenie połączenia](/pl/webhooks/call-complete).

## 3. Kieruj połączeniem z wątku

Gdy ktoś odpowie w wątku aktywnego połączenia, wyślij odpowiedź jako szept,
chyba że agent czeka na odpowiedź na pytanie (krok 4), w takim przypadku odpowiedź
jest właściwą odpowiedzią:

```bash
curl -X POST https://api.thunderphone.com/v1/calls/987654321/whisper \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Ask whether they can waive the late fee."}'
```

Agent słyszy go prywatnie i uwzględnia w swojej następnej turze; druga
osoba nigdy nie słyszy samego szeptu. Szept ma od 1 do 1000 znaków. Kod
`409` oznacza, że połączenie nie jest już aktywne: poinformuj wątek, że połączenie się zakończyło.

## 4. Pozwól agentowi zadać ci pytanie

Dodaj agentowi narzędzie, na przykład `ask_owner` z jednym parametrem
`question`, które wywołuje twój serwer. Utwórz je jako
[połączenie API](/pl/guides/build-tool-integration) i połącz z agentem.
Każde żądanie narzędzia zawiera identyfikator połączenia w nagłówku `X-ThunderPhone-Call-ID`.

Są trzy sposoby na otrzymanie odpowiedzi.

**Wstrzymaj połączenie (do 10 minut).** Ustaw narzędzie w trybie wstrzymania: `spec.wait_mode`
`"hold"` oraz `spec.timeout` na maksymalnie 600 sekund (bez limitu czasu wstrzymanie
trwa 20 sekund), za pośrednictwem
[API](/api-reference/integrations#timeout-and-wait-mode) lub poproś Zeus o
ich ustawienie (edytory aplikacji nie mają jeszcze żadnego z tych pól). Punkt końcowy publikuje pytanie w wątku połączenia i natychmiast odpowiada
wynikiem oczekującym:

```json
{"status": "pending", "request_id": "q-C012AB3CD-1731000042.000300"}
```

Rozmówca słyszy jedną komunikat od agenta, a następnie muzykę podczas
oczekiwania. W menu telefonicznym lub na poczcie głosowej agent przekazuje zamiast tego
komunikaty głosowe, a agent pełnodupleksowy nie wstrzymuje rozmowy: otrzymuje
odpowiedź oczekującą jako wynik. Gdy odpowiedź pojawi się w wątku, dostarcz ją za pomocą
[`POST /v1/calls/{call_id}/tool-results`](/api-reference/calls#deliver-a-tool-result):

```bash
curl -X POST https://api.thunderphone.com/v1/calls/987654321/tool-results \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"request_id": "q-C012AB3CD-1731000042.000300", "result": {"answer": "Yes, book Tuesday at 10."}}'
```

Muzyka cichnie, a agent kontynuuje rozmowę, korzystając z twojej odpowiedzi. Jeśli nikt
nie odpowie przed upływem `timeout`, agent otrzyma informację, że nie nadeszła odpowiedź, i zaproponuje
rozmówcy dalsze kroki. Gdy pytanie dotyczące połączenia oczekuje na odpowiedź,
następna odpowiedź w jego wątku stanowi odpowiedź: dostarcz ją jako wynik narzędzia i
nie wysyłaj jej dodatkowo jako szeptu (szept dociera do agenta dopiero po
zakończeniu działania narzędzia). Zobacz
[Długie oczekiwanie](/pl/tools/overview).

**Czekaj w żądaniu (do 3 minut).** Twój punkt końcowy publikuje pytanie,
czeka na odpowiedź i ją zwraca, na przykład `{"answer": "Yes, book Tuesday at 10."}`.
Ustaw `spec.timeout` narzędzia za pomocą API, maksymalnie na 180 sekund (domyślna
wartość to 20). Ustaw dla punktu końcowego własny limit czasu o kilka sekund krótszy
(na przykład 170 sekund), aby gdy nikt nie odpowie, nadal zwracał
coś, na czym agent może działać, na przykład
`{"answer": null, "note": "No reply yet. Offer to take a message."}`. Narzędzie,
które osiągnie `timeout`, dociera do agenta jako błąd, a twój host musi
utrzymywać żądanie otwarte przez tak długi czas. Podczas oczekiwania agent informuje rozmówcę, że
sprawdza, po około 12 sekundach mówi, że nadal nad tym pracuje, a
następnie przekazuje krótką aktualizację mniej więcej co 15 sekund. Tryb wstrzymania działa
również tutaj: ustaw `spec.wait_mode` na `"hold"`, a rozmówca usłyszy muzykę
zamiast komunikatów.

**Odpowiedz szeptem.** Twój punkt końcowy publikuje pytanie i natychmiast zwraca odpowiedź,
na przykład `{"status": "asked", "note": "Matthew has been asked; his answer will come as guidance."}`.
Gdy nadejdzie odpowiedź, wyślij ją jako szept (krok 3), a agent
natychmiast na nią odpowie. Użyj tego w przypadku odpowiedzi, które mogą potrwać dłużej niż
10 minut. Połączenie nie jest wstrzymywane: twój prompt powinien poinstruować
agenta, co ma robić w międzyczasie, na przykład podtrzymywać rozmowę z rozmówcą lub zaproponować
oddzwonienie.

W każdym przypadku określ w prompcie agenta, kiedy używać narzędzia i co
powiedzieć rozmówcy podczas oczekiwania:

```text
When you need Matthew's decision, use ask_owner with a short question.
Tell the person you're checking with Matthew and it may take a minute.
If there's no answer, offer to take a message or have Matthew call back.
```

## Limity, które należy uwzględnić

- Twój endpoint musi odpowiedzieć w ramach `timeout` narzędzia, maksymalnie w ciągu **180 sekund**. Narzędzie w trybie wstrzymania może
  utrzymywać połączenie w stanie oczekiwania przez maksymalnie **600 sekund** z oczekującym wynikiem.
- Gdy narzędzie oczekuje, agent nie odpowiada drugiej osobie. W trybie wstrzymania
  słyszy ona muzykę, a w przeciwnym razie krótkie komunikaty głosowe.
- Szept może mieć maksymalnie **1000 znaków**.
- Dostarczanie `telephony.turn` odbywa się co najmniej raz i może następować w niewłaściwej kolejności.

## Lista kontrolna bezpieczeństwa

- Przechowuj klucz API na swoim serwerze.
- Weryfikuj podpisy ThunderPhone w webhookach i żądaniach narzędzi oraz
  sekret podpisywania Slacka w żądaniach Slacka. Dwa podpisy ThunderPhone
  używają różnych sekretów: dostarczenia webhooków używają własnego sekretu
  endpointu webhooka, a żądania narzędzi używają sekretu webhooka Twojej organizacji
  z [`GET /v1/webhook`](/api-reference/organizations#legacy-single-url-webhook).
- Zdecyduj, kto może rozpoczynać połączenia: sprawdzaj identyfikator użytkownika Slacka przed ich wykonaniem.
- Połączenia wychodzące podlegają tym samym zasadom co wszystkie pozostałe. Zobacz
  [Przepisy dotyczące połączeń wychodzących](/pl/guides/outbound-calling-laws).

## Zbuduj to z agentem programistycznym

Skieruj swojego agenta programistycznego do [serwera MCP dokumentacji](/pl/guides/docs-mcp) oraz
na tę stronę i poproś o „bota Slack dla mojego agenta ThunderPhone, który postępuje zgodnie z
tym przewodnikiem”. Zeus, asystent w aplikacji ThunderPhone, może skonfigurować
część agenta (endpoint webhooka, narzędzie i linie promptu) oraz napisać
kod startowy bota na czacie.
