---
title: "Halda kõnesid Slackist või vestlusrakendusest"
description: "Loo oma Slacki, Teamsi või veebivestluse bot, mis algatab kõnesid, jälgib neid reaalajas, suunab häälagenti ja vastab selle küsimustele avaliku API abil."
---

Saad juhtida häälagenti vestlusrakendusest, mida sinu meeskond juba kasutab. Sõnum
alustab kõnet. Kõne kulgeb reaalajas lõimes. Lõimes antud vastus
suunab häälagenti. Kui häälagent vajab otsust, küsib ta seda seal ja
ootab sinu vastust.

ThunderPhone ei majuta seda robotit sinu eest. Sina (või sinu kodeerimisagent) ehitad
väikese serveri, mis ühendab sinu vestlusrakenduse avaliku API-ga. Sellel lehel on
näidatud vajalikud osad. Need on samad Slacki, Microsoft Teamsi, Discordi või privaatse
veebivestluslehe puhul; näited kasutavad Slacki.

## Kuidas see kokku sobib

| Teed seda vestluses | Sinu robot kutsub | Mis juhtub |
|---|---|---|
| Saada „Helista Comcastile ja küsi katkestuse eeldatavat lõppaega” | [`POST /v1/call`](/api-reference/outbound-calls), kus sõnum on `context` | Häälagent valib numbri. Sinu robot avab kõne jaoks lõime |
| Jälgi lõime | Võtab vastu [`telephony.turn`](/et/webhooks/events) veebikonksud | Iga rida, mille häälagent või teine osapool ütleb, ilmub lõimesse |
| Vasta kõne ajal lõimes | [`POST /v1/calls/{call_id}/whisper`](/api-reference/calls#whisper-to-the-agent) | Häälagent saab sinu märkuse privaatselt kätte ja tegutseb selle järgi. Teine osapool ei kuule seda kunagi |
| Vasta häälagendi küsimusele | Sinu [tööriista lõpp-punkt](/et/guides/build-tool-integration) tagastab sinu vastuse või edastab selle hiljem käsuga [`POST /v1/calls/{call_id}/tool-results`](/api-reference/calls#deliver-a-tool-result) | Häälagent jätkab sellega kõnet; ootelrežiimis kuuleb teine osapool samal ajal ootelmuusikat |
| Loe tulemust | Võtab vastu [`telephony.complete`](/et/webhooks/events) | Sinu robot postitab kokkuvõtte ja tulemuse |

Sinu robot hoiab üht vastendust: milline vestluslõim kuulub millisele `call_id`-le.

## Enne alustamist

- **API-võti**, mida hoitakse sinu serveris, mitte kunagi brauseris ega vestluses.
  Loo see jaotises **Integratsioonid → API-võtmed** (vt
  [Serveri API-võtme loomine](/et/guides/api-keys)).
- **Väljuvate kõnede toega number ja häälagent** kõnede jaoks. Sõnum
  muutub kõnepõhiseks `context`-iks, seega üks üldine häälagent haldab kõiki ülesandeid.
- **Server**, mis saab vastu võtta veebikonksusid, näiteks Railway, Fly.io, Render või
  sinu enda host.
- **Veebikonksu lõpp-punkt**, mis osutab sellele serverile ja on tellitud sündmustele
  `telephony.turn` ja `telephony.complete`. Kõnevooru sündmused saadetakse ainult neid loetlevatele
  lõpp-punktidele. Vt [Veebikonksud](/et/webhooks/endpoints).
  Kõnevooru sündmused nõuavad, et agendi kõnesalvestus oleks sisse lülitatud, ning kõne lõpu
  `summary` nõuab agendi sätet **Loo kõne kokkuvõte**; ilma nendeta jäävad
  need väljad tühjaks.
- **Sinu enda vestlusrakendus.** Slacki jaoks loo oma tööruumis rakendus aadressil
  [api.slack.com/apps](https://api.slack.com/apps).

<Tip>
  Kasuta Slacki rakendust, mille lood oma tööruumi jaoks, ja võta sõnumid vastu
  Slacki Events API kaudu, selle asemel et lugeda kanali ajalugu. Slack
  rakendab oma Marketplace'ist väljaspool teistesse tööruumidesse levitatud rakendustele
  rangeid lugemispiiranguid; sinu enda tööruumi jaoks loodud rakendusele need ei kehti
  ning sündmused jõuavad sinuni nende toimumise hetkel ilma lugemispäringuteta. Tüüpilised
  roboti õigused: `chat:write`, `app_mentions:read`, `im:history` (otsesõnumid),
  `channels:history` ja `groups:history` (lõimevastused avalikes ja privaatsetes
  kanalites, kus robot on olemas). Telli roboti sündmused
  `app_mention`, `message.im`, `message.channels` ja `message.groups` ning
  lülita App Home'i jaotises sisse vahekaart Messages, et inimesed saaksid robotile otsesõnumeid saata.
</Tip>

## 1. Alusta kõnet sõnumist

Kui sinu bot saab sõnumi (otsesõnumi või @mainimise),
kinnita Slacki päring kohe (Slack proovib uuesti kõike, mida ei
kinnitata 3 sekundi jooksul), ja tee ülejäänu taustal. Kontrolli,
et saatjal on õigus kõnesid teha, seejärel alusta kõnet, kasutades
sõnumit `context`-ina:

```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"
  }'
```

Salvesta tagastatud `call_id` Slacki lõime juurde (`channel` koos sõnumi
`ts`-iga) ja vasta lõimes ("Helistan…"). Koosta `idempotency_key`
kanali ja sõnumi `ts`-i põhjal (`ts` on kordumatu ainult oma kanalis),
et uuesti proovitud Slacki sündmus ei algataks teist kõnet. Kui päringus
on numbri asemel isiku nimi, otsib sinu bot numbri esmalt üles.
ThunderPhone valib ainult sinu saadetud `to_number`-i.

## 2. Jälgi kõnet lõimes

Iga `telephony.turn` webhook sisaldab `call_id`-d, kõnelejat (`role`:
`assistant` agendi jaoks, `user` teise isiku jaoks), `text`-i ja
käigu `position`-i. Leia lõim `call_id` järgi ja postita rida.

- **Kontrolli iga webhooki** enne selle põhjal tegutsemist. Vaata
  [Webhooki allkirjade kontrollimine](/et/guides/verify-webhook-signatures).
- **Eemalda duplikaadid ümbrise `event_id` alusel ja järjestage need `position` järgi.**
  Edastus toimub vähemalt üks kord ning käigud võivad saabuda vales järjekorras.
- **Koonda read** rühmadeks, kui aktiivne kõne ujutaks lõime üle; iga mõne
  sekundi järel postitamine on loetavam kui üks sõnum rea kohta.

Kui saabub `telephony.complete`, postita, kuidas kõne lõppes (selle `status`
ja `end_reason`), `summary` ning kõik eraldatud andmed, ja sulge lõim.
Väljade kohta vaata [Kõne lõpetamine](/et/webhooks/call-complete).

## 3. Suuna kõnet lõimest

Kui keegi vastab aktiivse kõne lõimes, saada vastus sosinana, välja
arvatud juhul, kui agent ootab küsimusele vastust (samm 4), mil vastus
on vastus küsimusele:

```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 kuuleb seda privaatselt ja põimib selle oma järgmisse käiku; teine
isik ei kuule sosinat kunagi. Sosin võib olla 1 kuni 1000 tähemärki. `409`
tähendab, et kõne ei ole enam aktiivne: teavita lõime, et kõne on lõppenud.

## 4. Lase häälagendil sinult küsida

Anna häälagendile tööriist, näiteks `ask_owner` ühe parameetriga `question`,
mis kutsub sinu serverit. Loo see
[API-ühendusena](/et/guides/build-tool-integration) ja seo häälagendiga.
Iga tööriistapäring kannab kõnet päises `X-ThunderPhone-Call-ID`.

Vastuse tagasisaamiseks on kolm võimalust.

**Pane kõne ootele (kuni 10 minutiks).** Määra tööriist ooterežiimile: `spec.wait_mode`
`"hold"` ja `spec.timeout` kuni 600 sekundini (ilma ajalõputa kestab ootel
hoidmine 20 sekundit), kasutades
[API-t](/api-reference/integrations#timeout-and-wait-mode), või palu Zeusil
need määrata (rakenduse redaktoritel pole kumbagi välja veel). Sinu lõpp-punkt postitab küsimuse kõne lõime ja vastab
kohe ootel oleva tulemusega:

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

Teine osapool kuuleb häälagendilt üht lauset ja seejärel ootelmuusikat. Telefonimenüüs
või kõnepostis kasutab häälagent selle asemel suulisi teavitusi ning
täisdupleksne häälagent ei pane kõnet ootele: ta saab ootel vastuse tulemusena. Kui
vastus jõuab lõime, edasta see kaudu
[`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."}}'
```

Muusika vaibub ja häälagent jätkab sinu vastusega. Kui keegi ei vasta enne
`timeout`-i, öeldakse häälagendile, et vastust ei saabunud, ning ta pakub
teisele osapoolele järgmisi samme. Kui kõne küsimus on ootel, vastab sellele
selle lõime järgmine vastus: edasta see tööriista tulemusena ja ära saada seda
lisaks sosinsõnumina (sosinsõnum jõuab häälagendini alles pärast tööriista tagastamist).
Vaata
[Pikki ootamisi](/et/tools/overview).

**Oota päringus (kuni 3 minutit).** Sinu lõpp-punkt postitab küsimuse,
ootab vastust ja tagastab selle, näiteks `{"answer": "Yes, book Tuesday at 10."}`.
Määra tööriista `spec.timeout` API kaudu kuni 180 sekundile (vaikimisi
on 20). Määra oma lõpp-punktile mõne sekundi võrra lühem ajalimiit
(näiteks 170 sekundit), et juhul, kui keegi ei vasta, tagastaks see siiski
midagi, mille põhjal häälagent saab tegutseda, näiteks
`{"answer": null, "note": "No reply yet. Offer to take a message."}`. Tööriist,
mis jõuab oma `timeout`-ini, jõuab häälagendini veana ning sinu server peab
hoidma päringut nii kaua avatuna. Ootamise ajal ütleb häälagent teisele
osapoolele, et ta kontrollib, teatab umbes 12 sekundi pärast, et töö jätkub,
ning annab seejärel lühikese teavituse umbes iga 15 sekundi järel. Ka siin
toimib ooteležiim: määra `spec.wait_mode` väärtuseks `"hold"` ja teine osapool
kuuleb teavituste asemel muusikat.

**Vasta sosinsõnumiga.** Sinu lõpp-punkt postitab küsimuse ja tagastab kohe,
näiteks `{"status": "asked", "note": "Matthew has been asked; his answer will come as guidance."}`.
Kui vastus saabub, saada see sosinsõnumina (3. samm) ja häälagent
vastab sellele kohe. Kasuta seda vastuste jaoks, mis võivad võtta kauem kui
10 minutit. Kõnet ei panda ootele: sinu juhis peaks ütlema
häälagendile, mida vahepeal teha, näiteks teisele osapoolele seltsi pakkuda või
pakkuda talle tagasi helistamist.

Igal juhul ütle häälagendi juhises, millal tööriista kasutada ja mida
teisele osapoolele ootamise ajal öelda:

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

## Planeeritavad piirangud

- Sinu lõpp-punkt peab vastama tööriista `timeout`-i jooksul, maksimaalselt **180 sekundiga**. Ootel režiimis tööriist võib hoida kõnet ootel kuni **600 sekundit**, kui tulemus on ootel.
- Kui tööriist ootab, ei vasta agent teisele osapoolele. Ootel režiimis kuuleb ta muusikat; muul juhul lühikesi suulisi olekuuuendusi.
- Sosistus võib olla kuni **1000 tähemärki**.
- `telephony.turn` edastus toimub vähemalt üks kord ja võib jõuda kohale vales järjekorras.

## Turvalisuse kontrollnimekiri

- Hoia API-võtit oma serveris.
- Kontrolli ThunderPhone'i allkirju veebikonksudel ja tööriistataotlustel ning Slacki allkirjastamissaladust Slacki taotlustel. Kahel ThunderPhone'i allkirjal on erinevad saladused: veebikonksu edastused kasutavad veebikonksu lõpp-punkti enda saladust ja tööriistataotlused sinu organisatsiooni veebikonksu saladust, mille saad [`GET /v1/webhook`](/api-reference/organizations#legacy-single-url-webhook)-ist.
- Otsusta, kes võib kõnesid alustada: kontrolli enne kõne tegemist Slacki kasutaja ID-d.
- Väljuvatele kõnedele kehtivad samad reeglid nagu kõigile teistele. Vaata [väljuvate kõnede seadusi](/et/guides/outbound-calling-laws).

## Loo see programmeerimisagendiga

Suuna oma programmeerimisagent [dokumentatsiooni MCP-serveri](/et/guides/docs-mcp) ja selle lehe juurde ning palu luua „Slacki bott minu ThunderPhone'i agendile, mis järgib seda juhendit”. ThunderPhone'i rakenduse abiline Zeus saab seadistada agendi poole (veebikonksu lõpp-punkti, tööriista ja viiba read) ning kirjutada vestluses botile algkoodi.
