---
title: "Endesha simu kutoka Slack au programu ya gumzo"
description: "Unda bot yako mwenyewe ya Slack, Teams au gumzo la wavuti inayopiga simu, kuzifuatilia moja kwa moja, kuongoza ejenti na kujibu maswali yake, kwa kutumia API ya umma."
---

Unaweza kuendesha ejenti kutoka kwenye programu ya gumzo ambayo timu yako tayari inatumia. Ujumbe
unaanzisha simu. Simu inaendelea moja kwa moja kwenye uzi. Jibu kwenye uzi
huelekeza ejenti. Ejenti inapohitaji uamuzi, inakuuliza humo na
kusubiri jibu lako.

ThunderPhone haikuandalii boti hii. Wewe (au ejenti wako wa kuandika msimbo) unatengeneza
seva ndogo inayounganisha programu yako ya gumzo na API ya umma. Ukurasa huu unaonyesha
vipengele. Ni vilevile kwa Slack, Microsoft Teams, Discord au ukurasa binafsi wa
gumzo la wavuti; mifano inatumia Slack.

## Jinsi inavyounganishwa

| Unafanya hivi kwenye gumzo | Boti yako inapiga | Kinachotokea |
|---|---|---|
| Tuma "Piga Comcast na upate muda unaokadiriwa wa hitilafu kuisha" | [`POST /v1/call`](/api-reference/outbound-calls) pamoja na ujumbe kama `context` | Ejenti inapiga simu. Boti yako inafungua uzi wa simu |
| Tazama uzi | Inapokea webhook za [`telephony.turn`](/sw/webhooks/events) | Kila mstari unaosemwa na ejenti au mtu mwingine huonekana kwenye uzi |
| Jibu kwenye uzi katikati ya simu | [`POST /v1/calls/{call_id}/whisper`](/api-reference/calls#whisper-to-the-agent) | Ejenti hupata dokezo lako kwa faragha na kulifanyia kazi. Mtu mwingine haliskii kamwe |
| Jibu swali la ejenti | [Kituo chako cha zana](/sw/guides/build-tool-integration) kinarejesha jibu lako, au kukifikisha baadaye kwa [`POST /v1/calls/{call_id}/tool-results`](/api-reference/calls#deliver-a-tool-result) | Ejenti huendeleza simu kwa jibu hilo; katika hali ya kusubiri mtu mwingine husikia muziki wa kusubiri wakati huo |
| Soma matokeo | Inapokea [`telephony.complete`](/sw/webhooks/events) | Boti yako huchapisha muhtasari na matokeo |

Boti yako huhifadhi uhusiano mmoja: uzi upi wa gumzo unahusiana na `call_id` ipi.

## Kabla ya kuanza

- **Ufunguo wa API**, unaohifadhiwa kwenye seva yako na kamwe si kwenye kivinjari au kwenye gumzo.
  Unda mmoja chini ya **Mipangilio ya shirika → Funguo** (tazama
  [Funguo](/sw/guides/organization-settings)).
- **Namba iliyowezeshwa kupiga simu za kutoka na ejenti** kwa ajili ya simu. Ujumbe
  huwa `context` ya kila simu, kwa hivyo ejenti mmoja wa jumla hushughulikia kila jukumu.
- **Seva** inayoweza kupokea webhook, kama Railway, Fly.io, Render au
  mpangishaji wako mwenyewe.
- **Kituo cha webhook** kinachoelekeza kwenye seva hiyo na kilichosajiliwa kwa
  `telephony.turn` na `telephony.complete`. Matukio ya zamu hutumwa tu kwa
  vituo vinavyoyaorodhesha. Tazama [Webhook](/sw/webhooks/endpoints).
  Matukio ya zamu yanahitaji kurekodi simu kwa ejenti kuwashwa, na
  `summary` ya mwisho wa simu inahitaji mpangilio wa ejenti wa **Tengeneza muhtasari wa simu**; bila
  hayo sehemu hizo hubaki tupu.
- **Programu yako mwenyewe ya gumzo.** Kwa Slack, unda programu katika eneo lako la kazi kwenye
  [api.slack.com/apps](https://api.slack.com/apps).

<Tip>
  Tumia programu ya Slack unayounda kwa ajili ya eneo lako la kazi, na upokee ujumbe
  kupitia Events API ya Slack badala ya kusoma historia ya vituo. Slack
  huweka vikomo vikali vya kusoma kwa programu zinazosambazwa kwa maeneo mengine ya kazi nje ya
  Marketplace yake; programu unayounda kwa ajili ya eneo lako la kazi haizuiliwi
  navyo, na matukio yanakufikia yanapotokea bila usomaji wowote. Ruhusa za kawaida
  za boti: `chat:write`, `app_mentions:read`, `im:history` (ujumbe wa moja kwa moja),
  `channels:history` na `groups:history` (majibu ya uzi katika
  vituo vya umma na binafsi ambamo boti imo). Sajili matukio ya boti
  `app_mention`, `message.im`, `message.channels` na `message.groups`, na
  washa kichupo cha Ujumbe chini ya Mwanzo wa Programu ili watu waweze kutuma ujumbe wa moja kwa moja kwa boti.
</Tip>

## 1. Anzisha simu kutoka kwenye ujumbe

Bot yako inapopokea ujumbe (ujumbe wa moja kwa moja au @mention),
kubali ombi la Slack mara moja (Slack hujaribu tena chochote
kisichokubaliwa ndani ya sekunde 3) na utekeleze yaliyosalia chinichini. Hakikisha
kwamba mtumaji ameruhusiwa kupiga simu, kisha anza simu kwa kutumia
ujumbe kama `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"
  }'
```

Hifadhi `call_id` iliyorejeshwa inayohusishwa na thread ya Slack (`channel` pamoja na
`ts` ya ujumbe) na ujibu kwenye thread ("Inapiga simu…"). Unda
`idempotency_key` kutoka kwenye channel na `ts` ya ujumbe (`ts` ni ya kipekee
ndani ya channel yake pekee), ili tukio la Slack linalojaribiwa tena lisipige simu
ya pili. Ikiwa ombi linamtaja mtu badala ya nambari, bot yako
hutafuta nambari kwanza. ThunderPhone hupiga tu `to_number` unayotuma.

## 2. Fuatilia simu kwenye thread

Kila webhook ya `telephony.turn` hubeba `call_id`, msemaji (`role`:
`assistant` kwa ejenti, `user` kwa mtu mwingine), `text` na
`position` ya zamu. Tafuta thread kwa kutumia `call_id` na
uchapishe mstari.

- **Thibitisha kila webhook** kabla ya kuchukua hatua. Tazama
  [Thibitisha saini za webhook](/sw/guides/verify-webhook-signatures).
- **Ondoa nakala rudufu kwa kutumia `event_id` ya bahasha na panga kwa `position`.**
  Uwasilishaji hufanyika angalau mara moja, na zamu zinaweza kuwasili nje ya mpangilio.
- **Kusanya mistari kwa makundi** ikiwa simu yenye shughuli nyingi ingeijaza thread; kuchapisha kila baada ya
  sekunde chache husomeka vizuri zaidi kuliko ujumbe mmoja kwa kila mstari.

`telephony.complete` inapowasili, chapisha jinsi simu ilivyomalizika (`status`
na `end_reason`), `summary`, na data yoyote iliyotolewa, kisha funga
thread. Tazama [Simu imekamilika](/sw/webhooks/call-complete) kwa sehemu hizo.

## 3. Elekeza simu kutoka kwenye thread

Mtu anapojibu kwenye thread ya simu inayoendelea, tuma jibu hilo kama mnong'ono,
isipokuwa ejenti inasubiri jibu la swali (hatua ya 4), ambapo jibu hilo
ndilo jibu la swali:

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

Ejenti huisikia kwa faragha na huiunganisha katika zamu yake inayofuata; mtu
mwingine hasikii kamwe mnong'ono wenyewe. Mnong'ono una herufi 1 hadi 1000. Thamani ya
`409` inamaanisha simu haiendelei tena: iambie thread kwamba simu imeisha.

## 4. Ruhusu ejenti ikuulize

Ipe ejenti zana, kwa mfano `ask_owner` yenye kigezo kimoja cha `question`,
kinachopigia seva yako. Iunde kama
[muunganisho wa API](/sw/guides/build-tool-integration) na uiunganishe na ejenti.
Kila ombi la zana hubeba simu katika kichwa chake cha `X-ThunderPhone-Call-ID`.

Kuna njia tatu za kupokea jibu.

**Shikilia simu (hadi dakika 10).** Weka zana katika hali ya kushikilia: `spec.wait_mode`
`"hold"` na `spec.timeout` hadi sekunde 600 (bila muda wa mwisho ushikiliaji
hudumu sekunde 20), kupitia
[API](/api-reference/integrations#timeout-and-wait-mode) (kihariri cha dashibodi
bado hakina sehemu zozote kati ya hizi). Endpoint yako hutuma swali kwenye uzi wa simu na kujibu
mara moja kwa matokeo yanayosubiri:

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

Mtu mwingine husikia sentensi moja kutoka kwa ejenti, kisha muziki wa kusubiri. Kwenye
menyu ya simu au ujumbe wa sauti ejenti hutumia masasisho ya kusemwa badala yake, na
ejenti ya full-duplex haishikilii: hupokea jibu linalosubiri kama matokeo. Jibu
linapowasili kwenye uzi, liwasilishe kwa
[`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."}}'
```

Muziki hupungua polepole na ejenti huendelea na jibu lako. Ikiwa hakuna
anayejibu kabla ya `timeout`, ejenti huambiwa hakuna jibu lililopatikana na humpa
mtu mwingine hatua zinazofuata. Wakati swali linasubiri kwa simu, jibu
linalofuata katika uzi wake hulijibu: liwasilishe kama matokeo ya zana na
usilitume pia kama whisper (whisper humfikia ejenti tu baada ya zana kurejesha
jibu). Angalia
[Kusubiri kwa muda mrefu](/sw/tools/overview).

**Subiri katika ombi (hadi dakika 3).** Endpoint yako hutuma swali,
husubiri jibu na kulirejesha, kama `{"answer": "Yes, book Tuesday at 10."}`.
Weka `spec.timeout` ya zana kupitia API, hadi sekunde 180 (chaguomsingi
ni 20). Ipe endpoint yako muda wake wa mwisho ulio mfupi kwa sekunde chache
(kwa mfano sekunde 170), ili wakati hakuna anayejibu bado irejeshe kitu ambacho
ejenti anaweza kufanyia kazi, kama
`{"answer": null, "note": "No reply yet. Offer to take a message."}`. Zana
inayofikia `timeout` yake humfikia ejenti kama hitilafu, na host yako lazima
iweke ombi wazi kwa muda huo. Inaposubiri, ejenti humwambia mtu mwingine
kuwa inakagua, husema bado inafanya kazi baada ya takriban sekunde 12, na
kisha hutoa sasisho fupi takriban kila sekunde 15. Hali ya kushikilia hufanya
kazi hapa pia: weka `spec.wait_mode` kuwa `"hold"` na mtu mwingine husikia muziki
badala ya masasisho.

**Jibu kwa whisper.** Endpoint yako hutuma swali na kurejesha jibu mara moja,
kwa mfano `{"status": "asked", "note": "Matthew has been asked; his answer will come as guidance."}`.
Jibu linapowasili, litume kama whisper (hatua ya 3), na ejenti
hulijibu mara moja. Tumia njia hii kwa majibu yanayoweza kuchukua zaidi ya
dakika 10. Simu haishikiliwi: prompt yako inapaswa kumwambia
ejenti afanye nini wakati huo, kama kuendelea kuzungumza na mtu huyo au kutoa
of a kuwampigia tena.

Katika kila hali, eleza kwenye prompt ya ejenti wakati wa kutumia zana na
cha kumwambia mtu mwingine inaposubiri:

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

## Vikomo vya kuzingatia

- Endpoint yako lazima ijibu ndani ya `timeout` ya zana, si zaidi ya **sekunde 180**. Zana katika hali ya kusubiri inaweza
  kuweka simu kwenye kusubiri kwa hadi **sekunde 600** ikiwa na matokeo yanayosubiri.
- Zana inaposubiri, ejenti haimjibu mtu mwingine. Katika hali ya kusubiri
  anasikia muziki; vinginevyo, masasisho mafupi yanayosemwa.
- Ujumbe wa kunong'ona una upeo wa **herufi 1000**.
- Uwasilishaji wa `telephony.turn` hutokea angalau mara moja na unaweza kuwa nje ya mpangilio.

## Orodha ya ukaguzi wa usalama

- Weka ufunguo wa API kwenye seva yako.
- Thibitisha sahihi za ThunderPhone kwenye webhook na maombi ya zana, na
  siri ya utiaji sahihi ya Slack kwenye maombi ya Slack. Sahihi hizi mbili za ThunderPhone
  zinatumia siri tofauti: uwasilishaji wa webhook hutumia siri ya endpoint
  hiyo ya webhook, na maombi ya zana hutumia siri ya webhook ya shirika lako
  kutoka [`GET /v1/webhook`](/api-reference/organizations#legacy-single-url-webhook).
- Amua ni nani anayeruhusiwa kuanzisha simu: angalia kitambulisho cha mtumiaji wa Slack kabla ya kupiga simu.
- Simu za kutoka hufuata sheria sawa na simu nyingine zozote. Tazama
  [Sheria za simu za kutoka](/sw/guides/outbound-calling-laws).

## Itengeneze kwa ejenti ya uandishi wa msimbo

Elekeza ejenti yako ya uandishi wa msimbo kwenye [seva ya MCP ya hati](/sw/guides/docs-mcp) na kwenye
ukurasa huu, kisha uombe "boti ya Slack ya ejenti wangu wa ThunderPhone inayofuata
mwongozo huu". Zeus, msaidizi katika programu ya ThunderPhone, anaweza kusanidi upande wa
ejenti (endpoint ya webhook, zana na mistari ya prompt) na kuandika
msimbo wa kuanzia wa boti kwenye gumzo.
