ThunderPhone v3 је сада доступан.Почните самостално, већ од 2 ¢/мин.Прочитајте објаву

Developer cookbook

Покрећите позиве из Slack-а или апликације за ћаскање

Направите сопственог Slack, Teams или веб-чет бота који покреће позиве, прати их уживо, усмерава агента и одговара на његова питања помоћу јавног API-ја.

Можете управљати гласовним агентом из апликације за ћаскање коју Ваш тим већ користи. Порука покреће позив. Позив се одвија уживо у нити. Одговор у нити усмерава агента. Када је агенту потребна одлука, пита Вас тамо и чека Ваш одговор.

ThunderPhone не хостује овај бот уместо Вас. Ви (или Ваш агент за програмирање) правите мали сервер који повезује Вашу апликацију за ћаскање са јавним API-јем. Ова страница приказује делове. Исти су за Slack, Microsoft Teams, Discord или приватну веб страницу за ћаскање; примери користе Slack.

Како се све повезује

Ово радите у ћаскањуВаш бот позиваШта се дешава
Пошаљите „Позовите Comcast и сазнајте процењено време отклањања квара“POST /v1/call са поруком као contextАгент позива. Ваш бот отвара нит за позив
Пратите нитПрима telephony.turn вебхуковеСвака реченица коју изговори агент или друга особа појављује се у нити
Одговорите у нити током позиваPOST /v1/calls/{call_id}/whisperАгент приватно прима Вашу белешку и поступа по њој. Друга особа је никада не чује
Одговорите на питање агентаВаша крајња тачка алатке враћа Ваш одговор или га касније испоручује помоћу POST /v1/calls/{call_id}/tool-resultsАгент наставља позив са њим; у режиму чекања друга особа у међувремену чује музику на чекању
Прочитајте резултатПрима telephony.completeВаш бот објављује резиме и исход

Ваш бот чува једно мапирање: која нит ћаскања припада ком call_id.

Пре него што почнете

  • API кључ, који се чува на Вашем серверу и никада у прегледачу или ћаскању. Направите га у оквиру Подешавања организације → Кључеви (погледајте Кључеви).
  • Број са омогућеним одлазним позивима и агент за позиве. Порука постаје context по позиву, тако да један општи агент обрађује сваки задатак.
  • Сервер који може да прима вебхукове, као што су Railway, Fly.io, Render или Ваш сопствени хост.
  • Крајња тачка вебхука која показује на тај сервер и претплаћена је на telephony.turn и telephony.complete. Догађаји скретања шаљу се само крајњим тачкама које их наводе. Погледајте Вебхукови. За догађаје скретања потребно је да снимање позива агента буде укључено, а за summary на крају позива потребно је подешавање агента Генериши резиме позива; без њих та поља остају празна.
  • Ваша сопствена апликација за ћаскање. За Slack, направите апликацију у свом радном простору на api.slack.com/apps.

1. Покрените позив из поруке

Када ваш бот прими поруку (директну поруку или @помињање), одмах потврдите Slack захтев (Slack поново шаље све што није потврђено у року од 3 секунде), а остало обавите у позадини. Проверите да ли пошиљалац сме да упућује позиве, а затим покрените позив са поруком као 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"
  }'

Сачувајте враћени call_id уз Slack нит (channel и ts поруке) и одговорите у нити („Позивамо…“). Изградите idempotency_key од канала и ts поруке (ts је јединствен само у оквиру свог канала), тако да поновљени Slack догађај не покрене други позив. Ако захтев наводи особу уместо броја, ваш бот прво проналази број. ThunderPhone позива само to_number који пошаљете.

2. Пратите позив у нити

Сваки telephony.turn вебхук садржи call_id, говорника (role: assistant за агента, user за другу особу), text и position реда. Пронађите нит према call_id и објавите ред.

  • Проверите сваки вебхук пре него што поступите према њему. Погледајте Проверите потписе вебхукова.
  • Уклоните дупликате према event_id омотача и поређајте према position. Испорука се врши најмање једном, а редови могу стићи ван редоследа.
  • Групишите редове ако би активан позив преплавио нит; објављивање на сваких неколико секунди чита се боље од једне поруке по реду.

Када стигне telephony.complete, објавите како је позив завршен (његов status и end_reason), summary и све издвојене податке, а затим означите нит као завршену. Погледајте Завршетак позива за поља.

3. Усмеравајте позив из нити

Када неко одговори у нити активног позива, пошаљите одговор као шапат, осим ако агент чека одговор на питање (корак 4), у ком случају је одговор одговор на питање:

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

Агент га чује приватно и укључује у свој следећи ред; друга особа никада не чује сам шапат. Шапат садржи од 1 до 1000 знакова. Код 409 значи да позив више није активан: обавестите нит да је позив завршен.

4. Нека Вам агент постави питање

Дајте агенту алат, на пример ask_owner са једним параметром question, који позива Ваш сервер. Направите га као API везу и повежите га са агентом. Сваки захтев алата преноси позив у заглављу X-ThunderPhone-Call-ID.

Постоје три начина да вратите одговор.

Задржите позив (до 10 минута). Подесите алат у режим задржавања: spec.wait_mode "hold" и spec.timeout до 600 секунди (без временског ограничења задржавање траје 20 секунди), путем API-ја (уређивач на контролној табли још нема ниједно од тих поља). Ваш крајњи сервер објављује питање у нит позива и одмах одговара резултатом на чекању:

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

Друга особа чује једну реченицу агента, а затим музику на чекању. У телефонском менију или говорној пошти агент уместо тога користи говорна обавештења, а full-duplex агент не задржава позив: добија одговор на чекању као резултат. Када одговор стигне у нит, испоручите га помоћу 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."}}'

Музика се постепено утишава и агент наставља са Вашим одговором. Ако нико не одговори пре timeout, агенту се каже да одговор није стигао и нуди другој особи следеће кораке. Док је питање на чекању за позив, следећи одговор у његовој нити одговара на њега: испоручите га као резултат алата и немојте га истовремено слати као шапат (шапат стиже до агента тек након повратка алата). Погледајте Дуга чекања.

Сачекајте у захтеву (до 3 минута). Ваш крајњи сервер објављује питање, чека одговор и враћа га, на пример {"answer": "Yes, book Tuesday at 10."}. Подесите spec.timeout алата путем API-ја, до 180 секунди (подразумевано је 20). Дајте крајњем серверу сопствени рок неколико секунди краћи (на пример 170 секунди), тако да, када нико не одговори, и даље врати нешто на шта агент може да реагује, на пример {"answer": null, "note": "No reply yet. Offer to take a message."}. Алат који достигне свој timeout стиже до агента као грешка, а Ваш хост мора држати захтев отвореним толико дуго. Док чека, агент говори другој особи да проверава, каже да још ради након око 12 секунди, а затим даје кратко обавештење отприлике сваких 15 секунди. Режим задржавања ради и овде: подесите spec.wait_mode на "hold" и друга особа чује музику уместо обавештења.

Одговорите шапатом. Ваш крајњи сервер објављује питање и одмах враћа, на пример {"status": "asked", "note": "Matthew has been asked; his answer will come as guidance."}. Када одговор стигне, пошаљите га као шапат (корак 3), а агент одмах одговара на њега. Користите ово за одговоре који могу трајати дуже од 10 минута. Позив није задржан: Ваш упит треба да каже агенту шта да ради у међувремену, на пример да прави друштво особи или понуди да је позове касније.

У сваком случају, у упиту агента наведите када да користи алат и шта да каже другој особи док чека:

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.

Ограничења која треба планирати

  • Ваша крајња тачка мора да одговори у оквиру временског ограничења алатке timeout, највише 180 секунди. Алатка у режиму чекања може да задржи позив на чекању до 600 секунди са резултатом на чекању.
  • Док алатка чека, агент не одговара другој особи. У режиму чекања чује музику; у супротном, кратка говорна ажурирања.
  • Шапат има највише 1000 знакова.
  • Испорука telephony.turn врши се најмање једном и може бити ван редоследа.

Безбедносна контролна листа

  • Чувајте API кључ на свом серверу.
  • Проверите ThunderPhone потписе на веб-кукама и захтевима алатки, као и Slack тајну за потписивање на Slack захтевима. Два ThunderPhone потписа користе различите тајне: испоруке веб-кука користе сопствену тајну крајње тачке веб-куке, а захтеви алатки користе тајну веб-куке ваше организације из GET /v1/webhook.
  • Одлучите ко сме да започне позиве: проверите Slack кориснички ID пре упућивања позива.
  • Одлазни позиви подлежу истим правилима као и сви други. Погледајте законе о одлазним позивима.

Направите га уз помоћ агента за програмирање

Усмерите свог агента за програмирање на MCP сервер документације и на ову страницу, па затражите „Slack бот за мог ThunderPhone агента који прати ово упутство“. Zeus, помоћник у ThunderPhone апликацији, може да подеси страну агента (крајњу тачку веб-куке, алатку и линије упита) и да напише почетни код за бота у ћаскању.