Call API at Webhook para sa Developer: Key, Scope at Event
Praktikal na tour ng Call REST API: API key at scope, rate limit, paghawak ng error, signed na webhook at ang Developers page kung saan pinamamahalaan ang endpoint.
Darating ang panahong kailangang makipag-usap ng phone system sa ibang bagay: CRM na dapat magpakita ng tawag pagkatapos nito, billing tool na gustong malaman kung sino ang tumawag, script na tumatawag kapag may na-submit na form. May REST API at outbound webhook ang Call para mismo rito. Ipinapaliwanag ng gabay na ito kung paano nagkakabit-kabit ang mga bahagi, ano ang hihingin bago magsulat ng code, at ang mga pagkakamaling kadalasang umuubos ng isang hapon ng developer.

Kung gusto lang ninyong maglipat ng maraming contact nang sabay-sabay, basahin muna ang Pag-import ng Contact sa CRM ng Phone Team; madalas mas madali ang import kaysa sa integration.
Saan magsisimula: ang reference at ang Developers page
Dalawang lugar ang dapat ninyong malaman. Nasa ilalim ng Settings ang API reference, at nasa Resources menu rin ng home page. Mababasa ito nang hindi nagsa-sign in, na kapaki-pakinabang kapag tinatantya ninyo ang trabaho para sa isang kliyente. Ang Developers page, nasa ilalim din ng Settings, ay para sa sarili ninyong workspace: ipinapakita nito ang identifier ng inyong organisasyon at agent, ang inyong mga webhook endpoint at read-only na listahan ng inyong mga key.
Ano ang ibinibigay ng bawat lugar
- Start hereBase URL at mga kumbensyon, authentication na may talahanayan ng scope, at mga error na may status code.
- EndpointsInililista ng bawat endpoint card ang scope, parameter, request body, response at error nito, may handang kopyahing request sa curl, JavaScript at Python.
- SearchPindutin ang / para tumalon sa Search endpoints at mag-filter ayon sa method, path, scope o buod.
- OpenAPI JSONDina-download ang buong specification bilang iisang file para sa sarili ninyong mga tool.
- Agent ID / APIAng inyong organization ID at slug, ang API mode (Sandbox o Live) at ang ID ng AI agent na pipiliin ninyo, bawat isa may Copy button.
- WebhooksAng inyong mga endpoint, ang mga event na natatanggap ng bawat isa, ang huling HTTP status at anumang bigong delivery.
Basahin ang mga seksyon tungkol sa rate limit at outbound webhook bago mag-live, hindi pagkatapos. Inilalarawan nila ang kilos na madaling makaligtaan sa mabilisang test.
API key at scope
May dalang key ang bawat request sa Authorization header bilang bearer token. Hindi ginagawa sa app ang mga key: inilalabas ito ng operator ng inyong workspace at sinasabi sa inyo kung aling scope ang dala nito. Isang beses lang ipinapakita ang buong key sa sandaling inilabas ito, at pagkatapos ay ang mga unang character na lang nito ang lumalabas, kaya itago agad ito sa sarili ninyong secret store.
| Scope | Ano ang pinapayagan nito |
|---|---|
| read | Pagbasa ng contact, tawag, queue, miyembro ng team, report at do-not-call list. |
| write | Paggawa at pag-update ng contact, pagtatala ng resulta ng tawag, pagdagdag ng numero sa do-not-call list. |
| calls | Pagtawag at pagtatapos ng tawag. |
| admin | Pamamahala ng webhook; maaari ring tumawag sa bawat iba pang endpoint. |
Hingin ang pinakamaliit na set na sapat sa trabaho. Read lang ang kailangan ng reporting script; calls ang kailangan ng click-to-call button. Kung nagbalik ang request ng 403 na may code na insufficient_scope, kulang sa key ang scope na nakasaad sa card ng endpoint na iyon.
Sandbox at live
Maaaring ilabas ang key para sa sandbox, na gumagamit ng simulator at hindi tumatawag nang totoo, o para sa live na paggamit. Ituring na label lang ang prefix ng key: gumagana ang key na may test label sa parehong datos at parehong phone connection gaya ng live, kaya huwag umasa sa prefix para mailayo ang mga eksperimento sa totoong customer. Gamitin ang API mode na ipinapakita sa Developers page para malaman kung nasaan kayo.
Pagtawag sa pamamagitan ng API
Saklaw ng mga public endpoint ang mga batayan: health check, paglista ng tawag, pagbasa ng isang tawag, pagtawag, pagbaba, pamamahala ng webhook at pakikipag-chat sa AI agent. Dumaraan sa parehong compliance check gaya ng tawag mula sa desk ang outbound na tawag sa pamamagitan ng API, kaya tinatanggihan ang numerong nasa do-not-call list o labas sa pinapayagang calling hours, gaya ng mangyayari sa isang agent. Buuin ang inyong code para hawakan ang pagtanggi na iyon bilang normal na resulta, hindi bug.
Mahalaga ito sa disenyo. Huwag sumulat ng loop na inuulit ang tinanggihang tawag hanggang gumana. Basahin ang dahilan, i-log ito, at magpatuloy. Para sa mga patakaran sa likod ng mga pagtanggi, tingnan ang Calling-Hours Guard sa Call at Ang Do-Not-Call List sa Call.
Rate limit at error
May sariling limit ng request kada minuto ang bawat key, na itinatakda kapag inilabas ang key; 120 ang default. Kapag naubos ng key ang minuto, sumasagot ang API ng 429 na may code na rate_limited at sinasabi kung gaano katagal maghihintay sa X-RateLimit-Reset header. Maghintay nang ganoon katagal, saka magpatuloy. Binabagalan ng magalang na client ang sarili bago pa tumama sa pader.
- 429 rate_limited: umatras para sa panahong nasa reset header, at ikalat ang bulk na trabaho sa paglipas ng oras.
- 403 insufficient_scope: kulang sa key ang scope sa card ng endpoint na iyon; humingi ng key na mayroon nito.
- Iba pang error: kumilos ayon sa error code, hindi sa mensahe. Hindi nagbabago ang mga code; maaaring magbago ang pananalita.
Paghawak ng bigong request
- Basahin ang statusClient error ba ito na maaayos ninyo, o server error na sulit subukan ulit?
- Basahin ang codeMag-branch ayon sa code, hindi kailanman ayon sa teksto ng mensahe.
- UmatrasPara sa 429, hintayin ang reset header; para sa server error, subukan ulit nang ilang beses na palaki nang palaki ang pagitan.
- I-log ang detalyeItago ang endpoint, code at oras para matunton ito ng support.
- Huminto sa mga pagtanggiDesisyon ang compliance refusal, hindi aberya; huwag itong i-loop.
Webhook: pagtanggap ng mga event
Sa halip na paulit-ulit na tanungin ang API kung may nangyari, hayaang ang Call ang magsabi sa inyo. Sa Developers page, pindutin ang Add endpoint, ilagay ang public https address, at lagyan ng tsek ang mga event na gusto ninyo; kapag walang tsek, lahat ng event. Isang beses lang ipinapakita ang signing secret, kapag idinagdag ang endpoint. Kopyahin ito noon. Kung nawala ito, burahin ang endpoint at idagdag ulit para makakuha ng bago.
Signed ang bawat delivery. Hawak ng signature header ang HMAC-SHA256 ng timestamp at body na pinagdugtong ng tuldok, kinalkula gamit ang inyong signing secret, at may hiwalay na header para sa timestamp. Kalkulahin ulit ito sa inyong panig at paghambingin bago pagkatiwalaan ang payload. May sample code para dito sa Node.js at Python ang API reference, at pinoprotektahan kayo laban sa replayed request ng pagtanggi sa mga lumang timestamp.
Mahusay at mahinang webhook receiver
| Mahusay | Mahina | |
|---|---|---|
| Signature | Bine-verify sa bawat request | Pinagkakatiwalaan nang hindi sinusuri |
| Sagot | 2xx sa loob ng ilang segundo, naka-queue ang trabaho para mamaya | Mabagal na pagproseso bago sumagot |
| Duplicate | Ligtas tanggapin nang dalawang beses ang parehong event | Gumagawa ng dalawang record |
| Pagkabigo | Nag-a-alert kapag bumibigo ang delivery | Tahimik hanggang may makapansin |
Dapat sumagot ang inyong endpoint ng 2xx status sa loob ng 10 segundo. Sinusubukan ulit ang bigong delivery, hanggang anim na pagtatangka sa kabuuan, at ino-off ang endpoint na bumigo nang 50 beses nang sunod-sunod. Ipinapakita ng bawat row sa Developers page ang huling HTTP status at ilang delivery ang bumigo, at nagpapadala ang Send test ng isang signed na test event para makita ninyo ang isinasagot ng inyong server.
Checklist bago mag-live
Bago i-on ang isang integration
- Alam ninyo kung aling scope ang nasa key, at walang higit sa kailangan
- Nakatago ang key sa secret store, hindi sa source code
- Bine-verify ang webhook signature at tinatanggihan ang lumang timestamp
- Mabilis sumagot ang receiver at hinahawakan ang duplicate na event
- Hinahawakan ang rate-limit at refusal response nang walang masikip na retry loop
- Nag-test kayo sa sandbox mode at pinindot ang Send test sa endpoint
- May itinalagang tao na makatatanggap ng alert kung magsimulang bumigo ang delivery
Paggawa nito sa Call
Sa Call, buksan ang Settings, saka ang API reference para pag-aralan ang mga endpoint, at Settings, saka ang Developers para kopyahin ang inyong organization ID, suriin ang mga key at magdagdag ng webhook. Makapagdaragdag, makapagte-test at makapagbubura ng endpoint ang mga owner, admin at manager; nakikita ng iba ang listahan. Kung gumagamit din kayo ng mga AI agent feature, ginagamit ng chat endpoint ang agent ID sa parehong page. Para sa voice na bahagi ng produkto, tingnan ang Pag-set Up ng AI Agent sa Call.
Mga madalas itanong
Paano ako makakukuha ng API key?
Inilalabas ng operator ng inyong workspace ang mga key; hindi ito magagawa sa app. Humingi ng isa at sabihin kung aling scope ang kailangan. Isang beses lang ipinapakita ang buong key kapag inilabas ito.
Ano ang ibig sabihin ng 429 na response?
Naubos na ng key ang mga request nito para sa kasalukuyang minuto. Maghintay ng bilang ng segundong nasa X-RateLimit-Reset header, saka subukan ulit, at ikalat ang bulk na trabaho sa mas mahabang panahon.
Paano ko masusuri na talagang galing sa Call ang isang webhook?
Kalkulahin ang HMAC-SHA256 ng timestamp at body gamit ang inyong signing secret at ihambing ito sa signature header. Nagpapakita ng halimbawa sa Node.js at Python ang API reference.
Puwede ba akong magpadala ng webhook sa local development server?
Hindi nang direkta. Dapat public https address ang mga endpoint, kaya gumamit ng tunnelling tool na naglalantad ng inyong local server sa ganoong address.
Bakit tinanggihan ang API call ko para tumawag?
Dumaraan sa parehong compliance check gaya ng tawag mula sa desk ang mga tawag sa pamamagitan ng API. Tinatanggihan ang numerong nasa do-not-call list o labas sa calling hours.
Sino ang makakakita at makapagbabago ng mga webhook?
Mababasa ng lahat ang listahan, pero mga owner, admin at manager lang ang makapagdaragdag, makapagte-test o makapagbubura ng endpoint.