Начало работы с API, Playground и вебхуками

Найдите ключ API, выполните безопасный первый запрос и подключите уведомления, не раскрывая учётные данные.

Используйте актуальный справочник API

Войдите в аккаунт и откройте документацию API. В ней указаны поддерживаемые методы, обязательные поля и примеры. Детали запросов берите из справочника; это руководство объясняет порядок работы, не повторяя спецификацию.

Подготовьте ключ

Пройдите проверку личности, чтобы увидеть или скопировать ключ. После проверки документация позволяет пять минут просматривать ключ и пользоваться Playground; создание или перевыпуск ключа требует новой проверки. Защищайте его как пароль: храните на сервере приложения, а не в публичных репозиториях, браузерном коде или снимках экрана.

Выполните безопасный первый запрос

Откройте Playground и выберите подходящий вашему аккаунту шаблон только для чтения, например список SIP-идентификаторов.
Проверьте метод, путь и параметры. Используйте идентификаторы, возвращённые для вашего аккаунта, а не значения из примеров.
Нажмите Run request и проверьте HTTP-статус и тело ответа.
Используйте документированный пример в приложении, обеспечив безопасное хранение ключа.

Playground работает с вашим аккаунтом. Отправка сообщений, звонки и заказ услуг могут выполнять реальные платные действия. Это не бесплатная песочница.

Добавьте уведомления вебхуков

В интеграциях аккаунта добавьте HTTPS-адрес и выберите нужные события. Секрет подписи вебхука отличается от ключа API. Проверяйте подписи, обрабатывайте каждое событие один раз и быстро подтверждайте приём. При диагностике смотрите журналы доставки. Перед повтором платной операции прочитайте правила повторных и дублирующих запросов; один тайм-аут не доказывает неудачу.

Связанные руководства

Выберите справочник нужного сервиса

В справочнике разделены Lookup, Pricing, SIP, SMS, Contacts, Speech API, Phone Numbers, Voice API и Calls & recordings. Точные требования, поля и стоимость смотрите у конкретного метода. Для браузерных звонков есть отдельное руководство Webphone SDK; это не то же самое, что серверное управление звонками Voice API.

Право агента читать документацию не даёт доступа к ключу владельца и выполнению запросов Playground с этим ключом. Попросите владельца управлять данными интеграции вместо передачи своего логина.

Используйте полученные ссылки и пагинацию

Считайте публичные ссылки на звонки непрозрачными значениями: копируйте полный идентификатор CALL- из своего ответа, не составляйте его вручную и не используйте внутренние телефонные идентификаторы. Исторические и активные звонки — разные списки. Управление также требует поддерживаемого состояния звонка; запись в истории не обязательно доступна для управления.

В истории следуйте pagination.next_cursor, пока pagination.has_more истинно. Сохраняйте исходные days, limit и фильтры SIP. Не декодируйте и не меняйте курсор. Если он истёк, начните новую выборку и сопоставьте результаты по публичным ссылкам. Время API, документированное как UTC, нужно явно преобразовать для отображения; оно не становится автоматически местным временем браузера.

Обрабатывайте ошибки без повторных платных действий

Читайте HTTP-статус вместе со структурированной ошибкой. Исправьте ошибки валидации или доступа до повтора. При ограничении частоты соблюдайте документированную задержку. После тайм-аута или временной ошибки платного действия проверьте его статус и правила дублей перед повторной отправкой: смена идентификаторов может создать новую операцию. Для поддержки сохраните публичную ссылку, время и ошибку без секретных данных, но никогда не ключ API.