Встраивайте звонки с переводом в свои собственные системы

curl https://b2b.owaa.ai/v1/b2b/admin/billing \
  -H "Authorization: Bearer $API_KEY"

Отправляйте ключ в заголовке Authorization. Ключи не принимаются в качестве параметра запроса.

Ключи API могут вызывать только конечные точки интеграции, перечисленные на этой странице, и сервер MCP. Управление ключами API, членами команды, пополнением счета, учетными данными оператора и лимитами расходов требует сеанса консоли с входом в систему.

Поверните ключ из консоли (страница ключей API): новый ключ отображается один раз, а старый немедленно перестает работать.

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

• POST/calls/originate

  Начните переведенный звонок между телефоном вашего агента и удаленной стороной, используя ваш собственный подключенный аккаунт Twilio.

• GET/caller-id/preview?destination=

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

• GET/calls

  Перечислить сегменты звонков, начиная с самых новых. Фильтруйте по лимиту (от 1 до 200) и статусу, а также используйте курсор в next_cursor для пагинации.

• GET/calls/{id}

  Получить один сегмент звонка.

• GET/calls/{id}/recording

  Передавать запись сегмента в виде аудио Opus. Выберите сторону с side=in или side=out.

• GET/billing

  Прочитайте ваш баланс, тариф за минуту, оставшиеся минуты и порог низкого баланса.

• GET/twilio-numbers

  Перечислите свои номера Twilio с их идентификатором, настройками маршрутизации и статусом. Только для чтения: учетные данные не возвращаются.

• PUT/twilio-numbers/{id}/route

  Установите URL для входящей маршрутизации и запасное назначение для одного из ваших номеров Twilio.

curl -X POST https://b2b.owaa.ai/v1/b2b/admin/calls/originate \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_number": "+14165550100",
    "far_number": "+34600000000",
    "agent_language": "en",
    "far_language": "es"
  }'

{
  "bridge_id": "...",
  "agent_call_sid": "...",
  "far_call_sid": "...",
  "agent_caller_id": "+14165550101",
  "far_caller_id": "+14165550101",
  "agent_must_confirm": false
}

Успешный запрос возвращает 201 с идентификаторами звонка. Сначала выполните предварительный просмотр идентификатора вызывающего абонента, чтобы избежать случаев 409.

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

curl "https://b2b.owaa.ai/v1/b2b/admin/calls?limit=20" \
  -H "Authorization: Bearer $API_KEY"

Чтобы настроить маршрутизацию, вам нужен идентификатор номера. Найдите его с помощью GET /twilio-numbers, который перечисляет ваши номера (показаны здесь с основными полями).

curl https://b2b.owaa.ai/v1/b2b/admin/twilio-numbers \
  -H "Authorization: Bearer $API_KEY"

[
  {
    "id": "<number_id>",
    "phone_number_e164": "+14165550101",
    "friendly_name": "Support line",
    "country_code": "CA",
    "voice_enabled": true,
    "verified": true,
    "routes_to_owaa": true,
    "inbound_destination_e164": "+34600000000",
    "inbound_routing_url": "https://example.com/owaa/route",
    "agent_language": "es",
    "caller_language_hint": "en"
  }
]

Затем настройте входящую маршрутизацию для этого номера с помощью PUT /twilio-numbers/{id}/route: URL-адрес, который Owaa вызывает для каждого входящего звонка, запасное направление и, при необходимости, язык агента и подсказку языка для звонящего.

curl -X PUT https://b2b.owaa.ai/v1/b2b/admin/twilio-numbers/<number_id>/route \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "routing_url": "https://example.com/owaa/route",
    "destination_e164": "+34600000000",
    "agent_language": "es",
    "caller_language_hint": "en"
  }'

Тело запроса

{
  "event": "call.inbound",
  "call_id": "...",
  "tenant_id": "...",
  "from": "+14165550100",
  "to": "+14165550101",
  "twilio_call_sid": "...",
  "received_at": "..."
}

Ответьте 200 и подключите или отклоните. Идентификатор вызывающего абонента, которым вы не владеете, игнорируется.

{ "action": "connect", "destination": "+34600000000", "caller_id": "+14165550101" }

{ "action": "reject", "reason": "closed" }

X-Owaa-Signature Каждый запрос содержит заголовок X-Owaa-Signature в формате t=<unix seconds>,v1=<hex>. Значение v1 — это HMAC-SHA256 от временной метки, точки и необработанного тела запроса, зашифрованное вашим секретом маршрутизации. Проверьте его на соответствие необработанному телу и отклоните временные метки старше пяти минут.

Ваш секрет маршрутизации отображается один раз на странице «Маршрутизация» в консоли.

Окно временной метки ограничивает повторы пятью минутами. Чтобы заблокировать повторы внутри него, также запомните call_id каждого запроса, который вы уже обработали.

import { createHmac, timingSafeEqual } from "node:crypto";

// rawBody: the exact bytes received, as a string or Buffer.
// Never re-serialise parsed JSON: that changes the bytes and the signature.
export function verifyOwaaSignature(rawBody, header, secret) {
  const parts = Object.fromEntries(
    String(header ?? "").split(",").map((p) => p.split("=")),
  );
  const t = parts.t ?? "";
  if (!/^\d+$/.test(t) || !(Math.abs(Date.now() / 1000 - Number(t)) <= 300)) return false;
  const expected = createHmac("sha256", secret).update(`${t}.${rawBody}`).digest();
  const given = Buffer.from(parts.v1 ?? "", "hex");
  return given.length === expected.length && timingSafeEqual(given, expected);
}

import hashlib
import hmac
import time


def verify_owaa_signature(raw_body: bytes, header: str, secret: str) -> bool:
    parts = dict(p.split("=", 1) for p in (header or "").split(",") if "=" in p)
    try:
        t = int(parts["t"])
    except (KeyError, ValueError):
        return False
    if abs(time.time() - t) > 300:
        return False
    signed = f"{t}.".encode() + raw_body
    expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, parts.get("v1", ""))

• 600 запросов на чтение в минуту
• 120 запросов на запись в минуту
• 60 загрузок записей в минуту

• 401Отсутствует или недействительный ключ API.
• 402Недостаточный баланс для начала звонка.
• 409Нет доступного идентификатора вызывающего абонента или не подключен проверенный аккаунт Twilio.
• 422Twilio отклонил звонок, или указанный вами идентификатор вызывающего абонента не принадлежит вам.
• 429Превышен лимит запросов: подождите время, указанное в Retry-After. Также возвращается адресу, который временно заблокирован после многократных неверных ключей.

API не имеет ключа идемпотентности. Если запрос на совершение звонка истекает по времени, перечислите свои недавние звонки, прежде чем отправлять его снова.

Подключение

С помощью ключа API: отправьте его как токен Bearer в заголовке Authorization.

С помощью OAuth: клиенты, поддерживающие OAuth 2.1 с PKCE, могут войти в систему и получить доступ из консоли. Каждое разрешение может быть отозвано.

Конфигурация клиента

Добавьте сервер к любому клиенту MCP, который поддерживает удаленные HTTP-серверы, и замените заполнитель своим ключом.

{
  "mcpServers": {
    "owaa": {
      "type": "http",
      "url": "https://mcp.owaa.ai/business",
      "headers": { "Authorization": "Bearer <your-api-key>" }
    }
  }
}

claude mcp add --transport http owaa https://mcp.owaa.ai/business \
  --header "Authorization: Bearer <your-api-key>"

Инструменты

• list_languagesПеречислить языки, доступные для переведенных звонков.
• check_call_costОценить стоимость звонка до его совершения.
• get_callПолучить один звонок с его статусом и стоимостью.
• list_recent_activityПеречислить недавнюю активность в вашей учетной записи.
• place_translated_callСовершить переведенный звонок: сначала звонит телефон вашего оператора, затем удаленной стороны. Расходует ваш баланс.
• delegate_call_taskПередать телефонную задачу ИИ-звонящему Owaa с целью и полями для сбора. Доступно, если включено для вашего бизнеса.
• get_taskПроверить ход выполнения и результат делегированной задачи.
• cancel_taskОтменить делегированную задачу.

Области действия

• activity:readПоиск языков, стоимости, звонков и задач. Всегда предоставляется.
• calls:translateСовершать переведенные звонки.
• tasks:delegateДелегировать телефонные задачи.

Области действия для ключа API устанавливаются в консоли. Инструмент, находящийся вне областей действия ключа, возвращает scope_not_granted.

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

Инструменты возвращают ошибки в виде кода и сообщения, например insufficient_balance, country_not_allowed или rate_limited. Не повторяйте outcome_unknown вслепую: сначала проверьте звонок.