ThunderPhone v3 ir klāt.Sāciet patstāvīgi — no 2 ¢/min.Lasīt paziņojumu

Developer cookbook

Veiciet zvanus no Slack vai tērzēšanas lietotnes

Izveidojiet savu Slack, Teams vai tīmekļa tērzēšanas robotu, kas sāk zvanus, seko tiem tiešraidē, vada balss aģentu un atbild uz tā jautājumiem, izmantojot publisko API.

Varat vadīt balss aģentu no tērzēšanas lietotnes, ko jūsu komanda jau izmanto. Ziņojums sāk zvanu. Zvans notiek tiešraidē pavedienā. Atbilde pavedienā virza balss aģentu. Kad balss aģentam nepieciešams lēmums, tas jautā jums tur un gaida jūsu atbildi.

ThunderPhone neuztur šo robotu jūsu vietā. Jūs (vai jūsu programmēšanas aģents) izveidojat nelielu serveri, kas savieno jūsu tērzēšanas lietotni ar publisko API. Šajā lapā ir parādītas nepieciešamās daļas. Tās ir vienādas Slack, Microsoft Teams, Discord vai privātai tīmekļa tērzēšanas lapai; piemēros izmantots Slack.

Kā tas darbojas kopā

Jūs darāt šo tērzēšanāJūsu robots izsaucKas notiek
Nosūtiet "Call Comcast and get the outage ETA"POST /v1/call ar ziņojumu kā contextBalss aģents veic zvanu. Jūsu robots atver zvana pavedienu
Skatiet pavedienuSaņem telephony.turn tīmekļa aizķeresKatra balss aģenta vai otras personas pateiktā rinda parādās pavedienā
Atbildiet pavedienā zvana laikāPOST /v1/calls/{call_id}/whisperBalss aģents privāti saņem jūsu piezīmi un rīkojas atbilstoši tai. Otra persona to nekad nedzird
Atbildiet uz balss aģenta jautājumuJūsu rīka galapunkts atgriež jūsu atbildi vai piegādā to vēlāk ar POST /v1/calls/{call_id}/tool-resultsBalss aģents turpina zvanu ar to; gaidīšanas režīmā otra persona tikmēr dzird gaidīšanas mūziku
Izlasiet rezultātuSaņem telephony.completeJūsu robots publicē kopsavilkumu un iznākumu

Jūsu robots uztur vienu sasaisti: kurš tērzēšanas pavediens pieder kuram call_id.

Pirms sākat

  • API atslēga, kas tiek glabāta jūsu serverī, nevis pārlūkprogrammā vai tērzēšanā. Izveidojiet to sadaļā Integrācijas → API atslēgas (skatiet Izveidot servera API atslēgu).
  • Numurs ar iespējotu izejošo zvanu funkciju un balss aģents zvaniem. Ziņojums kļūst par katra zvana context, tāpēc viens vispārīgs balss aģents apstrādā katru uzdevumu.
  • Serveris, kas var saņemt tīmekļa aizķeres, piemēram, Railway, Fly.io, Render vai jūsu pašu mitinātā vide.
  • Tīmekļa aizķeres galapunkts, kas norāda uz šo serveri un ir abonējis telephony.turn un telephony.complete. Sarunas posmu notikumi tiek sūtīti tikai uz galapunktiem, kuros tie ir norādīti. Skatiet Tīmekļa aizķeres. Sarunas posmu notikumiem ir nepieciešams iespējots balss aģenta zvanu ieraksts, un zvana beigu summary ir nepieciešams balss aģenta iestatījums Ģenerēt zvana kopsavilkumu; bez tiem šie lauki paliek tukši.
  • Jūsu pašu tērzēšanas lietotne. Slack vajadzībām izveidojiet lietotni savā darbvietā vietnē api.slack.com/apps.

1. Sāciet zvanu no ziņojuma

Kad jūsu robots saņem ziņojumu (tiešo ziņojumu vai @pieminējumu), nekavējoties apstipriniet Slack pieprasījumu (Slack atkārtoti nosūta visu, kas netiek apstiprināts 3 sekunžu laikā), un pārējo veiciet fonā. Pārbaudiet, vai sūtītājam ir atļauts veikt zvanus, pēc tam sāciet zvanu, izmantojot ziņojumu kā 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"
  }'

Saglabājiet atgriezto call_id kopā ar Slack pavedienu (channel un ziņojuma ts) un atbildiet pavedienā ("Zvans tiek veikts…"). Veidojiet idempotency_key no kanāla un ziņojuma ts (ts ir unikāls tikai savā kanālā), lai atkārtoti nosūtīts Slack notikums neveiktu otru zvanu. Ja pieprasījumā ir norādīta persona, nevis numurs, jūsu robots vispirms atrod numuru. ThunderPhone zvana tikai uz jūsu nosūtīto to_number.

2. Sekojiet zvanam pavedienā

Katrs telephony.turn tīmekļa aizķeres notikums ietver call_id, runātāju (role: assistant balss aģentam, user otrai personai), text un gājiena position. Atrodiet pavedienu pēc call_id un publicējiet rindu.

  • Pārbaudiet katru tīmekļa aizķeres notikumu, pirms rīkojaties. Skatiet Tīmekļa aizķeres parakstu pārbaude.
  • Dublētus notikumus atmetiet pēc aploksnes event_id un kārtojiet pēc position. Piegāde notiek vismaz vienu reizi, un gājieni var pienākt nepareizā secībā.
  • Grupējiet rindas, ja aktīvs zvans pārpludinātu pavedienu; publicēšana ik pēc dažām sekundēm ir labāk lasāma nekā viens ziņojums katrai rindai.

Kad pienāk telephony.complete, publicējiet, kā zvans beidzās (tā status un end_reason), summary un visus iegūtos datus, pēc tam noslēdziet pavedienu. Laukus skatiet sadaļā Zvans pabeigts.

3. Virziet zvanu no pavediena

Kad kāds atbild aktīva zvana pavedienā, nosūtiet atbildi kā čukstu, ja vien balss aģents negaida atbildi uz jautājumu (4. darbība); tādā gadījumā atbilde ir risinājums:

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

Balss aģents to dzird privāti un iekļauj savā nākamajā gājienā; otra persona pašu čukstu nekad nedzird. Čuksta garums ir no 1 līdz 1000 rakstzīmēm. 409 nozīmē, ka zvans vairs nav aktīvs: paziņojiet pavedienā, ka zvans ir beidzies.

4. Ļaujiet aģentam jums jautāt

Piešķiriet aģentam rīku, piemēram, ask_owner ar vienu parametru question, kas izsauc jūsu serveri. Izveidojiet to kā API savienojumu un saistiet to ar aģentu. Katrs rīka pieprasījums pārsūta zvanu tā X-ThunderPhone-Call-ID galvenē.

Ir trīs veidi, kā saņemt atbildi.

Aizturiet zvanu (līdz 10 minūtēm). Iestatiet rīkam aizturēšanas režīmu: spec.wait_mode "hold" un spec.timeout līdz 600 sekundēm (bez taimauta aizturēšana ilgst 20 sekundes), izmantojot API, vai lūdziet Zeus tos iestatīt (lietotnes redaktoros pagaidām nav neviena no šiem laukiem). Jūsu galapunkts publicē jautājumu zvana pavedienā un nekavējoties atbild ar gaidošu rezultātu:

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

Sarunas partneris dzird vienu aģenta teikumu, pēc tam — aizturēšanas mūziku. Tālruņa izvēlnē vai balss pastā aģents tā vietā izmanto mutiskus atjauninājumus, bet pilndupleksa aģents neaiztur zvanu: tas saņem gaidošo atbildi kā rezultātu. Kad atbilde nonāk pavedienā, piegādājiet to ar 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."}}'

Mūzika pakāpeniski apklust, un aģents turpina ar jūsu atbildi. Ja neviens neatbild pirms timeout, aģentam tiek paziņots, ka atbilde nav saņemta, un tas sarunas partnerim piedāvā nākamos soļus. Kamēr zvanam ir gaidošs jautājums, nākamā atbilde tā pavedienā atbild uz to: piegādājiet to kā rīka rezultātu un nesūtiet to arī kā čuksta ziņojumu (čuksta ziņojums sasniedz aģentu tikai pēc rīka atgriešanās). Skatiet Ilgstoša gaidīšana.

Gaidiet pieprasījumā (līdz 3 minūtēm). Jūsu galapunkts publicē jautājumu, gaida atbildi un to atgriež, piemēram, {"answer": "Yes, book Tuesday at 10."}. Iestatiet rīka spec.timeout, izmantojot API, līdz 180 sekundēm (noklusējums ir 20). Piešķiriet savam galapunktam par dažām sekundēm īsāku termiņu (piemēram, 170 sekundes), lai gadījumā, ja neviens neatbild, tas joprojām atgrieztu kaut ko, ar ko aģents var rīkoties, piemēram, {"answer": null, "note": "No reply yet. Offer to take a message."}. Rīks, kas sasniedz savu timeout, nonāk pie aģenta kā kļūda, un jūsu mitināšanas videi pieprasījums ir jātur atvērts tik ilgi. Kamēr tas gaida, aģents sarunas partnerim pasaka, ka pārbauda, pēc aptuveni 12 sekundēm paziņo, ka joprojām strādā, un pēc tam sniedz īsu atjauninājumu aptuveni ik pēc 15 sekundēm. Arī šeit darbojas aizturēšanas režīms: iestatiet spec.wait_mode uz "hold", un sarunas partneris atjauninājumu vietā dzirdēs mūziku.

Atbildiet ar čuksta ziņojumu. Jūsu galapunkts publicē jautājumu un nekavējoties atgriež atbildi, piemēram, {"status": "asked", "note": "Matthew has been asked; his answer will come as guidance."}. Kad atbilde nonāk, nosūtiet to kā čuksta ziņojumu (3. darbība), un aģents uz to uzreiz reaģē. Izmantojiet šo iespēju atbildēm, kuru saņemšana var aizņemt vairāk nekā 10 minūtes. Zvans netiek aizturēts: jūsu uzvednē aģentam jānorāda, ko darīt pa šo laiku, piemēram, uzturēt sarunas partnerim kompāniju vai piedāvāt viņam atzvanīt.

Katrā gadījumā aģenta uzvednē norādiet, kad izmantot rīku un ko teikt sarunas partnerim, kamēr tas gaida:

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.

Ierobežojumi, kas jāņem vērā

  • Jūsu galapunktam jāatbild rīka timeout laikā, ne ilgāk kā 180 sekundēs. Rīks aizturēšanas režīmā var turēt zvanu aizturētu līdz 600 sekundēm, kamēr tiek gaidīts rezultāts.
  • Kamēr rīks gaida, balss aģents neatbild otrai personai. Aizturēšanas režīmā tā dzird mūziku; pretējā gadījumā — īsus balss paziņojumus.
  • Čuksts var būt ne garāks par 1000 rakstzīmēm.
  • telephony.turn piegāde notiek vismaz vienu reizi un var nebūt secīga.

Drošības kontrolsaraksts

  • Glabājiet API atslēgu savā serverī.
  • Pārbaudiet ThunderPhone parakstus tīmekļa aizķerēs un rīku pieprasījumos, kā arī Slack parakstīšanas noslēpumu Slack pieprasījumos. Abi ThunderPhone paraksti izmanto atšķirīgus noslēpumus: tīmekļa aizķeres piegādes izmanto tīmekļa aizķeres galapunkta paša noslēpumu, bet rīku pieprasījumi izmanto jūsu organizācijas tīmekļa aizķeres noslēpumu no GET /v1/webhook.
  • Izlemiet, kam ir atļauts sākt zvanus: pirms zvana veikšanas pārbaudiet Slack lietotāja ID.
  • Izejošajiem zvaniem piemēro tos pašus noteikumus kā jebkuriem citiem. Skatiet Izejošo zvanu likumus.

Izveidojiet to ar programmēšanas aģentu

Norādiet savam programmēšanas aģentam uz dokumentācijas MCP serveri un uz šo lapu, un lūdziet izveidot “Slack botu manam ThunderPhone balss aģentam, kas ievēro šo ceļvedi”. Zeus, asistents ThunderPhone lietotnē, var iestatīt balss aģenta pusi (tīmekļa aizķeres galapunktu, rīku un uzvednes rindas) un tērzēšanā uzrakstīt sākuma kodu botam.