ThunderPhone v3 आता लाइव्ह आहे.स्वतःच सुरू करा—2¢/मिनिटपासून.घोषणा वाचा

Developer cookbook

Slack किंवा चॅट अॅपमधून कॉल चालवा

सार्वजनिक API वापरून कॉल सुरू करणारा, त्यांचा थेट मागोवा घेणारा, एजंटला मार्गदर्शन करणारा आणि त्याच्या प्रश्नांची उत्तरे देणारा तुमचा स्वतःचा Slack, Teams किंवा वेब-चॅट बॉट तयार करा.

तुमची टीम आधीपासून वापरत असलेल्या चॅट अॅपमधून तुम्ही एजंट चालवू शकता. एक संदेश कॉल सुरू करतो. कॉल थ्रेडमध्ये थेट चालतो. थ्रेडमधील उत्तर एजंटला मार्गदर्शन करते. एजंटला निर्णयाची आवश्यकता असते तेव्हा तो तिथे तुम्हाला विचारतो आणि तुमच्या उत्तराची वाट पाहतो.

ThunderPhone तुमच्यासाठी हा बॉट होस्ट करत नाही. तुम्ही (किंवा तुमचा कोडिंग एजंट) एक लहान सर्व्हर तयार करता जो तुमच्या चॅट अॅपला सार्वजनिक API शी जोडतो. हे पृष्ठ घटक दाखवते. Slack, Microsoft Teams, Discord किंवा खाजगी वेब चॅट पृष्ठासाठी ते समान आहेत; उदाहरणांमध्ये Slack वापरले आहे.

हे एकत्र कसे कार्य करते

तुम्ही चॅटमध्ये हे करतातुमचा बॉट हे कॉल करतोकाय होते
"Comcast ला कॉल करा आणि सेवाबंदीची अपेक्षित वेळ मिळवा" पाठवासंदेश context म्हणून वापरून POST /v1/callएजंट डायल करतो. तुमचा बॉट कॉलसाठी थ्रेड उघडतो
थ्रेड पाहा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 ची विनंती त्वरित स्वीकारा (3 सेकंदांत स्वीकारल्या न गेलेल्या कोणत्याही गोष्टीसाठी Slack पुन्हा प्रयत्न करते) आणि उर्वरित काम पार्श्वभूमीत करा. पाठवणाऱ्याला कॉल करण्याची परवानगी आहे याची खात्री करा, नंतर संदेश 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. एजंटला तुम्हाला विचारू द्या

एजंटला एक टूल द्या, उदाहरणार्थ एका question पॅरामीटरसह ask_owner, जे तुमच्या सर्व्हरला कॉल करते. ते 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 मिनिटांपेक्षा जास्त वेळ लागू शकणाऱ्या उत्तरांसाठी हे वापरा. कॉल होल्डवर ठेवला जात नाही: तुमच्या prompt ने एजंटला दरम्यान काय करायचे ते सांगितले पाहिजे, उदाहरणार्थ व्यक्तीशी संवाद सुरू ठेवणे किंवा त्यांना परत कॉल करण्याची ऑफर देणे.

प्रत्येक बाबतीत, एजंटच्या prompt मध्ये टूल कधी वापरायचे आणि प्रतीक्षा करताना समोरील व्यक्तीला काय सांगायचे ते नमूद करा:

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.

नियोजनासाठी मर्यादा

  • तुमच्या endpoint ने साधनाच्या timeout मध्ये, कमाल 180 सेकंदांत प्रतिसाद दिला पाहिजे. होल्ड मोडमधील साधन प्रलंबित निकालासह कॉलला कमाल 600 सेकंदांपर्यंत होल्डवर ठेवू शकते.
  • साधन प्रतीक्षा करत असताना, एजंट समोरील व्यक्तीला उत्तर देत नाही. होल्ड मोडमध्ये त्यांना संगीत ऐकू येते; अन्यथा, लहान तोंडी अपडेट्स ऐकू येतात.
  • व्हिस्परची मर्यादा 1000 वर्ण आहे.
  • telephony.turn वितरण किमान एकदा होते आणि ते क्रमाबाहेर येऊ शकते.

सुरक्षा तपासणीसूची

  • API की तुमच्या सर्व्हरवर ठेवा.
  • वेबहुक आणि साधन विनंत्यांवरील ThunderPhone च्या स्वाक्षऱ्या आणि Slack विनंत्यांवरील Slack चे साइनिंग सीक्रेट पडताळा. ThunderPhone च्या दोन स्वाक्षऱ्या वेगवेगळी सीक्रेट्स वापरतात: वेबहुक वितरणांसाठी वेबहुक endpoint चे स्वतःचे सीक्रेट वापरले जाते आणि साधन विनंत्यांसाठी GET /v1/webhook मधील तुमच्या संस्थेचे वेबहुक सीक्रेट वापरले जाते.
  • कॉल कोण सुरू करू शकते ते ठरवा: कॉल लावण्यापूर्वी Slack वापरकर्ता ID तपासा.
  • आउटबाउंड कॉलना इतर कोणत्याही कॉलप्रमाणेच नियम लागू होतात. आउटबाउंड कॉलिंग कायदे पहा.

कोडिंग एजंटसह तयार करा

तुमच्या कोडिंग एजंटला दस्तऐवज MCP सर्व्हर आणि या पेजकडे निर्देशित करा आणि "या मार्गदर्शकाचे पालन करणारा माझ्या ThunderPhone एजंटसाठी Slack बॉट" तयार करण्यास सांगा. ThunderPhone अॅपमधील सहाय्यक Zeus एजंटची बाजू सेट अप करू शकतो (वेबहुक endpoint, साधन आणि prompt ओळी) आणि चॅटमध्ये बॉटसाठी सुरुवातीचा कोड लिहू शकतो.