---
title: "Soita puheluita Slackista tai chat-sovelluksesta"
description: "Rakenna oma Slack-, Teams- tai verkkokeskustelubotti, joka aloittaa puheluita, seuraa niitä reaaliajassa, ohjaa agenttia ja vastaa sen kysymyksiin julkisen API:n avulla."
---

Voit ohjata agenttia tiimisi jo käyttämästä chat-sovelluksesta. Viesti
käynnistää puhelun. Puhelu etenee reaaliajassa keskusteluketjussa. Ketjuun
lähetetty vastaus ohjaa agenttia. Kun agentti tarvitsee päätöksen, se kysyy
sinulta siellä ja odottaa vastaustasi.

ThunderPhone ei isännöi tätä bottia puolestasi. Sinä (tai koodausagenttisi)
rakennat pienen palvelimen, joka yhdistää chat-sovelluksesi julkiseen APIin.
Tällä sivulla esitellään osat. Ne ovat samat Slackissa, Microsoft Teamsissa,
Discordissa tai yksityisellä verkkokeskustelusivulla; esimerkeissä käytetään
Slackia.

## Näin se toimii yhdessä

| Teet tämän chatissa | Bottisi kutsuu | Mitä tapahtuu |
|---|---|---|
| Lähetä "Soita Comcastille ja selvitä käyttökatkon arvioitu korjausaika" | [`POST /v1/call`](/api-reference/outbound-calls), jossa viesti on `context` | Agentti soittaa. Bottisi avaa puhelulle keskusteluketjun |
| Seuraa keskusteluketjua | Vastaanottaa [`telephony.turn`](/fi/webhooks/events)-webhookeja | Jokainen agentin tai toisen henkilön sanoma rivi näkyy keskusteluketjussa |
| Vastaa keskusteluketjussa kesken puhelun | [`POST /v1/calls/{call_id}/whisper`](/api-reference/calls#whisper-to-the-agent) | Agentti saa viestisi yksityisesti ja toimii sen mukaan. Toinen henkilö ei koskaan kuule sitä |
| Vastaa agentin kysymykseen | Oma [työkalupäätepisteesi](/fi/guides/build-tool-integration) palauttaa vastauksesi tai toimittaa sen myöhemmin komennolla [`POST /v1/calls/{call_id}/tool-results`](/api-reference/calls#deliver-a-tool-result) | Agentti jatkaa puhelua vastauksesi perusteella; pitotilassa toinen henkilö kuulee sillä välin odotusmusiikkia |
| Lue tulos | Vastaanottaa [`telephony.complete`](/fi/webhooks/events)-webhookin | Bottisi julkaisee yhteenvedon ja lopputuloksen |

Bottisi ylläpitää yhtä yhdistämistä: mikä chat-ketju kuuluu millekin `call_id`:lle.

## Ennen aloittamista

- **API-avain**, joka säilytetään palvelimellasi eikä koskaan selaimessa tai chatissa.
  Luo sellainen kohdassa **Integraatiot → API-avaimet** (katso
  [Luo palvelimen API-avain](/fi/guides/api-keys)).
- **Lähteviin puheluihin tarkoitettu numero ja agentti** puheluita varten. Viestistä
  tulee puhelukohtainen `context`, joten yksi yleinen agentti hoitaa kaikki tehtävät.
- **Palvelin**, joka voi vastaanottaa webhookeja, kuten Railway, Fly.io, Render tai
  oma palvelimesi.
- **Webhook-päätepiste**, joka osoittaa kyseiseen palvelimeen ja on tilattu
  vastaanottamaan `telephony.turn`- ja `telephony.complete`-tapahtumia. Vuorotapahtumia lähetetään vain
  niitä luetteleviin päätepisteisiin. Katso [Webhookit](/fi/webhooks/endpoints).
  Vuorotapahtumat edellyttävät, että agentin puhelutallennus on käytössä, ja puhelun lopun
  `summary` edellyttää agentin **Luo puheluyhteenveto** -asetusta; ilman
  niitä nämä kentät jäävät tyhjiksi.
- **Oma chat-sovelluksesi.** Slackia varten luo sovellus työtilaasi osoitteessa
  [api.slack.com/apps](https://api.slack.com/apps).

<Tip>
  Käytä omaan työtilaasi luomaasi Slack-sovellusta ja vastaanota viestit
  Slackin Events API:n kautta kanavahistorian lukemisen sijaan. Slack
  asettaa tiukat lukurajoitukset sovelluksille, joita jaetaan muihin työtiloihin
  sen Marketplacen ulkopuolella; omaan työtilaasi rakentamaasi sovellusta nämä
  rajoitukset eivät koske, ja tapahtumat saapuvat sinulle niiden tapahtuessa
  ilman lukuja. Tyypilliset bottioikeudet: `chat:write`, `app_mentions:read`,
  `im:history` (suorat viestit), `channels:history` ja `groups:history`
  (ketjuvastaukset julkisilla ja yksityisillä kanavilla, joilla botti on mukana).
  Tilaa bottitapahtumat `app_mention`, `message.im`, `message.channels` ja
  `message.groups` ja ota käyttöön App Home -kohdan Messages-välilehti, jotta
  ihmiset voivat lähettää botille suoria viestejä.
</Tip>

## 1. Aloita puhelu viestistä

Kun bottisi vastaanottaa viestin (suoran viestin tai @maininnan),
vahvista Slackin pyyntö heti (Slack yrittää uudelleen kaikkea, mitä ei
vahvisteta 3 sekunnin kuluessa), ja tee loput taustalla. Tarkista,
että lähettäjällä on oikeus soittaa puheluita, ja aloita sitten puhelu
viesti `context`-kenttänä:

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

Tallenna palautettu `call_id` Slack-säiettä varten (`channel` sekä
viestin `ts`) ja vastaa säikeeseen ("Soitetaan…"). Muodosta
`idempotency_key` kanavasta ja viestin `ts`-arvosta (`ts` on yksilöllinen
vain omassa kanavassaan), jotta uudelleen yritetty Slack-tapahtuma ei
aloita toista puhelua. Jos pyynnössä mainitaan henkilö numeron sijaan,
bottisi hakee numeron ensin. ThunderPhone soittaa vain lähettämääsi
`to_number`-numeroon.

## 2. Seuraa puhelua säikeessä

Jokainen `telephony.turn`-webhook sisältää `call_id`-tunnisteen,
puhujan (`role`: `assistant` agentille, `user` toiselle henkilölle), `text`-tekstin
sekä vuoron `position`-sijainnin. Hae säie `call_id`-tunnisteella ja
lähetä rivi siihen.

- **Vahvista jokainen webhook** ennen kuin toimit sen perusteella. Katso
  [Vahvista webhook-allekirjoitukset](/fi/guides/verify-webhook-signatures).
- **Poista kaksoiskappaleet kirjekuoren `event_id`-tunnisteen perusteella ja järjestä `position`-arvon mukaan.**
  Toimitus tapahtuu vähintään kerran, ja vuorot voivat saapua väärässä järjestyksessä.
- **Lähetä rivejä erissä**, jos kiireinen puhelu täyttäisi säikeen; muutaman
  sekunnin välein julkaiseminen on luettavampaa kuin yksi viesti riviä kohden.

Kun `telephony.complete` saapuu, julkaise puhelun päättymistapa (sen `status`
ja `end_reason`), `summary` sekä kaikki poimitut tiedot ja päätä säie.
Katso kentät kohdasta [Puhelu valmis](/fi/webhooks/call-complete).

## 3. Ohjaa puhelua säikeestä

Kun joku vastaa käynnissä olevan puhelun säikeeseen, lähetä vastaus kuiskauksena,
ellei agentti odota vastausta kysymykseen (vaihe 4), jolloin vastaus
on vastaus kysymykseen:

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

Agentti kuulee sen yksityisesti ja sisällyttää sen seuraavaan vuoroonsa; toinen
henkilö ei koskaan kuule itse kuiskausta. Kuiskaus on 1–1000 merkkiä pitkä. Jos saat
`409`-vastauksen, puhelu ei ole enää käynnissä: kerro säikeessä, että puhelu on päättynyt.

## 4. Anna agentin kysyä sinulta

Anna agentille työkalu, esimerkiksi `ask_owner`, jossa on yksi `question`-
parametri ja joka kutsuu palvelintasi. Luo se
[API-yhteytenä](/fi/guides/build-tool-integration) ja liitä se agenttiin.
Jokaisessa työkalupyynnössä puhelu välitetään `X-ThunderPhone-Call-ID`-
otsakkeessa.

Vastauksen voi palauttaa kolmella tavalla.

**Pidä puhelu odotustilassa (enintään 10 minuuttia).** Aseta työkalu odotustilaan: `spec.wait_mode`
`"hold"` ja `spec.timeout` enintään 600 sekuntiin (ilman aikakatkaisua odotus
kestää 20 sekuntia) [API:n](/api-reference/integrations#timeout-and-wait-mode) kautta tai pyydä Zeusia
asettamaan ne (sovelluksen muokkaimissa ei vielä ole kumpaakaan kenttää). Päätepisteesi lähettää kysymyksen puhelun ketjuun ja vastaa heti
odottavalla tuloksella:

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

Toinen osapuoli kuulee agentilta yhden lauseen ja sen jälkeen pitomusiikkia.
Puhelinvalikossa tai vastaajassa agentti käyttää sen sijaan puhuttuja
tilannepäivityksiä, eikä täysdupleksiagentti pidä puhelua pidossa: se
saa odottavan vastauksen tuloksena. Kun vastaus saapuu ketjuun, toimita se
[`POST /v1/calls/{call_id}/tool-results`](/api-reference/calls#deliver-a-tool-result) -pyynnöllä:

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

Musiikki vaimenee ja agentti jatkaa vastauksellasi. Jos kukaan ei
vastaa ennen `timeout`-ajan päättymistä, agentille kerrotaan, ettei vastausta
saatu, ja se ehdottaa toiselle osapuolelle seuraavia toimia. Kun puhelulle
on odottava kysymys, sen ketjuun tuleva seuraava vastaus vastaa siihen:
toimita se työkalun tuloksena äläkä lähetä sitä myös kuiskauksena (kuiskaus
tavoittaa agentin vasta työkalun palautettua tuloksen). Katso
[Pitkät odotusajat](/fi/tools/overview).

**Odota pyynnössä (enintään 3 minuuttia).** Päätepisteesi lähettää kysymyksen,
odottaa vastausta ja palauttaa sen, esimerkiksi `{"answer": "Yes, book Tuesday at 10."}`.
Aseta työkalun `spec.timeout` API:n kautta enintään 180 sekuntiin (oletusarvo
on 20). Aseta päätepisteellesi oma määräaika muutamaa sekuntia lyhyemmäksi
(esimerkiksi 170 sekuntiin), jotta se palauttaa myös silloin, kun kukaan ei
vastaa, jotain mistä agentti voi jatkaa, esimerkiksi
`{"answer": null, "note": "No reply yet. Offer to take a message."}`. Työkalu,
joka saavuttaa `timeout`-ajan, saapuu agentille virheenä, ja palvelimesi on
pidettävä pyyntö avoimena niin kauan. Odottaessaan agentti kertoo toiselle
osapuolelle tarkistavansa asiaa, sanoo noin 12 sekunnin jälkeen työskentelevänsä
edelleen ja antaa sitten lyhyen tilannepäivityksen noin 15 sekunnin välein.
Pitotila toimii myös tässä: aseta `spec.wait_mode` arvoon `"hold"`, jolloin
toinen osapuoli kuulee tilannepäivitysten sijaan musiikkia.

**Vastaa kuiskauksella.** Päätepisteesi lähettää kysymyksen ja palauttaa heti
vastauksen, esimerkiksi `{"status": "asked", "note": "Matthew has been asked; his answer will come as guidance."}`.
Kun vastaus saapuu, lähetä se kuiskauksena (vaihe 3), ja agentti
reagoi siihen heti. Käytä tätä vastauksiin, joiden saaminen voi kestää yli
10 minuuttia. Puhelua ei pidetä pidossa: kehotteessasi tulee kertoa
agentille, mitä sen pitää tehdä sillä välin, esimerkiksi pitää seuraa tai
tarjota takaisinsoittoa.

Kerro jokaisessa tapauksessa agentin kehotteessa, milloin työkalua käytetään ja
mitä toiselle osapuolelle kerrotaan odotuksen aikana:

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

## Huomioitavat rajoitukset

- Päätepisteesi on vastattava työkalun `timeout`-ajan kuluessa, enintään **180 sekunnissa**. Pitotilassa oleva työkalu voi
  pitää puhelun pidossa enintään **600 sekuntia** odottavan tuloksen kanssa.
- Kun työkalu odottaa, agentti ei vastaa toiselle henkilölle. Pitotilassa
  hän kuulee musiikkia; muussa tapauksessa lyhyitä puhuttuja tilannepäivityksiä.
- Kuiskauksen enimmäispituus on **1000 merkkiä**.
- `telephony.turn` toimitetaan vähintään kerran, ja toimitukset voivat olla väärässä järjestyksessä.

## Tietoturvan tarkistuslista

- Säilytä API-avain palvelimellasi.
- Varmista ThunderPhonen allekirjoitukset webhookeissa ja työkalupyynnöissä sekä
  Slackin allekirjoitussalaisuus Slackin pyynnöissä. ThunderPhonen kaksi
  allekirjoitusta käyttävät eri salaisuuksia: webhook-toimitukset käyttävät webhook-
  päätepisteen omaa salaisuutta, ja työkalupyynnöt käyttävät organisaatiosi webhook-
  salaisuutta, joka haetaan osoitteesta [`GET /v1/webhook`](/api-reference/organizations#legacy-single-url-webhook).
- Päätä, kuka saa aloittaa puheluita: tarkista Slack-käyttäjätunnus ennen puhelun soittamista.
- Lähtevät puhelut noudattavat samoja sääntöjä kuin muutkin puhelut. Katso
  [lähtevien puheluiden lait](/fi/guides/outbound-calling-laws).

## Rakenna se koodausagentilla

Ohjaa koodausagenttisi [dokumentaation MCP-palvelimelle](/fi/guides/docs-mcp) ja
tälle sivulle ja pyydä sitä luomaan ”Slack-botti ThunderPhone-agentilleni, joka noudattaa
tätä opasta”. ThunderPhone-sovelluksen avustaja Zeus voi määrittää
agentin puolen (webhook-päätepisteen, työkalun ja kehotteen rivit) sekä kirjoittaa
botille aloituskoodin chattiin.
