Работа с Call

API и webhooks на Call за разработчици: ключове, обхвати, събития

Практичен преглед на REST API на Call: API ключове и обхвати, ограничения на заявките, обработка на грешки, подписани webhooks и страницата Developers.

Редакционен екип на Call · Публикувано · 6 мин четене

Рано или късно телефонната система трябва да комуникира с нещо друго: CRM, който да показва обаждането веднага щом приключи, инструмент за фактуриране, който иска да знае кой се е обадил, скрипт, който прави обаждане при изпращане на формуляр. Call има REST API и изходящи webhooks точно за това. Това ръководство обяснява как се свързват частите, какво да поискате, преди да пишете код, и грешките, които най-често струват на разработчика един следобед.

Разработчик преглежда интеграция на лаптоп до настолен телефон
Илюстративно изображение

Ако целта ви е просто да прехвърлите контакти на едро, първо прочетете Импортиране на контакти в CRM на телефонен екип; импортът често е по-лесен от интеграцията.

Откъде да започнете: справочникът и страницата Developers

Има две места, които трябва да познавате. API reference се намира в Settings, както и в менюто Resources на началната страница. Може да се чете без вписване, което е удобно, когато оценявате работа за клиент. Страницата Developers, също в Settings, е за вашето собствено работно пространство: тя показва идентификаторите на организацията и агентите ви, адресите ви за webhooks и списък на ключовете ви само за четене.

Какво ви дава всяко място

  • Start hereБазов URL и конвенции, удостоверяване с таблица на обхватите и грешки със статус кодове.
  • EndpointsВсяка карта на крайна точка изброява обхвата, параметрите, тялото на заявката, отговора и грешките, с готови за копиране заявки на curl, JavaScript и Python.
  • ТърсенеНатиснете /, за да отидете в Search endpoints и да филтрирате по метод, път, обхват или описание.
  • OpenAPI JSONИзтегля цялата спецификация като един файл за вашите собствени инструменти.
  • Agent ID / APIID и slug на организацията ви, режимът на API (Sandbox или Live) и ID на избрания AI агент, всеки с бутон Copy.
  • WebhooksВашите адреси, събитията, които получава всеки от тях, последният HTTP статус и неуспешните доставки.

Прочетете разделите за ограниченията на заявките и изходящите webhooks, преди да пуснете интеграцията, а не след това. Те описват поведение, което лесно се пропуска при бърз тест.

API ключове и обхвати

Всяка заявка носи ключ в заглавката Authorization като bearer токен. Ключовете не се създават в приложението: операторът на работното ви пространство ги издава и ви казва какви обхвати носят. Пълният ключ се показва веднъж, в момента на издаването му, а след това се виждат само първите му символи, затова го запазете веднага в собственото си хранилище за тайни.

ОбхватКакво позволява
readЧетене на контакти, обаждания, опашки, членове на екипа, отчети и списъка „не звънете“.
writeСъздаване и обновяване на контакти, записване на резултати от обаждания, добавяне на номера в списъка „не звънете“.
callsЗапочване и прекратяване на обаждания.
adminУправление на webhooks; може да извиква и всички други крайни точки.

Искайте най-малкия набор, който върши работа. Скрипт за отчети има нужда само от read; бутон за обаждане с едно щракване има нужда от calls. Ако заявка върне 403 с код insufficient_scope, на ключа липсва обхватът, посочен в картата на съответната крайна точка.

Sandbox и live

Ключовете могат да се издават за sandbox, който използва симулатор и не прави истински обаждания, или за реална употреба. Приемайте префикса на ключа само като етикет: ключ с етикет „test“ работи със същите данни и същата телефонна връзка като реалния, така че не разчитайте на префикса, за да държите експериментите далеч от истинските клиенти. Използвайте режима на API, показан на страницата Developers, за да знаете къде се намирате.

Обаждания чрез API

Публичните крайни точки покриват основното: проверка на състоянието, списък с обаждания, четене на едно обаждане, започване на обаждане, затваряне, управление на webhooks и чат с AI агент. Изходящо обаждане, направено чрез API, минава през същата проверка за съответствие като обаждане от работното място, така че номер в списъка „не звънете“ или извън разрешените часове за обаждания се отказва точно както би се отказал за служител. Изградете кода си така, че да обработва този отказ като нормален резултат, а не като грешка.

Това е важно за дизайна. Не пишете цикъл, който опитва отново отказано обаждане, докато успее. Прочетете причината, запишете я и продължете. За правилата зад тези откази вижте Защита на часовете за обаждания в Call и Списъкът „не звънете“ в Call.

Ограничения на заявките и грешки

Всеки ключ има собствен лимит на заявките в минута, зададен при издаването му; по подразбиране той е 120. Когато ключът изчерпа минутата, API отговаря с 429 и код rate_limited и ви казва колко да изчакате в заглавката X-RateLimit-Reset. Изчакайте толкова и продължете. Добрият клиент сам забавя темпото, преди да удари стената.

Обработка на неуспешна заявка

  1. Прочетете статусаКлиентска грешка ли е, която можете да поправите, или сървърна грешка, която си струва да опитате отново?
  2. Прочетете кодаРазклонявайте логиката по кода, никога по текста на съобщението.
  3. ИзчакайтеПри 429 изчакайте заглавката за нулиране; при сървърни грешки опитайте отново няколко пъти с нарастващи интервали.
  4. Запишете подробноститеПазете крайната точка, кода и времето, за да може поддръжката да проследи случая.
  5. Спирайте при отказиОтказът поради съответствие е решение, а не повреда; не го повтаряйте в цикъл.

Webhooks: получаване на събития

Вместо да питате API отново и отново дали нещо се е случило, оставете Call да ви каже. На страницата Developers натиснете Add endpoint, въведете публичен https адрес и отметнете събитията, които искате; ако не отметнете нищо, получавате всички събития. Тайният ключ за подписване се показва веднъж, когато адресът бъде добавен. Копирайте го тогава. Ако бъде загубен, изтрийте адреса и го добавете отново, за да получите нов.

Всяка доставка е подписана. Заглавката с подписа съдържа HMAC-SHA256 на времевия печат и тялото, свързани с точка, изчислен с вашия таен ключ за подписване, а отделна заглавка носи времевия печат. Изчислете го отново от своя страна и сравнете, преди да се доверите на съдържанието. Справочникът за API съдържа примерен код за това на Node.js и Python, а отхвърлянето на стари времеви печати ви защитава от повторно изпратени заявки.

Добър и лош получател на webhooks

ДобърЛош
ПодписПроверява се при всяка заявкаПриема се без проверка
Отговор2xx до няколко секунди, работата се поставя в опашка за по-късноБавна обработка преди отговора
ДубликатиБезопасно е едно и също събитие да се получи два пътиСъздава два записа
НеуспехиСигнализира, когато доставките се провалятМълчи, докато някой не забележи

Вашият адрес трябва да отговори със статус 2xx в рамките на 10 секунди. Неуспешна доставка се опитва отново, до общо шест опита, а адрес, който се провали 50 пъти подред, се изключва. Всеки ред на страницата Developers показва последния HTTP статус и колко доставки са се провалили, а Send test изпраща едно подписано тестово събитие, за да видите какво отговаря сървърът ви.

Контролен списък преди пускане

Преди да включите интеграция

  • Знаете какви обхвати има ключът и той няма повече от необходимото
  • Ключът се пази в хранилище за тайни, а не в изходния код
  • Подписите на webhooks се проверяват, а старите времеви печати се отхвърлят
  • Получателят отговаря бързо и обработва дублирани събития
  • Отговорите за лимит и откази се обработват без плътни цикли на повторни опити
  • Тествали сте в режим sandbox и сте натиснали Send test за адреса
  • Посочен е човек, който получава сигнал, ако доставките започнат да се провалят

Как да го направите в Call

В Call отворете Settings, след това API reference, за да проучите крайните точки, и Settings, след това Developers, за да копирате ID на организацията си, да проверите ключовете си и да добавите webhook. Собствениците, администраторите и мениджърите могат да добавят, тестват и изтриват адреси; всички останали виждат списъка. Ако използвате и функциите за AI агенти, ID на агента на същата страница се използва от крайната точка за чат. За гласовата страна на продукта вижте Настройка на AI агент в Call.

Често задавани въпроси

Как да получа API ключ?

Ключовете се издават от оператора на работното ви пространство; не могат да се създават в приложението. Поискайте ключ и посочете какви обхвати са му нужни. Пълният ключ се показва веднъж, при издаването.

Какво означава отговор 429?

Ключът е изчерпал заявките си за текущата минута. Изчакайте броя секунди от заглавката X-RateLimit-Reset, след това опитайте отново и разпределете масовата работа в по-дълъг период.

Как да проверя, че webhook наистина идва от Call?

Изчислете HMAC-SHA256 на времевия печат и тялото с вашия таен ключ за подписване и го сравнете със заглавката с подписа. Справочникът за API показва примери на Node.js и Python.

Мога ли да изпращам webhooks към локален сървър за разработка?

Не директно. Адресите трябва да са публични https адреси, затова използвайте инструмент за тунелиране, който излага локалния ви сървър на такъв адрес.

Защо заявката ми през API за обаждане беше отказана?

Обажданията през API минават през същата проверка за съответствие като обажданията от работното място. Номер в списъка „не звънете“ или извън часовете за обаждания се отказва.

Кой може да вижда и променя webhooks?

Всеки може да чете списъка, но само собствениците, администраторите и мениджърите могат да добавят, тестват или изтриват адреси.

Отворете справочника за API на Call и добавете webhook адрес

В демо конзолата можете да изпробвате входящи обаждания в симулация.

Свързани ръководства

Работа с Call

Статус на служителя в Call: свободен, почивка и не безпокойте

Какво означава всеки статус на служителя в Call, как хората и супервайзорите го променят, как работи автоматичната почивка и навици за честни опашки и почивки.

Редакционен екип на Call ·
Работа с Call

Предаване на разговор от AI агента към човек: ръководство

Как да осигурите гладко предаване от AI телефонен агент към екипа ви: кога да се предава, кой да звъни, топло или студено прехвърляне и резервни варианти.

Редакционен екип на Call ·
Работа с Call

Избор и тестване на AI глас за вашата телефонна линия

Как да изберете AI глас, подходящ за обаждащите се, да сравните мостри, да настроите скорост и произношение, да дадете на линия собствен глас и да го тествате.

Редакционен екип на Call ·
Работа с Call

Екраните за анализи в Call: отчети, табло на стената, глас

Обиколка на анализите в Call: плочките в Home, разделите в Reports, таблото на стената, административните и гласовите анализи и на какво отговаря всеки екран.

Редакционен екип на Call ·