டெவலப்பர்களுக்கான Call API, Webhooks: கீகள், scopes, நிகழ்வுகள்
Call REST API-இன் நடைமுறைச் சுற்றுப்பயணம்: API கீகளும் scopes-உம், rate limits, பிழைக் கையாளுதல், கையொப்பமிட்ட webhooks, endpoints-ஐ நிர்வகிக்கும் Developers பக்கம்.
விரைவிலோ தாமதமாகவோ ஒரு தொலைபேசி அமைப்பு வேறொன்றுடன் பேச வேண்டியிருக்கும்: அழைப்பு முடியும்போதே அதைக் காட்ட வேண்டிய CRM, யார் அழைத்தார் என்று அறிய விரும்பும் கட்டணக் கருவி, படிவம் சமர்ப்பிக்கப்படும்போது அழைப்பைச் செய்யும் ஸ்கிரிப்ட். இதற்காகவே Call-இல் REST API-உம் வெளிச்செல்லும் webhooks-உம் உள்ளன. பகுதிகள் எப்படிப் பொருந்துகின்றன, குறியீடு எழுதும் முன் என்ன கேட்க வேண்டும், டெவலப்பருக்கு அடிக்கடி ஒரு மதியத்தை வீணாக்கும் தவறுகள் ஆகியவற்றை இந்த வழிகாட்டி விளக்குகிறது.

உங்கள் நோக்கம் தொடர்புகளை மொத்தமாக நகர்த்துவது மட்டும் என்றால், முதலில் தொலைபேசிக் குழு CRM-க்குத் தொடர்புகளை இறக்குமதி செய்தல் படியுங்கள்; பெரும்பாலும் ஒருங்கிணைப்பைவிட இறக்குமதி எளிது.
எங்கே தொடங்குவது: குறிப்பும் Developers பக்கமும்
தெரிந்துகொள்ள வேண்டிய இடங்கள் இரண்டு. API குறிப்பு Settings பகுதியிலும், முகப்புப் பக்கத்தின் Resources மெனுவிலும் உள்ளது. அதை உள்நுழையாமலே படிக்கலாம்; ஒரு வாடிக்கையாளருக்காக வேலையின் வரம்பை மதிப்பிடும்போது இது வசதியானது. Developers பக்கம், இதுவும் Settings-இன் கீழ், உங்கள் சொந்தப் பணியிடத்துக்கானது: அது உங்கள் நிறுவன மற்றும் முகவர் அடையாளங்காட்டிகள், உங்கள் webhook endpoints, உங்கள் கீகளின் படிக்க மட்டுமான பட்டியல் ஆகியவற்றைக் காட்டுகிறது.
ஒவ்வொரு இடமும் தருவது
- Start hereஅடிப்படை URL, மரபுகள், scopes அட்டவணையுடன் அங்கீகாரம், நிலைக் குறியீடுகளுடன் பிழைகள்.
- Endpointsஒவ்வொரு endpoint அட்டையும் அதன் scope, அளவுருக்கள், கோரிக்கை உடல், பதில், பிழைகளைப் பட்டியலிடுகிறது; curl, JavaScript, Python-இல் நகலெடுக்கத் தயாரான கோரிக்கைகளுடன்.
- தேடல்Search endpoints-க்குச் செல்ல / அழுத்தி, method, path, scope அல்லது சுருக்கம் வாரியாக வடிகட்டுங்கள்.
- OpenAPI JSONஉங்கள் சொந்தக் கருவிகளுக்காக முழு விவரக்குறிப்பையும் ஒரே கோப்பாகப் பதிவிறக்குகிறது.
- Agent ID / APIஉங்கள் நிறுவன ID-உம் slug-உம், API பயன்முறை (Sandbox அல்லது Live), நீங்கள் தேர்ந்தெடுக்கும் AI முகவரின் ID, ஒவ்வொன்றும் Copy பொத்தானுடன்.
- Webhooksஉங்கள் endpoints, ஒவ்வொன்றும் பெறும் நிகழ்வுகள், கடைசி HTTP நிலை, தோல்வியடைந்த டெலிவரிகள்.
Rate limits மற்றும் வெளிச்செல்லும் webhooks பற்றிய பகுதிகளை நேரலைக்குப் பிறகு அல்ல, முன்பே படியுங்கள். விரைவான சோதனையில் தவறவிடக்கூடிய நடத்தையை அவை விவரிக்கின்றன.
API கீகளும் scopes-உம்
ஒவ்வொரு கோரிக்கையும் Authorization header-இல் bearer token ஆக ஒரு கீயைக் கொண்டுசெல்கிறது. கீகள் செயலியில் உருவாக்கப்படுவதில்லை: உங்கள் பணியிடத்தின் ஆபரேட்டர் அவற்றை வழங்கி, அவற்றில் எந்த scopes உள்ளன என்று சொல்கிறார். முழுக் கீ வழங்கப்படும் தருணத்தில் ஒருமுறை மட்டுமே காட்டப்படும், பின்னர் அதன் முதல் எழுத்துகள் மட்டுமே தெரியும்; எனவே அதை உடனே உங்கள் சொந்த secret store-இல் சேமியுங்கள்.
| Scope | அது அனுமதிப்பது |
|---|---|
| read | தொடர்புகள், அழைப்புகள், வரிசைகள், குழு உறுப்பினர்கள், அறிக்கைகள், அழைக்கக்கூடாதோர் பட்டியல் ஆகியவற்றைப் படித்தல். |
| write | தொடர்புகளை உருவாக்குதல், புதுப்பித்தல், அழைப்பு முடிவுகளைப் பதிவுசெய்தல், அழைக்கக்கூடாதோர் பட்டியலில் எண்களைச் சேர்த்தல். |
| calls | அழைப்புகளைச் செய்தலும் முடித்தலும். |
| admin | Webhooks-ஐ நிர்வகித்தல்; மற்ற ஒவ்வொரு endpoint-ஐயும் அழைக்கலாம். |
வேலையைச் செய்யும் மிகச் சிறிய தொகுப்பைக் கேளுங்கள். அறிக்கை ஸ்கிரிப்டுக்கு read மட்டுமே தேவை; click-to-call பொத்தானுக்கு calls தேவை. ஒரு கோரிக்கை insufficient_scope குறியீட்டுடன் 403 தந்தால், அந்த endpoint அட்டையில் காட்டப்படும் scope கீயிடம் இல்லை.
Sandbox மற்றும் live
கீகள் sandbox-க்கு வழங்கப்படலாம், அது சிமுலேட்டரைப் பயன்படுத்தி உண்மையான அழைப்புகள் எதையும் செய்யாது; அல்லது live பயன்பாட்டுக்கு. கீயின் முன்னொட்டை ஒரு லேபிளாக மட்டுமே கருதுங்கள்: test எனக் குறிக்கப்பட்ட கீ live கீ போலவே அதே தரவிலும் அதே தொலைபேசி இணைப்பிலும் வேலை செய்கிறது; எனவே சோதனைகளை உண்மையான வாடிக்கையாளர்களிடமிருந்து விலக்கி வைக்க முன்னொட்டை நம்பாதீர்கள். நீங்கள் எங்கே இருக்கிறீர்கள் என்று அறிய Developers பக்கத்தில் காட்டப்படும் API பயன்முறையைப் பயன்படுத்துங்கள்.
API மூலம் அழைப்புகளைச் செய்தல்
பொது endpoints அடிப்படைகளை உள்ளடக்குகின்றன: health check, அழைப்புகளைப் பட்டியலிடுதல், ஒரு அழைப்பைப் படித்தல், அழைப்பைச் செய்தல், துண்டித்தல், webhooks-ஐ நிர்வகித்தல், AI முகவருடன் உரையாடுதல். API மூலம் செய்யப்படும் வெளிச்செல்லும் அழைப்பு மேசையிலிருந்து செய்யப்படும் அழைப்பைப் போலவே அதே இணக்கச் சரிபார்ப்பைக் கடக்கிறது; எனவே அழைக்கக்கூடாதோர் பட்டியலில் உள்ள அல்லது அனுமதிக்கப்பட்ட அழைப்பு நேரத்துக்கு வெளியே உள்ள எண் முகவருக்கு மறுக்கப்படுவது போலவே மறுக்கப்படும். அந்த மறுப்பைப் பிழையாக அல்லாமல் சாதாரண விளைவாகக் கையாளும்படி உங்கள் குறியீட்டை எழுதுங்கள்.
இது வடிவமைப்புக்கு முக்கியம். மறுக்கப்பட்ட அழைப்பு வெற்றிபெறும் வரை மீண்டும் முயலும் loop-ஐ எழுதாதீர்கள். காரணத்தைப் படித்து, பதிவுசெய்து, அடுத்ததுக்குச் செல்லுங்கள். அந்த மறுப்புகளின் பின்னால் உள்ள விதிகளுக்கு Call-இல் அழைப்பு நேரக் காவல் மற்றும் Call-இல் அழைக்கக்கூடாதோர் பட்டியல் பாருங்கள்.
Rate limits மற்றும் பிழைகள்
ஒவ்வொரு கீக்கும் நிமிடத்துக்கான கோரிக்கைகளின் தனி வரம்பு உண்டு, கீ வழங்கப்படும்போது அமைக்கப்படுகிறது; இயல்புநிலை 120. ஒரு கீ அந்த நிமிடத்தின் வரம்பைத் தீர்த்தால், API rate_limited குறியீட்டுடன் 429 பதிலளித்து, X-RateLimit-Reset header-இல் எவ்வளவு நேரம் காத்திருக்க வேண்டும் என்று சொல்கிறது. அவ்வளவு நேரம் காத்திருந்து தொடருங்கள். மரியாதையான client சுவரில் மோதும் முன்பே தன்னை மெதுவாக்கிக்கொள்கிறது.
- 429 rate_limited: reset header-இல் உள்ள காலத்துக்குப் பின்வாங்குங்கள்; மொத்த வேலையைக் காலப்போக்கில் பரப்புங்கள்.
- 403 insufficient_scope: அந்த endpoint அட்டையில் உள்ள scope கீயிடம் இல்லை; அதனுடன் கூடிய கீயைக் கோருங்கள்.
- மற்றப் பிழைகள்: செய்தியின் அடிப்படையில் அல்ல, பிழைக் குறியீட்டின் அடிப்படையில் செயல்படுங்கள். குறியீடுகள் மாறுவதில்லை; வாசகம் மாறலாம்.
தோல்வியடைந்த கோரிக்கையைக் கையாளுதல்
- நிலையைப் படித்தல்நீங்கள் சரிசெய்யக்கூடிய client பிழையா, அல்லது மீண்டும் முயலத் தகுந்த server பிழையா?
- குறியீட்டைப் படித்தல்செய்தி உரையின் அடிப்படையில் ஒருபோதும் அல்ல, குறியீட்டின் அடிப்படையில் கிளைபிரியுங்கள்.
- பின்வாங்குதல்429-க்கு reset header வரை காத்திருங்கள்; server பிழைகளுக்கு, அதிகரிக்கும் இடைவெளிகளுடன் சில முறை மீண்டும் முயலுங்கள்.
- விவரத்தைப் பதிவுசெய்தல்ஆதரவுக் குழு கண்டறிய endpoint, குறியீடு, நேரத்தை வைத்திருங்கள்.
- மறுப்புகளில் நிறுத்துதல்இணக்க மறுப்பு ஒரு முடிவு, கோளாறு அல்ல; அதில் loop செய்யாதீர்கள்.
Webhooks: நிகழ்வுகளைப் பெறுதல்
ஏதாவது நடந்ததா என்று API-இடம் மீண்டும் மீண்டும் கேட்பதற்குப் பதில், Call உங்களிடம் சொல்லட்டும். Developers பக்கத்தில் Add endpoint அழுத்தி, பொது https முகவரியை உள்ளிட்டு, விரும்பும் நிகழ்வுகளை டிக் செய்யுங்கள்; எதையும் டிக் செய்யாவிட்டால் அனைத்து நிகழ்வுகளும். Endpoint சேர்க்கப்படும்போது signing secret ஒருமுறை காட்டப்படும். அப்போதே நகலெடுங்கள். தொலைந்தால், endpoint-ஐ நீக்கி மீண்டும் சேர்த்துப் புதியதைப் பெறுங்கள்.
ஒவ்வொரு டெலிவரியும் கையொப்பமிடப்படுகிறது. கையொப்ப header, உங்கள் signing secret மூலம் கணக்கிடப்பட்ட, முற்றுப்புள்ளியால் இணைக்கப்பட்ட timestamp மற்றும் body-இன் HMAC-SHA256-ஐக் கொண்டுள்ளது; தனி header timestamp-ஐக் கொண்டுசெல்கிறது. Payload-ஐ நம்பும் முன் உங்கள் பக்கத்தில் அதை மீண்டும் கணக்கிட்டு ஒப்பிடுங்கள். API குறிப்பில் இதற்கான Node.js மற்றும் Python மாதிரிக் குறியீடு உள்ளது; பழைய timestamps-ஐ நிராகரிப்பது மீண்டும் அனுப்பப்படும் கோரிக்கைகளிலிருந்து உங்களைப் பாதுகாக்கிறது.
நல்ல மற்றும் மோசமான webhook receiver
| நல்லது | மோசமானது | |
|---|---|---|
| கையொப்பம் | ஒவ்வொரு கோரிக்கையிலும் சரிபார்க்கப்படுகிறது | சரிபார்க்காமலே நம்பப்படுகிறது |
| பதில் | சில வினாடிகளில் 2xx, வேலை பின்னர் செய்ய வரிசைப்படுத்தப்படுகிறது | பதிலளிக்கும் முன் மெதுவான செயலாக்கம் |
| நகல்கள் | ஒரே நிகழ்வை இருமுறை பெற்றாலும் பாதுகாப்பானது | இரண்டு பதிவுகளை உருவாக்குகிறது |
| தோல்விகள் | டெலிவரிகள் தோல்வியடையும்போது எச்சரிக்கிறது | யாராவது கவனிக்கும் வரை மௌனம் |
உங்கள் endpoint 10 வினாடிகளுக்குள் 2xx நிலையுடன் பதிலளிக்க வேண்டும். தோல்வியடைந்த டெலிவரி மீண்டும் முயலப்படும், மொத்தம் ஆறு முயற்சிகள் வரை; தொடர்ந்து 50 முறை தோல்வியடையும் endpoint முடக்கப்படும். Developers பக்கத்தில் ஒவ்வொரு வரிசையும் கடைசி HTTP நிலையையும் எத்தனை டெலிவரிகள் தோல்வியடைந்தன என்பதையும் காட்டுகிறது; Send test ஒரு கையொப்பமிட்ட சோதனை நிகழ்வை அனுப்புகிறது, உங்கள் சர்வர் என்ன பதிலளிக்கிறது என்று பார்க்கலாம்.
நேரலைக்கான சரிபார்ப்புப் பட்டியல்
ஒருங்கிணைப்பை இயக்கும் முன்
- கீயிடம் எந்த scopes உள்ளன என்று உங்களுக்குத் தெரியும், தேவைக்கு மேல் இல்லை
- கீ source code-இல் அல்லாமல் secret store-இல் சேமிக்கப்பட்டுள்ளது
- Webhook கையொப்பங்கள் சரிபார்க்கப்பட்டு, பழைய timestamps நிராகரிக்கப்படுகின்றன
- Receiver விரைவாகப் பதிலளித்து நகல் நிகழ்வுகளைக் கையாள்கிறது
- Rate-limit மற்றும் மறுப்புப் பதில்கள் இறுக்கமான retry loops இல்லாமல் கையாளப்படுகின்றன
- Sandbox பயன்முறையில் சோதித்து, endpoint-இல் Send test அழுத்தினீர்கள்
- டெலிவரிகள் தோல்வியடையத் தொடங்கினால் எச்சரிக்கை பெற ஒருவர் பெயரிடப்பட்டுள்ளார்
Call-இல் செய்தல்
Call-இல், endpoints-ஐ ஆய்வு செய்ய Settings, பிறகு API reference-ஐத் திறங்கள்; உங்கள் நிறுவன ID-ஐ நகலெடுக்க, கீகளைச் சரிபார்க்க, webhook சேர்க்க Settings, பிறகு Developers. உரிமையாளர்கள், நிர்வாகிகள், மேலாளர்கள் endpoints-ஐச் சேர்க்கலாம், சோதிக்கலாம், நீக்கலாம்; மற்ற அனைவரும் பட்டியலைப் பார்க்கிறார்கள். AI முகவர் அம்சங்களையும் பயன்படுத்தினால், அதே பக்கத்தில் உள்ள agent ID chat endpoint-க்குப் பயன்படும். தயாரிப்பின் குரல் பக்கத்துக்கு Call-இல் AI முகவரை அமைத்தல் பாருங்கள்.
அடிக்கடி கேட்கப்படும் கேள்விகள்
API கீயை எப்படிப் பெறுவது?
கீகள் உங்கள் பணியிடத்தின் ஆபரேட்டரால் வழங்கப்படுகின்றன; செயலியில் உருவாக்க முடியாது. ஒன்றைக் கேட்டு, அதற்கு எந்த scopes தேவை என்று சொல்லுங்கள். முழுக் கீ வழங்கப்படும்போது ஒருமுறை காட்டப்படும்.
429 பதில் என்றால் என்ன?
நடப்பு நிமிடத்துக்கான கோரிக்கைகளைக் கீ தீர்த்துவிட்டது. X-RateLimit-Reset header-இல் உள்ள வினாடிகள் காத்திருந்து மீண்டும் முயலுங்கள்; மொத்த வேலையை நீண்ட காலத்தில் பரப்புங்கள்.
Webhook உண்மையில் Call-இலிருந்து வந்தது என்று எப்படிச் சரிபார்ப்பது?
உங்கள் signing secret மூலம் timestamp மற்றும் body-இன் HMAC-SHA256-ஐக் கணக்கிட்டு, கையொப்ப header-உடன் ஒப்பிடுங்கள். API குறிப்பு Node.js மற்றும் Python-இல் உதாரணங்களைக் காட்டுகிறது.
உள்ளூர் மேம்பாட்டு சர்வருக்கு webhooks அனுப்பலாமா?
நேரடியாக முடியாது. Endpoints பொது https முகவரிகளாக இருக்க வேண்டும்; எனவே உங்கள் உள்ளூர் சர்வரை அப்படிப்பட்ட முகவரியில் வெளிப்படுத்தும் tunnelling கருவியைப் பயன்படுத்துங்கள்.
அழைப்பைச் செய்யும் என் API கோரிக்கை ஏன் மறுக்கப்பட்டது?
API மூலம் செய்யப்படும் அழைப்புகள் மேசையிலிருந்து செய்யப்படும் அழைப்புகளைப் போலவே அதே இணக்கச் சரிபார்ப்பைக் கடக்கின்றன. அழைக்கக்கூடாதோர் பட்டியலில் உள்ள அல்லது அழைப்பு நேரத்துக்கு வெளியே உள்ள எண் மறுக்கப்படும்.
Webhooks-ஐ யார் பார்க்கலாம், மாற்றலாம்?
அனைவரும் பட்டியலைப் படிக்கலாம்; ஆனால் உரிமையாளர்கள், நிர்வாகிகள், மேலாளர்கள் மட்டுமே endpoints-ஐச் சேர்க்க, சோதிக்க அல்லது நீக்க முடியும்.