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

Другият човек чува една реплика от агента, след което музика при задържане. В телефонно меню или гласова поща агентът използва вместо това устни актуализации, а пълнодуплексният агент не задържа: получава чакащия отговор като резултат. Когато отговорът пристигне в нишката, го доставете чрез 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 за уебкуки и заявки към инструменти, както и signing secret на Slack за заявките на Slack. Двата подписа на ThunderPhone използват различни тайни: доставките на уебкуки използват собствената тайна на крайната точка за уебкуки, а заявките към инструменти използват тайната за уебкуки на вашата организация от GET /v1/webhook.
  • Решете кой може да стартира разговори: проверявайте потребителския идентификатор в Slack, преди да осъществите такъв.
  • Изходящите разговори следват същите правила като всички останали. Вижте Закони за изходящи обаждания.

Създайте го с агент за програмиране

Насочете своя агент за програмиране към MCP сървъра за документация и към тази страница и поискайте „Slack бот за моя ThunderPhone агент, който следва това ръководство“. Zeus, асистентът в приложението ThunderPhone, може да настрои частта на агента (крайната точка за уебкуки, инструмента и редовете за подканата) и да напише начален код за бота в чата.