Работа с Call

API и вебхуки Call для разработчиков: ключи, области, события

Практический обзор REST API Call: API-ключи и области доступа, лимиты запросов, обработка ошибок, подписанные вебхуки и страница для управления эндпоинтами.

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

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

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

Если вам нужно просто массово перенести контакты, сначала прочитайте материал «Импорт контактов в CRM телефонной команды»: импорт часто проще интеграции.

С чего начать: справочник и страница «Для разработчиков»

Нужно знать два места. Первое — справочник по API, который находится в разделе «Настройки», а также в меню «Ресурсы» на главной странице. Его можно читать без входа в систему, что удобно, когда вы оцениваете объём работ для клиента. Второе — страница «Для разработчиков», тоже в разделе «Настройки», которая относится к вашему рабочему пространству: на ней показаны идентификаторы вашей организации и агента, эндпоинты вебхуков и список ваших ключей только для чтения.

Что даёт каждое место

  • Начните здесьБазовый URL и соглашения, аутентификация с таблицей областей доступа и ошибки с кодами статусов.
  • ЭндпоинтыВ карточке каждого эндпоинта указаны область доступа, параметры, тело запроса, ответ и ошибки, а также готовые к копированию запросы на curl, JavaScript и Python.
  • ПоискНажмите /, чтобы перейти к поиску эндпоинтов и отфильтровать их по методу, пути, области доступа или описанию.
  • OpenAPI JSONСкачивает всю спецификацию одним файлом для ваших собственных инструментов.
  • ID агента / APIID и короткое имя (slug) вашей организации, режим API (Sandbox или Live) и ID выбранного ИИ-агента — у каждого есть кнопка «Копировать».
  • ВебхукиВаши эндпоинты, события, которые получает каждый из них, последний HTTP-статус и неудачные доставки.

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

API-ключи и области доступа

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

Область доступаЧто разрешает
readЧтение контактов, звонков, очередей, сотрудников, отчётов и списка запрета звонков.
writeСоздание и обновление контактов, запись результатов звонков, добавление номеров в список запрета звонков.
callsСовершение и завершение звонков.
adminУправление вебхуками; также даёт доступ ко всем остальным эндпоинтам.

Запрашивайте минимальный набор, достаточный для задачи. Скрипту отчётности нужна только область read, кнопке звонка по щелчку — calls. Если запрос возвращает 403 с кодом insufficient_scope, у ключа нет области доступа, указанной в карточке этого эндпоинта.

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

Ключи могут выдаваться для песочницы, которая использует симулятор и не совершает реальных звонков, или для боевого использования. Считайте префикс ключа всего лишь меткой: ключ с пометкой «test» работает с теми же данными и тем же телефонным подключением, что и боевой, поэтому не полагайтесь на префикс, чтобы оградить эксперименты от реальных клиентов. Чтобы понимать, в каком режиме вы работаете, смотрите на режим 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-статус и число неудачных доставок, а кнопка «Отправить тест» отправляет одно подписанное тестовое событие, чтобы вы увидели, что отвечает ваш сервер.

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

Прежде чем включить интеграцию

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

Как это сделать в Call

В Call откройте «Настройки» → «Справочник по API», чтобы изучить эндпоинты, и «Настройки» → «Для разработчиков», чтобы скопировать ID организации, проверить ключи и добавить вебхук. Добавлять, тестировать и удалять эндпоинты могут владельцы, администраторы и менеджеры; остальные видят список. Если вы используете и функции ИИ-агента, ID агента на той же странице используется в эндпоинте чата. О голосовой части продукта читайте в материале «Настройка ИИ-агента в Call».

Частые вопросы

Как получить API-ключ?

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

Что означает ответ 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 ·