Робота з Call

API та вебхуки Call для розробників: ключі, scopes, події

Практичний огляд REST API Call: API-ключі та scopes, ліміти запитів, обробка помилок, підписані вебхуки й сторінка «Розробникам», де ви керуєте кінцевими точками.

Редакція Call · Опубліковано · Читати 5 хв

Рано чи пізно телефонна система має взаємодіяти з чимось іншим: CRM, яка має показувати дзвінок одразу після його завершення, білінговий інструмент, якому треба знати, хто телефонував, скрипт, що здійснює дзвінок після надсилання форми. Саме для цього Call має REST API та вихідні вебхуки. У цьому посібнику пояснено, як поєднуються ці частини, що запросити, перш ніж писати код, і які помилки найчастіше коштують розробнику пів дня.

Розробник переглядає інтеграцію на ноутбуці поруч зі стаціонарним телефоном
Ілюстрація

Якщо ваша мета — просто масово перенести контакти, спершу прочитайте матеріал «Імпорт контактів у CRM телефонної команди»: імпорт часто простіший за інтеграцію.

З чого почати: довідник і сторінка «Розробникам»

Варто знати два місця. Довідник API розміщено в розділі «Налаштування», а також у меню «Ресурси» на головній сторінці. Його можна читати без входу, що зручно, коли ви оцінюєте обсяг робіт для клієнта. Сторінка Розробникам, також у розділі «Налаштування», призначена для вашого робочого простору: вона показує ідентифікатори вашої організації та агентів, кінцеві точки вебхуків і список ваших ключів лише для читання.

Що дає кожне місце

  • З чого початиБазова URL-адреса й угоди, автентифікація з таблицею scopes, помилки з кодами статусу.
  • Кінцеві точкиКартка кожної кінцевої точки містить її scope, параметри, тіло запиту, відповідь і помилки, а також готові до копіювання запити на curl, JavaScript і Python.
  • ПошукНатисніть /, щоб перейти до пошуку кінцевих точок і фільтрувати за методом, шляхом, scope чи описом.
  • OpenAPI JSONЗавантажує всю специфікацію одним файлом для ваших власних інструментів.
  • ID агента / APIID і slug вашої організації, режим API («Пісочниця» або «Бойовий») та ID обраного ШІ-агента, кожен із кнопкою «Копіювати».
  • Webhook'иВаші кінцеві точки, події, які отримує кожна з них, останній HTTP-статус і невдалі доставки.

Прочитайте розділи про ліміти запитів і вихідні вебхуки до запуску, а не після. Вони описують поведінку, яку легко не помітити під час швидкого тесту.

API-ключі та scopes

Кожен запит передає ключ у заголовку Authorization як bearer-токен. Ключі не створюються в застосунку: їх видає оператор вашого робочого простору й повідомляє, які scopes вони мають. Повний ключ показується один раз у момент видачі, а згодом видно лише його перші символи, тож одразу збережіть його у своєму сховищі секретів.

ScopeЩо дозволяє
readЧитати контакти, дзвінки, черги, членів команди, звіти та список заборони дзвінків.
writeСтворювати й оновлювати контакти, фіксувати результати дзвінків, додавати номери до списку заборони дзвінків.
callsЗдійснювати й завершувати дзвінки.
adminКерувати вебхуками; також може звертатися до всіх інших кінцевих точок.

Просіть найменший набір, достатній для завдання. Скрипту для звітів потрібен read і нічого більше; кнопці «натисни, щоб зателефонувати» потрібен calls. Якщо запит повертає 403 із кодом insufficient_scope, ключу бракує scope, зазначеного на картці цієї кінцевої точки.

Пісочниця й бойовий режим

Ключі можна видати для пісочниці, яка використовує симулятор і не здійснює реальних дзвінків, або для бойового використання. Сприймайте префікс ключа лише як мітку: ключ із позначкою тестового працює з тими самими даними й тим самим телефонним підключенням, що й бойовий, тож не покладайтеся на префікс, щоб відгородити експерименти від реальних клієнтів. Де ви перебуваєте, показує режим API на сторінці «Розробникам».

Здійснення дзвінків через API

Публічні кінцеві точки охоплюють основне: перевірку стану, список дзвінків, читання одного дзвінка, здійснення дзвінка, завершення дзвінка, керування вебхуками та чат із ШІ-агентом. Вихідний дзвінок, здійснений через API, проходить ту саму перевірку відповідності вимогам, що й дзвінок із робочого місця, тож номер зі списку заборони дзвінків або поза дозволеними годинами буде відхилено — так само, як для оператора. Пишіть код так, щоб обробляти таку відмову як звичайний результат, а не як помилку.

Це важливо для архітектури. Не пишіть цикл, який повторює відхилений дзвінок, доки той не пройде. Прочитайте причину, зафіксуйте її в журналі й рухайтеся далі. Правила, що стоять за цими відмовами, описано в матеріалах «Контроль годин дзвінків у Call» і «Список заборони дзвінків у Call».

Ліміти запитів і помилки

Кожен ключ має власний ліміт запитів на хвилину, який задається під час видачі ключа; за замовчуванням — 120. Коли ключ вичерпує ліміт на поточну хвилину, API відповідає 429 із кодом rate_limited і повідомляє в заголовку X-RateLimit-Reset, скільки чекати. Зачекайте стільки, а потім продовжуйте. Ввічливий клієнт сповільнюється сам, ще не дійшовши до межі.

Обробка невдалого запиту

  1. Прочитайте статусЦе помилка клієнта, яку можна виправити, чи помилка сервера, яку варто повторити?
  2. Прочитайте кодРозгалужуйте логіку за кодом, ніколи за текстом повідомлення.
  3. ЗачекайтеДля 429 дочекайтеся часу із заголовка скидання; для помилок сервера повторіть кілька разів зі зростаючими затримками.
  4. Зафіксуйте подробиціЗберігайте кінцеву точку, код і час, щоб підтримка могла все відстежити.
  5. Зупиняйтеся на відмовахВідмова з міркувань відповідності — це рішення, а не збій; не зациклюйтеся на ній.

Вебхуки: отримання подій

Замість того щоб знову й знову питати API, чи щось сталося, дозвольте Call повідомляти вас. На сторінці «Розробникам» натисніть «Додати кінцеву точку», введіть публічну https-адресу й позначте потрібні події; якщо не позначити жодної, надходитимуть усі події. Секрет підпису показується один раз, коли кінцеву точку додано. Скопіюйте його одразу. Якщо його втрачено, видаліть кінцеву точку й додайте її знову, щоб отримати новий.

Кожна доставка підписується. Заголовок підпису містить HMAC-SHA256 від часової мітки й тіла, з'єднаних крапкою, обчислений за допомогою вашого секрету підпису, а окремий заголовок передає часову мітку. Обчисліть його у себе й порівняйте, перш ніж довіряти вмісту. Довідник API містить приклади коду для цього на Node.js і Python, а відхилення застарілих часових міток захищає від повторно відтворених запитів.

Вдалий і невдалий приймач вебхуків

ВдалийНевдалий
ПідписПеревіряється в кожному запитіПриймається на віру
Відповідь2xx за кілька секунд, робота ставиться в чергуТривала обробка перед відповіддю
ДублікатиБезпечно отримати ту саму подію двічіСтворює два записи
ЗбоїСповіщає, коли доставки не вдаютьсяМовчить, доки хтось не помітить

Ваша кінцева точка має відповісти статусом 2xx протягом 10 секунд. Невдала доставка повторюється — загалом до шести спроб, а кінцева точка, яка не відповіла 50 разів поспіль, вимикається. Кожен рядок на сторінці «Розробникам» показує останній HTTP-статус і кількість невдалих доставок, а «Надіслати тест» надсилає одну підписану тестову подію, щоб ви побачили, що відповідає ваш сервер.

Чек-лист перед запуском

Перш ніж увімкнути інтеграцію

  • Ви знаєте, які scopes має ключ, і їх не більше, ніж потрібно
  • Ключ зберігається у сховищі секретів, а не у вихідному коді
  • Підписи вебхуків перевіряються, а застарілі часові мітки відхиляються
  • Приймач відповідає швидко й обробляє дублікати подій
  • Відповіді про перевищення ліміту й відмови обробляються без щільних циклів повторів
  • Ви протестували інтеграцію в режимі пісочниці й натиснули «Надіслати тест» для кінцевої точки
  • Призначено людину, яка отримає сповіщення, якщо доставки почнуть зриватися

Як це зробити в Call

У Call відкрийте «Налаштування» → «Довідник API», щоб вивчити кінцеві точки, і «Налаштування» → «Розробникам», щоб скопіювати ID організації, перевірити ключі й додати вебхук. Додавати, тестувати й видаляти кінцеві точки можуть власники, адміністратори та менеджери; усі інші бачать список. Якщо ви також користуєтеся функціями ШІ-агента, ID агента на тій самій сторінці використовується для кінцевої точки чату. Про голосову частину продукту див. матеріал «Налаштування ШІ-агента в Call».

Часті запитання

Як отримати API-ключ?

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

Що означає відповідь 429?

Ключ вичерпав ліміт запитів на поточну хвилину. Зачекайте кількість секунд, указану в заголовку X-RateLimit-Reset, спробуйте знову й розподіліть масові операції на довший період.

Як перевірити, що вебхук справді надійшов від Call?

Обчисліть HMAC-SHA256 від часової мітки й тіла за допомогою секрету підпису й порівняйте результат із заголовком підпису. Довідник API містить приклади на Node.js і Python.

Чи можна надсилати вебхуки на локальний сервер розробки?

Не напряму. Кінцеві точки мають бути публічними https-адресами, тож скористайтеся тунелюванням, яке відкриває ваш локальний сервер за такою адресою.

Чому мій запит API на здійснення дзвінка відхилено?

Дзвінки через API проходять ту саму перевірку відповідності, що й дзвінки з робочого місця. Номер зі списку заборони дзвінків або дзвінок поза дозволеними годинами відхиляється.

Хто може бачити й змінювати вебхуки?

Список можуть читати всі, але додавати, тестувати чи видаляти кінцеві точки можуть лише власники, адміністратори та менеджери.

Відкрийте довідник API Call і додайте кінцеву точку вебхука

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

Схожі посібники

Робота з Call

Статуси операторів у Call: «Вільний», «На перерві», «Не турбувати»

Що означає кожен статус оператора в Call, як його змінюють люди й супервайзери, як працює автоматична перерва і які звички роблять черги й перерви справедливими.

Редакція Call ·
Робота з Call

Передача дзвінка від ШІ-агента людині: посібник

Як побудувати плавну передачу дзвінка від ШІ-агента команді: коли передавати, кому дзвонить телефон, тепле чи холодне переведення, резервний план і подальші дії.

Редакція Call ·
Робота з Call

Як обрати й перевірити голос ШІ для телефонної лінії

Як обрати голос ШІ, що підходить абонентам, порівняти зразки, налаштувати швидкість і вимову, призначити лінії власний голос і перевірити його до дзвінків клієнтів.

Редакція Call ·
Робота з Call

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

Огляд аналітики в Call: плитки «Головної», вкладки «Звітів», табло, аналітика адміністратора та голосу — і на яке запитання відповідає кожен екран.

Редакція Call ·