API та вебхуки Call для розробників: ключі, scopes, події
Практичний огляд REST API Call: API-ключі та scopes, ліміти запитів, обробка помилок, підписані вебхуки й сторінка «Розробникам», де ви керуєте кінцевими точками.
Рано чи пізно телефонна система має взаємодіяти з чимось іншим: 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, скільки чекати. Зачекайте стільки, а потім продовжуйте. Ввічливий клієнт сповільнюється сам, ще не дійшовши до межі.
- 429 rate_limited: зачекайте період, указаний у заголовку скидання, і розподіляйте масові операції в часі.
- 403 insufficient_scope: ключу бракує scope, зазначеного на картці кінцевої точки; запросіть ключ із ним.
- Інші помилки: орієнтуйтеся на код помилки, а не на повідомлення. Коди не змінюються, а формулювання може.
Обробка невдалого запиту
- Прочитайте статусЦе помилка клієнта, яку можна виправити, чи помилка сервера, яку варто повторити?
- Прочитайте кодРозгалужуйте логіку за кодом, ніколи за текстом повідомлення.
- ЗачекайтеДля 429 дочекайтеся часу із заголовка скидання; для помилок сервера повторіть кілька разів зі зростаючими затримками.
- Зафіксуйте подробиціЗберігайте кінцеву точку, код і час, щоб підтримка могла все відстежити.
- Зупиняйтеся на відмовахВідмова з міркувань відповідності — це рішення, а не збій; не зациклюйтеся на ній.
Вебхуки: отримання подій
Замість того щоб знову й знову питати 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 проходять ту саму перевірку відповідності, що й дзвінки з робочого місця. Номер зі списку заборони дзвінків або дзвінок поза дозволеними годинами відхиляється.
Хто може бачити й змінювати вебхуки?
Список можуть читати всі, але додавати, тестувати чи видаляти кінцеві точки можуть лише власники, адміністратори та менеджери.