---
title: "Izvajajte klice iz Slacka ali aplikacije za klepet"
description: "Z javnim API-jem ustvarite lastnega bota za Slack, Teams ali spletni klepet, ki začenja klice, jim sledi v živo, usmerja agenta in odgovarja na njegova vprašanja."
---

Svojega agenta lahko upravljate iz aplikacije za klepet, ki jo vaša ekipa že uporablja. Sporočilo
začne klic. Klic poteka v živo v niti. Odgovor v niti
usmerja agenta. Ko agent potrebuje odločitev, vas zanjo vpraša tam in
počaka na vaš odgovor.

ThunderPhone tega bota ne gosti namesto vas. Vi (ali vaš agent za programiranje) ustvarite
majhen strežnik, ki vašo aplikacijo za klepet poveže z javnim API-jem. Ta stran prikazuje
sestavne dele. Ti so enaki za Slack, Microsoft Teams, Discord ali zasebno
spletno stran za klepet; primeri uporabljajo Slack.

## Kako deluje skupaj

| To naredite v klepetu | Vaš bot pokliče | Kaj se zgodi |
|---|---|---|
| Pošljete »Pokliči Comcast in pridobi predvideni čas odprave izpada« | [`POST /v1/call`](/api-reference/outbound-calls) s sporočilom kot `context` | Agent pokliče. Vaš bot odpre nit za klic |
| Spremljate nit | Prejema spletne klice [`telephony.turn`](/sl/webhooks/events) | Vsaka vrstica, ki jo izreče agent ali druga oseba, se prikaže v niti |
| Med klicem odgovorite v niti | [`POST /v1/calls/{call_id}/whisper`](/api-reference/calls#whisper-to-the-agent) | Agent zasebno prejme vašo opombo in ukrepa po njej. Druga oseba je nikoli ne sliši |
| Odgovorite na vprašanje agenta | Vaša [končna točka orodja](/sl/guides/build-tool-integration) vrne vaš odgovor ali ga pozneje dostavi z [`POST /v1/calls/{call_id}/tool-results`](/api-reference/calls#deliver-a-tool-result) | Agent nadaljuje klic z njim; v načinu čakanja druga oseba medtem sliši glasbo za čakanje |
| Preberete rezultat | Prejema spletne klice [`telephony.complete`](/sl/webhooks/events) | Vaš bot objavi povzetek in izid |

Vaš bot vzdržuje eno preslikavo: katera nit klepeta pripada kateremu `call_id`.

## Preden začnete

- **Ključ API-ja**, shranjen na vašem strežniku in nikoli v brskalniku ali klepetu.
  Ustvarite ga v razdelku **Nastavitve organizacije → Ključi** (glejte
  [Ključi](/sl/guides/organization-settings)).
- **Številka z omogočenimi odhodnimi klici in agent** za klice. Sporočilo
  postane `context` za posamezen klic, zato en splošen agent obravnava vsako nalogo.
- **Strežnik**, ki lahko prejema spletne klice, na primer Railway, Fly.io, Render ali
  vaš lastni gostitelj.
- **Končna točka za spletne klice**, usmerjena na ta strežnik in naročena na
  `telephony.turn` in `telephony.complete`. Dogodki obratov so poslani le na
  končne točke, ki jih navajajo. Glejte [Spletni klici](/sl/webhooks/endpoints).
  Dogodki obratov zahtevajo vklopljeno snemanje klicev agenta, za `summary` ob
  koncu klica pa je potrebna agentova nastavitev **Ustvari povzetek klica**; brez
  tega ta polja ostanejo prazna.
- **Vaša lastna aplikacija za klepet.** Za Slack ustvarite aplikacijo v svojem delovnem prostoru na
  [api.slack.com/apps](https://api.slack.com/apps).

<Tip>
  Uporabite aplikacijo Slack, ki jo ustvarite za svoj delovni prostor, in prejemajte sporočila
  prek Slackovega API-ja Events, namesto da berete zgodovino kanalov. Slack
  za aplikacije, distribuirane v druge delovne prostore zunaj
  svoje Marketplace, določa stroge omejitve branja; aplikacija, ki jo ustvarite za
  svoj delovni prostor, tem omejitvam ne podlega, dogodki pa vas dosežejo takoj, ko se zgodijo,
  brez branja. Običajni obsegi botov: `chat:write`, `app_mentions:read`, `im:history` (neposredna
  sporočila), `channels:history` in `groups:history` (odgovori v nitih v
  javnih in zasebnih kanalih, v katerih je bot). Naročite se na dogodke bota
  `app_mention`, `message.im`, `message.channels` in `message.groups` ter
  vklopite zavihek Messages v razdelku App Home, da lahko ljudje botu pošiljajo neposredna sporočila.
</Tip>

## 1. Začnite klic iz sporočila

Ko vaš bot prejme sporočilo (neposredno sporočilo ali omembo z @),
takoj potrdite Slackovo zahtevo (Slack znova pošlje vse, kar ni
potrjeno v 3 sekundah), preostalo pa izvedite v ozadju. Preverite,
ali pošiljatelj sme opravljati klice, nato začnite klic s sporočilom kot
`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"
  }'
```

Vrnjeni `call_id` shranite ob Slackovi niti (`channel` skupaj z
vrednostjo `ts` sporočila) in odgovorite v niti ("Kličem …"). Ustvarite
`idempotency_key` iz kanala in vrednosti `ts` sporočila (vrednost `ts` je
enolična samo znotraj svojega kanala), da ponovljeni Slackov dogodek ne
začne drugega klica. Če zahteva navaja osebo namesto številke, vaš bot
najprej poišče številko. ThunderPhone kliče samo številko `to_number`, ki jo pošljete.

## 2. Spremljajte klic v niti

Vsak spletni kavelj `telephony.turn` vsebuje `call_id`, govorca (`role`:
`assistant` za agenta, `user` za drugo osebo), `text` in
`position` poteze. Poiščite nit po `call_id` in
objavite vrstico.

- **Preverite vsak spletni kavelj**, preden ukrepate na njegovi podlagi. Glejte
  [Preverjanje podpisov spletnih kavljev](/sl/guides/verify-webhook-signatures).
- **Odstranite podvojitve po `event_id` ovojnice in razvrstite po `position`.**
  Dostava je vsaj enkratna, poteze pa lahko prispejo v napačnem vrstnem redu.
- **Združujte vrstice**, če bi prometen klic preplavil nit; objavljanje vsakih
  nekaj sekund je bolj berljivo kot eno sporočilo na vrstico.

Ko prispe `telephony.complete`, objavite način zaključka klica (njegova
`status` in `end_reason`), `summary` ter vse pridobljene podatke in
zaključite nit. Za polja glejte [Zaključek klica](/sl/webhooks/call-complete).

## 3. Usmerjajte klic iz niti

Ko nekdo odgovori v niti aktivnega klica, pošljite odgovor kot šepet,
razen če agent čaka na odgovor na vprašanje (4. korak), v tem primeru je odgovor
odgovor na vprašanje:

```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 ga sliši zasebno in ga vključi v svojo naslednjo potezo; druga
oseba samega šepeta nikoli ne sliši. Šepet vsebuje od 1 do 1000 znakov. Koda
`409` pomeni, da klic ni več aktiven: niti sporočite, da se je klic končal.

## 4. Omogočite agentu, da vas vpraša

Agentu dodelite orodje, na primer `ask_owner` z enim parametrom
`question`, ki pokliče vaš strežnik. Ustvarite ga kot
[povezavo API](/sl/guides/build-tool-integration) in ga povežite z agentom.
Vsaka zahteva orodja vsebuje klic v glavi `X-ThunderPhone-Call-ID`.

Odgovor lahko vrnete na tri načine.

**Zadržite klic (do 10 minut).** Orodje nastavite na način zadržanja: `spec.wait_mode`
`"hold"` in `spec.timeout` do 600 sekund (brez časovne omejitve zadržanje
traja 20 sekund) prek
[API-ja](/api-reference/integrations#timeout-and-wait-mode) (urejevalnik na
nadzorni plošči še nima nobenega od teh polj). Vaša končna točka objavi vprašanje v nit klica in takoj
odgovori z rezultatom v čakanju:

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

Sogovornik sliši eno poved agenta, nato glasbo med zadržanjem. V
telefonskem meniju ali glasovni pošti agent namesto tega uporablja govorne posodobitve, agent s
polnim dupleksom pa klica ne zadrži: odgovor v čakanju prejme kot rezultat. Ko
odgovor prispe v nit, ga dostavite z
[`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."}}'
```

Glasba postopoma utihne in agent nadaljuje z vašim odgovorom. Če nihče
ne odgovori pred `timeout`, agent izve, da odgovora ni prejel, in sogovorniku ponudi
naslednje korake. Dokler vprašanje čaka za klic, nanj odgovori naslednji
odgovor v njegovi niti: dostavite ga kot rezultat orodja in ga ne pošljite
še kot šepet (šepet doseže agenta šele po vrnitvi orodja). Glejte
[Dolga čakanja](/sl/tools/overview).

**Počakajte v zahtevi (do 3 minute).** Vaša končna točka objavi vprašanje,
počaka na odgovor in ga vrne, na primer `{"answer": "Yes, book Tuesday at 10."}`.
Nastavite `spec.timeout` orodja prek API-ja, do 180 sekund (privzeta
vrednost je 20). Svoji končni točki določite lasten rok nekaj sekund krajši
(na primer 170 sekund), da tudi takrat, ko nihče ne odgovori, še vedno vrne
nekaj, na podlagi česar lahko agent ukrepa, na primer
`{"answer": null, "note": "No reply yet. Offer to take a message."}`. Orodje,
ki doseže `timeout`, agenta doseže kot napaka, vaš gostitelj pa mora zahtevo
obdržati odprto toliko časa. Med čakanjem agent sogovorniku pove, da preverja,
po približno 12 sekundah pove, da še vedno dela, nato pa približno vsakih 15 sekund
navede kratko posodobitev. Tudi tukaj deluje način zadržanja: nastavite `spec.wait_mode`
na `"hold"` in sogovornik namesto posodobitev sliši glasbo.

**Odgovorite s šepetom.** Vaša končna točka objavi vprašanje in se takoj vrne,
na primer `{"status": "asked", "note": "Matthew has been asked; his answer will come as guidance."}`.
Ko odgovor prispe, ga pošljite kot šepet (3. korak), agent pa
se nanj takoj odzove. To uporabite za odgovore, ki lahko trajajo dlje kot
10 minut. Klic ni zadržan: vaš poziv mora
agentu povedati, kaj naj medtem počne, na primer naj sogovorniku dela družbo ali ponudi,
da ga pokliče nazaj.

V vsakem primeru v pozivu agenta navedite, kdaj naj uporabi orodje in kaj naj
med čakanjem pove sogovorniku:

```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.
```

## Omejitve, ki jih upoštevajte pri načrtovanju

- Vaša končna točka mora odgovoriti v okviru `timeout` orodja, največ v **180 sekundah**. Orodje v načinu zadržanja lahko
  klic zadrži do **600 sekund** ob čakajočem rezultatu.
- Medtem ko orodje čaka, agent drugi osebi ne odgovarja. V načinu zadržanja
  sliši glasbo, sicer pa kratka glasovna obvestila.
- Šepet obsega največ **1000 znakov**.
- Dostava `telephony.turn` se izvede vsaj enkrat in je lahko neurejena.

## Varnostni kontrolni seznam

- Ključ API hranite na svojem strežniku.
- Preverite podpise ThunderPhone v spletnih kaveljcih in zahtevah orodij ter
  Slackovo podpisno skrivnost v Slackovih zahtevah. Podpisa ThunderPhone
  uporabljata različni skrivnosti: dostave spletnih kavljev uporabljajo lastno skrivnost
  končne točke spletnega kavlja, zahteve orodij pa skrivnost spletnega kavlja vaše organizacije
  iz [`GET /v1/webhook`](/api-reference/organizations#legacy-single-url-webhook).
- Določite, kdo lahko začne klice: pred vzpostavitvijo klica preverite ID uporabnika Slacka.
- Odhodni klici upoštevajo enaka pravila kot vsi drugi. Oglejte si
  [Zakoni o odhodnih klicih](/sl/guides/outbound-calling-laws).

## Izdelajte ga s programerskim agentom

Svojega programerskega agenta usmerite na [strežnik MCP za dokumentacijo](/sl/guides/docs-mcp) in na
to stran ter zahtevajte »bota Slack za mojega agenta ThunderPhone, ki upošteva
ta vodnik«. Zeus, pomočnik v aplikaciji ThunderPhone, lahko nastavi stran
agenta (končno točko spletnega kavlja, orodje in vrstice poziva) ter v klepetu napiše
začetno kodo za bota.
