ThunderPhone v3 இப்போது கிடைக்கிறது.நீங்களே தொடங்கலாம்; நிமிடத்திற்கு 2¢ முதல்.அறிவிப்பைப் படிக்கவும்

Developer cookbook

Slack அல்லது அரட்டை செயலியிலிருந்து அழைப்புகளை இயக்குங்கள்

பொது API-ஐப் பயன்படுத்தி, அழைப்புகளைத் தொடங்கும், அவற்றை நேரலையில் பின்தொடரும், ஏஜென்டை வழிநடத்தும் மற்றும் அதன் கேள்விகளுக்குப் பதிலளிக்கும் உங்கள் சொந்த Slack, Teams அல்லது வலை-அரட்டை போட்டை உருவாக்குங்கள்.

உங்கள் அணி ஏற்கனவே பயன்படுத்தும் அரட்டை செயலியிலிருந்து ஒரு ஏஜென்ட்டை இயக்கலாம். ஒரு செய்தி அழைப்பைத் தொடங்கும். அழைப்பு ஒரு தொடரிழையில் நேரலையாக நடைபெறும். தொடரிழையில் பதிலளிப்பது ஏஜென்ட்டை வழிநடத்தும். ஏஜென்ட்டுக்கு ஒரு முடிவு தேவைப்படும்போது, அது அங்கே உங்களிடம் கேட்டு உங்கள் பதிலுக்காகக் காத்திருக்கும்.

ThunderPhone இந்த பாட்டை உங்களுக்காக ஹோஸ்ட் செய்யாது. நீங்கள் (அல்லது உங்கள் கோடிங் ஏஜென்ட்) உங்கள் அரட்டை செயலியை பொது API-யுடன் இணைக்கும் ஒரு சிறிய சர்வரை உருவாக்குவீர்கள். இந்தப் பக்கம் அதன் கூறுகளைக் காட்டுகிறது. Slack, Microsoft Teams, Discord அல்லது தனிப்பட்ட இணைய அரட்டைப் பக்கத்திற்கு இவை ஒன்றே; எடுத்துக்காட்டுகள் Slack-ஐப் பயன்படுத்துகின்றன.

இது எவ்வாறு ஒன்றிணைகிறது

அரட்டையில் நீங்கள் செய்வதுஉங்கள் பாட் அழைப்பதுஎன்ன நடக்கிறது
"Comcast-ஐ அழைத்து செயலிழப்பு ETA-வைப் பெறு" என அனுப்புகசெய்தியை 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. செய்தியிலிருந்து அழைப்பைத் தொடங்குக

உங்கள் bot ஒரு செய்தியைப் பெறும்போது (நேரடிச் செய்தி அல்லது @mention), 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 thread-க்கு எதிராகச் சேமிக்கவும் (channel மற்றும் செய்தியின் ts) மற்றும் thread-இல் பதிலளிக்கவும் ("அழைக்கிறது…"). idempotency_key-ஐ channel மற்றும் செய்தியின் ts-இலிருந்து உருவாக்கவும் (ts என்பது அதன் channel-க்குள் மட்டுமே தனித்துவமானது), இதனால் மீண்டும் முயற்சிக்கப்படும் Slack event இரண்டாவது அழைப்பை மேற்கொள்ளாது. கோரிக்கையில் எண்ணுக்குப் பதிலாக ஒரு நபரின் பெயர் இருந்தால், உங்கள் bot முதலில் எண்ணைத் தேடிக் கண்டறியும். நீங்கள் அனுப்பும் to_number-ஐ மட்டுமே ThunderPhone அழைக்கும்.

2. thread-இல் அழைப்பைப் பின்தொடர்க

ஒவ்வொரு telephony.turn webhook-லும் call_id, பேசுபவர் (role: ஏஜென்ட்டுக்கு assistant, மற்ற நபருக்கு user), text மற்றும் turn-இன் position ஆகியவற்றைக் கொண்டிருக்கும். call_id மூலம் thread-ஐத் தேடி, வரியைப் பதிவிடவும்.

  • செயல்படுவதற்கு முன் ஒவ்வொரு webhook-ஐயும் சரிபார்க்கவும். பார்க்கவும் webhook கையொப்பங்களைச் சரிபார்க்கவும்.
  • envelope-இன் event_id அடிப்படையில் நகல்களை நீக்கி, position அடிப்படையில் வரிசைப்படுத்தவும். விநியோகம் குறைந்தபட்சம் ஒருமுறையாவது நிகழும்; turn-கள் வரிசை தவறி வரலாம்.
  • பரபரப்பான அழைப்பு thread-ஐ நிரப்பக்கூடியதாக இருந்தால் வரிகளைத் தொகுக்கவும்; ஒவ்வொரு வரிக்கும் ஒரு செய்தியைப் பதிவிடுவதைவிட சில வினாடிகளுக்கு ஒருமுறை பதிவிடுவது சிறப்பாகப் படிக்கும்.

telephony.complete வரும்போது, அழைப்பு எவ்வாறு முடிந்தது (status மற்றும் end_reason), summary, மற்றும் பிரித்தெடுக்கப்பட்ட தரவுகள் ஏதேனும் இருந்தால் அவற்றைப் பதிவிட்டு, thread-ஐ நிறைவு செய்யவும். புலங்களுக்காக அழைப்பு நிறைவு என்பதைப் பார்க்கவும்.

3. thread-இலிருந்து அழைப்பை வழிநடத்துக

நேரலையில் உள்ள அழைப்பின் thread-இல் யாராவது பதிலளிக்கும்போது, ஏஜென்ட் ஒரு கேள்விக்கான பதிலுக்காகக் காத்திருக்கவில்லை என்றால் (படி 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."}'

ஏஜென்ட் அதைத் தனிப்பட்ட முறையில் கேட்டு, தனது அடுத்த turn-இல் இணைத்துக்கொள்ளும்; மற்ற நபர் கிசுகிசுவை ஒருபோதும் கேட்கமாட்டார். ஒரு கிசுகிசு 1 முதல் 1000 எழுத்துகள் வரை இருக்கலாம். 409 என்பது அழைப்பு இனி நேரலையில் இல்லை என்பதைக் குறிக்கும்: அழைப்பு முடிந்துவிட்டதாக thread-க்கு தெரிவிக்கவும்.

4. ஏஜென்ட் உங்களிடம் கேட்கச் செய்யுங்கள்

உங்கள் சர்வரை அழைக்கும், எடுத்துக்காட்டாக ஒரு question அளவுருவைக் கொண்ட ask_owner என்ற டூலை ஏஜென்ட்டுக்கு வழங்குங்கள். அதை ஒரு API இணைப்பாக உருவாக்கி ஏஜென்ட்டுடன் இணைக்கவும். ஒவ்வொரு டூல் கோரிக்கையும் அழைப்பை அதன் X-ThunderPhone-Call-ID தலைப்பில் கொண்டிருக்கும்.

பதிலைத் திரும்பப் பெற மூன்று வழிகள் உள்ளன.

அழைப்பை நிறுத்தி வையுங்கள் (அதிகபட்சம் 10 நிமிடங்கள்). டூலை hold முறைக்கு அமைக்கவும்: spec.wait_mode "hold" மற்றும் spec.timeout ஐ 600 வினாடிகள் வரை அமைக்கவும் (timeout இல்லாமல் hold 20 வினாடிகள் நீடிக்கும்), இதை API மூலம் செய்யுங்கள் (டாஷ்போர்டு எடிட்டரில் இன்னும் எந்தப் புலமும் இல்லை). உங்கள் endpoint கேள்வியை அழைப்பின் thread-இல் பதிவிட்டு, உடனடியாக pending முடிவுடன் பதிலளிக்கும்:

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

மற்ற நபர் ஏஜென்ட்டிடமிருந்து ஒரு வரியைக் கேட்பார், பின்னர் hold இசை ஒலிக்கும். தொலைபேசி மெனு அல்லது voicemail-இல் ஏஜென்ட் அதற்குப் பதிலாகப் பேசும் புதுப்பிப்புகளைப் பயன்படுத்தும்; மேலும் full-duplex ஏஜென்ட் hold செய்யாது: அது pending பதிலை முடிவாகப் பெறும். thread-இல் பதில் வந்ததும், அதை 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-க்கு முன் யாரும் பதிலளிக்கவில்லை என்றால், பதில் வரவில்லை என்று ஏஜென்ட்டிடம் தெரிவிக்கப்பட்டு, மற்ற நபருக்கு அடுத்த படிகளை அது வழங்கும். அழைப்புக்கான கேள்வி pending நிலையில் இருக்கும்போது, அதன் thread-இல் வரும் அடுத்த பதில் அதற்குப் பதிலளிக்கும்: அதை டூல் முடிவாக வழங்குங்கள்; அதே நேரத்தில் கிசுகிசுவாகவும் அனுப்பாதீர்கள் (டூல் திரும்பிய பிறகே கிசுகிசு ஏஜென்ட்டை அடையும்). பார்க்கவும் நீண்ட காத்திருப்புகள்.

கோரிக்கையிலேயே காத்திருங்கள் (அதிகபட்சம் 3 நிமிடங்கள்). உங்கள் endpoint கேள்வியைப் பதிவிட்டு, பதிலுக்காகக் காத்திருந்து அதைத் திருப்பி அனுப்பும், எடுத்துக்காட்டாக {"answer": "Yes, book Tuesday at 10."}. API மூலம் டூலின் spec.timeout ஐ 180 வினாடிகள் வரை அமைக்கவும் (இயல்புநிலை 20). யாரும் பதிலளிக்காதபோதும் ஏஜென்ட் செயல்படக்கூடிய ஒன்றை அது திருப்பி அனுப்பும் வகையில், உங்கள் endpoint-க்கு சில வினாடிகள் குறைவான தனிப்பட்ட deadline-ஐ வழங்குங்கள் (எடுத்துக்காட்டாக 170 வினாடிகள்), உதாரணமாக {"answer": null, "note": "No reply yet. Offer to take a message."}. தனது timeout-ஐ எட்டும் டூல் ஏஜென்ட்டை பிழையாக அடையும்; மேலும் உங்கள் host அந்த அளவு நேரம் கோரிக்கையைத் திறந்தே வைத்திருக்க வேண்டும். அது காத்திருக்கும்போது, ஏஜென்ட் மற்ற நபரிடம் சரிபார்ப்பதாகக் கூறி, சுமார் 12 வினாடிகளுக்குப் பிறகும் இன்னும் செயல்படுவதாகச் சொல்லும்; பின்னர் ஒவ்வொரு 15 வினாடிகளுக்கும் சுருக்கமான புதுப்பிப்பை வழங்கும். இங்கும் hold முறை செயல்படும்: spec.wait_mode ஐ "hold" என அமைத்தால், புதுப்பிப்புகளுக்குப் பதிலாக மற்ற நபர் இசையைக் கேட்பார்.

கிசுகிசு மூலம் பதிலளியுங்கள். உங்கள் endpoint கேள்வியைப் பதிவிட்டு உடனடியாகத் திரும்பும், எடுத்துக்காட்டாக {"status": "asked", "note": "Matthew has been asked; his answer will come as guidance."}. பதில் வந்ததும், அதை கிசுகிசுவாக அனுப்புங்கள் (படி 3); ஏஜென்ட் உடனடியாக அதற்குப் பதிலளிக்கும். 10 நிமிடங்களுக்கும் மேலாக ஆகக்கூடிய பதில்களுக்கு இதைப் பயன்படுத்துங்கள். அழைப்பு hold-இல் வைக்கப்படாது: அந்த நேரத்தில் என்ன செய்ய வேண்டும் என்பதை உங்கள் 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.

திட்டமிட வேண்டிய வரம்புகள்

  • உங்கள் எண்ட்பாயிண்ட், கருவியின் timeout காலவரம்பிற்குள், அதிகபட்சம் 180 விநாடிகளில் பதிலளிக்க வேண்டும். ஹோல்ட் பயன்முறையில் உள்ள கருவி, நிலுவையில் உள்ள முடிவுடன் அழைப்பை அதிகபட்சம் 600 விநாடிகள் ஹோல்டில் வைத்திருக்கலாம்.
  • ஒரு கருவி காத்திருக்கும்போது, ஏஜென்ட் மறுபுற நபருக்குப் பதிலளிக்காது. ஹோல்ட் பயன்முறையில் அவர்கள் இசையைக் கேட்பார்கள்; இல்லையெனில், சுருக்கமான பேச்சு புதுப்பிப்புகளைக் கேட்பார்கள்.
  • ஒரு கிசுகிசு அதிகபட்சம் 1000 எழுத்துகள் மட்டுமே இருக்கலாம்.
  • telephony.turn டெலிவரி குறைந்தபட்சம் ஒருமுறை நிகழும்; அது வரிசைக்கு மாறாக இருக்கலாம்.

பாதுகாப்புச் சரிபார்ப்புப் பட்டியல்

  • API விசையை உங்கள் சர்வரில் வைத்திருங்கள்.
  • வெப்ஹுக்குகள் மற்றும் கருவி கோரிக்கைகளில் ThunderPhone-இன் கையொப்பங்களையும், Slack கோரிக்கைகளில் Slack-இன் சைனிங் சீக்ரெட்டையும் சரிபார்க்கவும். இரண்டு ThunderPhone கையொப்பங்களும் வேறுபட்ட சீக்ரெட்டுகளைப் பயன்படுத்துகின்றன: வெப்ஹுக் டெலிவரிகள் வெப்ஹுக் எண்ட்பாயிண்ட்டின் சொந்த சீக்ரெட்டைப் பயன்படுத்துகின்றன; கருவி கோரிக்கைகள் உங்கள் நிறுவனத்தின் GET /v1/webhook இலுள்ள வெப்ஹுக் சீக்ரெட்டைப் பயன்படுத்துகின்றன.
  • அழைப்புகளை யார் தொடங்கலாம் என்பதைத் தீர்மானிக்கவும்: அழைப்பை மேற்கொள்வதற்கு முன் Slack பயனர் ID-யைச் சரிபார்க்கவும்.
  • வெளிச்செல்லும் அழைப்புகள் மற்ற எல்லா அழைப்புகளுக்கும் பொருந்தும் அதே விதிகளைப் பின்பற்றுகின்றன. வெளிச்செல்லும் அழைப்புச் சட்டங்கள் என்பதைப் பார்க்கவும்.

கோடிங் ஏஜென்ட்டுடன் உருவாக்கவும்

உங்கள் கோடிங் ஏஜென்ட்டை ஆவண MCP சர்வர் மற்றும் இந்தப் பக்கத்திற்குச் சுட்டிக்காட்டி, "இந்த வழிகாட்டியைப் பின்பற்றும் என் ThunderPhone ஏஜென்ட்டிற்கான Slack பாட்" ஒன்றைக் கேளுங்கள். ThunderPhone செயலியில் உள்ள உதவியாளரான Zeus, ஏஜென்ட்டின் தரப்பை அமைக்கலாம் (வெப்ஹுக் எண்ட்பாயிண்ட், கருவி மற்றும் prompt வரிகள்) மற்றும் அரட்டையில் பாட்டிற்கான தொடக்கக் குறியீட்டை எழுதலாம்.