Call Trace
Документация для разработчиков
API-ключи

Документация

Быстрый стартСоздать API-ключАутентификацияОбласти доступаСрок действия токенаСоздать анализПроверить статусСписок анализовPayloadПовторыСекрет webhookПримеры на языкахОшибки
Публичный API

Документация Call Trace API

Отправляйте записи звонков из своей системы, получайте немедленный ответ 202 и финальную транскрипцию и оценку через webhooks.

Создайте API-ключ

Откройте Админ > Интеграции и создайте ключ с областью analysis:write.

Отправьте URL файла

Передайте HTTPS fileUrl в POST /api/v1/analyses. API ответит 202 Accepted.

Получите результат

Подпишитесь на analysis.completed и analysis.failed, чтобы получить финальную оценку.

Проверьте secret

Сравните X-CallTrace-Secret с webhook secret, который вы сохранили при создании endpoint.

API-ключи

Создайте токен в панели администратора

Только администраторы могут создавать API-ключи интеграций. Ключи имеют ограниченные права, могут истекать, отзываться и не связаны с сессиями сотрудников.

  1. 01

    Откройте Интеграции

    Войдите как администратор и откройте Админ > Интеграции > API Keys.

  2. 02

    Назовите ключ

    Используйте имя, которое идентифицирует внешнюю систему, окружение и владельца.

  3. 03

    Выберите области доступа

    Выбирайте только те права, которые нужны системе. Большинству интеграций загрузки достаточно analysis:write и analysis:read.

  4. 04

    Задайте срок действия

    Укажите дату истечения для временного доступа или оставьте бессрочным для долгоживущих сервисных интеграций.

  5. 05

    Скопируйте один раз

    Полный токен ct_live_ показывается только один раз. После закрытия панели остаётся видимым только префикс.

    ct_live_••••••••

Формат токена

ct_live_8Lk3...full-secret-value

Храните полный токен в secret manager вашей внешней системы. Call Trace хранит только хеш и после создания показывает лишь префикс.

Аутентификация

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

API-ключи интеграций отделены от сессий сотрудников. Передавайте ключ в заголовке Authorization и выдавайте только те области доступа, которые нужны вашей системе.

Заголовок

Authorization: Bearer ct_live_...
Content-Type: application/json

Области доступа

analysis:write создаёт анализы.

analysis:read читает статус и результаты.

webhooks:write управляет настройками webhooks.

Права доступа

Что разрешает каждая область

Области доступа суммируются. Начните с минимального набора для интеграции и добавляйте новые только когда конкретный endpoint этого требует.

Область
Назначение
Описание
analysis:write
Создание новых анализов
Обязательна для POST /api/v1/analyses. Позволяет внешней системе отправить fileUrl и поставить анализ в очередь.
analysis:read
Чтение статуса и результата анализа
Обязательна для GET /api/v1/analyses и GET /api/v1/analyses/{analysisId}. Используйте для polling и сверки данных.
calls:read
Чтение данных на уровне звонка
Даёт доступ к метаданным звонков через безопасные для интеграций endpoints. Не выдавайте, если интеграция только отправляет файлы.
storage:write
Запись исходных файлов
Зарезервирована для интеграций с прямой загрузкой в хранилище. Для fileUrl-интеграций обычно не нужна.
webhooks:read
Чтение конфигурации и истории webhooks
Позволяет просматривать webhook endpoints и попытки доставки для поддержки или мониторинга.
webhooks:write
Управление webhooks
Позволяет создавать и обновлять webhook endpoints. Оставляйте на admin/service ключах, а не на обычных ключах отправки анализов.

Рекомендуемый минимум

Для стандартного сценария создайте один токен с analysis:write и analysis:read. Webhooks настраивает администратор в UI, поэтому внешней системе обычно не нужен webhooks:write.

Срок действия токена

Истечение, бессрочный доступ и ротация

У каждого API-ключа свой срок жизни. Токен может быть бессрочным, автоматически истекать или отзываться вручную.

Бессрочный токен

expiresAt пуст. Токен активен, пока администратор его не отзовёт. Используйте только для доверенных backend-to-backend интеграций с процессом ротации.

Токен с датой истечения

expiresAt задан. После этой даты API возвращает 401 и новые запросы не принимаются. Используйте для тестов, подрядчиков или временного доступа.

Отозванный токен

revokedAt устанавливается сразу при отзыве ключа администратором. Отзыв мгновенный и необратим; создайте новый ключ.

Ротация

Создайте новый ключ, разверните его во внешней системе, убедитесь что обновился last used, затем отзовите старый ключ. Это исключает простой.

Справочник API

Создать анализ

Запрос сохраняет исходный файл и запускает фоновую обработку. Клиент не должен ждать завершения транскрипции или оценки в этом запросе.

Создать анализ

Возвращает 202 Accepted и ставит обработку в очередь.

POST/api/v1/analyses

Запрос

POST /api/v1/analyses
Authorization: Bearer ct_live_...
Content-Type: application/json

{
  "fileUrl": "https://example.com/calls/call-123.mp3",
  "agentId": "6f6af4bb-4f23-4f3f-a87e-85f2f8322dc1",
  "queueId": "7a7bf5cc-5e34-4f4g-b98f-96g3g9433ed2",
  "externalId": "crm-call-123",
  "idempotencyKey": "crm-call-123",
  "metadata": {
    "customerId": "cust_42",
    "source": "crm"
  }
}

Ответ

HTTP/1.1 202 Accepted
Content-Type: application/json

{
  "analysisId": "6f6af4bb-4f23-4f3f-a87e-85f2f8322dc1",
  "status": "queued",
  "externalId": "crm-call-123"
}
Поле
Тип
Обязательность
Описание
fileUrl
string
Обязательно
HTTPS URL аудиофайла для анализа. Максимальный размер — 20 МБ.
fileName
string
Необязательно
Имя в Call Trace. Если не передано, берётся последний сегмент пути из fileUrl.
agentId
uuid
Обязательно
Агент для анализа. Должен существовать в вашей компании.
queueId
uuid
Обязательно
Очередь со скриптом для оценки. Должна иметь активную версию скрипта.
language
string
Необязательно
Язык транскрипции. По умолчанию auto, если не передан.
externalId
string
Необязательно
Идентификатор из вашей CRM, helpdesk или телефонии.
idempotencyKey
string
Необязательно
Дедуплицирует повторы из вашей системы.
metadata
object
Необязательно
Небольшой JSON-объект, возвращаемый в status и webhook payloads.

Требования к URL файла

fileUrl должен использовать HTTPS. Приватные, localhost и внутренние IP-диапазоны отклоняются, включая редиректы во внутренние сети. Максимальный размер файла — 20 МБ. Файлы скачиваются с таймаутами и проверкой content-type до обработки.

Справочник API

Читать статус и результаты

Используйте этот endpoint, когда системе нужно сверить состояние или восстановиться после пропущенных webhook-доставок.

Получить анализ

Возвращает последний статус задачи и доступные поля результата.

GET/api/v1/analyses/{analysisId}
{
  "analysisId": "6f6af4bb-4f23-4f3f-a87e-85f2f8322dc1",
  "status": "completed",
  "externalId": "crm-call-123",
  "call": {
    "durationSeconds": 184,
    "agentId": "agent-uuid",
    "queueId": "queue-uuid"
  },
  "evaluation": {
    "score": 82,
    "summary": "The agent followed the script and resolved the main request.",
    "emotion": {
      "label": "neutral",
      "score": 55,
      "comment": "The caller stayed calm throughout the conversation."
    },
    "criteria": [
      { "name": "Greeting", "score": 10, "maxScore": 10 },
      { "name": "Need discovery", "score": 18, "maxScore": 20 }
    ]
  },
  "transcript": {
    "language": "en",
    "segments": [
      { "speaker": "agent", "text": "Good afternoon, how can I help?" }
    ]
  },
  "metadata": {
    "customerId": "cust_42"
  },
  "error": null
}
queued

Запрос принят и ожидает обработки.

processing

Файл скачивается, транскрибируется и оценивается.

completed

Оценка, транскрипция и сводка звонка доступны.

failed

Обработка не удалась после повторов. Детали возвращаются в error.

Справочник API

Список анализов

Поиск по status, externalId, agent, queue или диапазону дат. Используйте для back-office сверки и инструментов поддержки.

Список анализов

Возвращает постраничный список анализов компании интеграции.

GET/api/v1/analyses
GET /api/v1/analyses?status=completed&externalId=crm-call-123
Authorization: Bearer ct_live_...

Webhooks

Webhook payload

Настройте webhook endpoints в Админ > Интеграции. Payloads содержат информацию, необходимую для сохранения результата оценки в вашей системе.

analysis.createdanalysis.completedanalysis.failed
{
  "deliveryId": "whd_01jz8n0f8ck2bk0smq7h2x1t0r",
  "event": "analysis.completed",
  "occurredAt": "2026-06-19T12:00:00.000Z",
  "analysisId": "6f6af4bb-4f23-4f3f-a87e-85f2f8322dc1",
  "externalId": "crm-call-123",
  "call": {
    "status": "completed",
    "durationSeconds": 184,
    "recordingUrl": "https://storage.example.com/audio/call-123.mp3"
  },
  "evaluation": {
    "score": 82,
    "summary": "The agent followed the script and resolved the main request.",
    "emotion": {
      "label": "neutral",
      "score": 55,
      "comment": "The caller stayed calm throughout the conversation."
    },
    "criteria": [
      { "name": "Greeting", "score": 10, "maxScore": 10 }
    ]
  },
  "transcript": {
    "language": "en",
    "segments": [
      { "speaker": "agent", "text": "Good afternoon, how can I help?" }
    ]
  },
  "metadata": {
    "customerId": "cust_42"
  },
  "error": null
}

Текст скрипта по умолчанию не включается. Используйте deliveryId для дедупликации и analysisId плюс event при сохранении переходов состояния.

Webhooks

Доставка и повторы

Call Trace сохраняет каждую попытку доставки и повторяет неудачные, чтобы результаты не терялись при таймауте или временных сбоях у клиента.

Успех

Любой ответ 2xx помечает доставку как выполненную.

Политика повторов

Первая попытка плюс 3 повтора с backoff, например 10 секунд, 1 минута и 5 минут.

История

Каждая попытка сохраняет статус, код ответа, сообщение об ошибке, метки времени и снимок payload.

Webhooks

Webhook secret

У каждого webhook endpoint есть secret. Call Trace отправляет его в каждой доставке, чтобы вы могли отклонять запросы из неизвестных источников.

Зачем проверять secret

URL webhook доступен из интернета. Сравните заголовок X-CallTrace-Secret с secret, который вы сохранили при создании endpoint. Если значения не совпадают, верните 401 и не обрабатывайте payload.

Что приходит в каждой доставке

POST /your/webhook-handler

X-CallTrace-Secret: whsec_8Lk3...your-endpoint-secret

X-CallTrace-Delivery: whd_01jz8n0f8ck2bk0smq7h2x1t0r

X-CallTrace-Event: analysis.completed

X-CallTrace-Timestamp: 2026-06-19T12:00:00.000Z

{ "event": "analysis.completed", "analysisId": "6f6af4bb-..." }

X-CallTrace-Secret

Secret endpoint. Сравните это значение с CALL_TRACE_WEBHOOK_SECRET на вашем сервере.

X-CallTrace-Delivery

Уникальный ID доставки. Используйте его, чтобы игнорировать повторные retry того же события.

X-CallTrace-Event

Тип события, например analysis.completed.

X-CallTrace-Timestamp

Когда Call Trace отправил запрос. Полезно для логов и поддержки.

Как проверить

Прочитайте X-CallTrace-Secret из заголовков запроса и сравните с secret, который показывается один раз в Админ > Интеграции при создании webhook. Храните secret в переменной окружения и отклоняйте несовпадения до обработки JSON.

Пример на Node.js

const secret = request.headers.get("x-calltrace-secret");

if (secret !== process.env.CALL_TRACE_WEBHOOK_SECRET) {
  return new Response("Unauthorized", { status: 401 });
}

const payload = await request.json();

Примеры

Создать анализ на вашем языке

Все примеры используют один и тот же стабильный endpoint и ожидают API-ключ в CALL_TRACE_API_KEY.

const response = await fetch("https://your-domain.com/api/v1/analyses", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.CALL_TRACE_API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    fileUrl: "https://example.com/calls/call-123.mp3",
    fileName: "call-123.mp3",
    language: "auto",
    externalId: "crm-call-123",
    idempotencyKey: "crm-call-123"
  })
});

const analysis = await response.json();
console.log(analysis.analysisId);

Ошибки

Обработка ошибок

Используйте idempotency keys для безопасных повторов. Ошибки валидации возвращаются синхронно. Ошибки обработки — через status endpoint и webhooks analysis.failed.

400

Невалидный JSON, отсутствует fileUrl, неподдерживаемый content type или невалидные metadata.

401

Отсутствует, истёк, отозван или некорректный API-ключ.

403

API-ключ не включает требуемую область доступа.

409

Тот же idempotency key уже использован для другого payload.

422

URL файла заблокирован, приватный, не HTTPS, слишком большой или недоступен.

500

Временная ошибка сервера. Повторите с тем же idempotency key.

Call Trace