ThunderPhone v3 sasa inapatikana.Anza mwenyewe, kuanzia 2¢/dakika.Soma tangazo

Developer cookbook

Endesha simu kutoka Slack au programu ya gumzo

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 gumzoBoti yako inapigaKinachotokea
Tuma "Piga Comcast na upate muda unaokadiriwa wa hitilafu kuisha"POST /v1/call pamoja na ujumbe kama contextEjenti inapiga simu. Boti yako inafungua uzi wa simu
Tazama uziInapokea webhook za telephony.turnKila mstari unaosemwa na ejenti au mtu mwingine huonekana kwenye uzi
Jibu kwenye uzi katikati ya simuPOST /v1/calls/{call_id}/whisperEjenti hupata dokezo lako kwa faragha na kulifanyia kazi. Mtu mwingine haliskii kamwe
Jibu swali la ejentiKituo chako cha zana kinarejesha jibu lako, au kukifikisha baadaye kwa POST /v1/calls/{call_id}/tool-resultsEjenti huendeleza simu kwa jibu hilo; katika hali ya kusubiri mtu mwingine husikia muziki wa kusubiri wakati huo
Soma matokeoInapokea telephony.completeBoti 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).
  • 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. 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.

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:

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.
  • 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 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:

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 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 (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:

{"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:

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.

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:

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

Itengeneze kwa ejenti ya uandishi wa msimbo

Elekeza ejenti yako ya uandishi wa msimbo kwenye seva ya MCP ya hati 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.