Integra llamadas traducidas en tus propios sistemas

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

Envía la clave en el encabezado Authorization. Las claves no se aceptan como parámetro de consulta.

Las claves API solo pueden llamar a los puntos finales de integración que se enumeran en esta página y al servidor MCP. La gestión de claves API, miembros del equipo, recargas de facturación, credenciales de operador y límites de gasto requiere una sesión de consola iniciada.

Rota una clave desde la consola (página de claves API): la nueva clave se muestra una vez y la antigua deja de funcionar inmediatamente.

Una solicitud con una clave faltante o inválida devuelve 401. Los intentos fallidos repetidos desde una dirección se bloquean por un tiempo.

• POST/calls/originate

  Inicie una llamada traducida entre el teléfono de su agente y un tercero, utilizando su propia cuenta de Twilio conectada.

• GET/caller-id/preview?destination=

  Realice una prueba en seco de un destino: muestra qué identificador de llamadas se usaría, para que los problemas de identificador de llamadas salgan a la luz antes de marcar.

• GET/calls

  Liste las etapas de la llamada, las más recientes primero. Filtre con límite (1 a 200) y estado, y pagine con el cursor en next_cursor.

• GET/calls/{id}

  Obtenga una sola etapa de la llamada.

• GET/calls/{id}/recording

  Transmita la grabación de una etapa como audio Opus. Elija el lado con side=in o side=out.

• GET/billing

  Lea su saldo, tarifa por minuto, minutos restantes y umbral de saldo bajo.

• GET/twilio-numbers

  Liste sus números de Twilio con su ID, configuración de enrutamiento y estado. Solo lectura: no se devuelven credenciales.

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

  Establezca la URL de enrutamiento de entrada y el destino de respaldo para uno de sus números de 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
}

Una solicitud exitosa devuelve 201 con los identificadores de la llamada. Ejecute primero la vista previa del identificador de llamadas para evitar los casos 409.

Listar las etapas de llamadas recientes. Utilice el punto final de facturación de la misma manera para leer su saldo.

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

Para configurar el enrutamiento, necesita el ID del número. Encuéntrelo con GET /twilio-numbers, que enumera sus números (mostrados aquí con los campos principales).

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"
  }
]

Luego, configure el enrutamiento de entrada para ese número con PUT /twilio-numbers/{id}/route: la URL a la que Owaa llama para cada llamada entrante, el destino de respaldo y, opcionalmente, el idioma del agente y una sugerencia de idioma para la persona que llama.

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"
  }'

Cuerpo de la solicitud

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

Responda con 200 y conecte o rechace. Un caller_id que no le pertenece es ignorado.

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

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

X-Owaa-Signature Cada solicitud lleva un encabezado X-Owaa-Signature en el formato t=<segundos unix>,v1=<hex>. El valor v1 es el HMAC-SHA256 de la marca de tiempo, un punto y el cuerpo de la solicitud sin procesar, con la clave de su secreto de enrutamiento. Verifíquelo contra el cuerpo sin procesar y rechace las marcas de tiempo anteriores a cinco minutos.

Su secreto de enrutamiento se muestra una vez en la página de Enrutamiento de la consola.

La ventana de tiempo limita las repeticiones a cinco minutos. Para bloquear las repeticiones dentro de ella, recuerde también el call_id de cada solicitud que ya haya manejado.

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 solicitudes de lectura por minuto
• 120 solicitudes de escritura por minuto
• 60 descargas de grabaciones por minuto

• 401Clave API faltante o no válida.
• 402Saldo insuficiente para iniciar la llamada.
• 409No hay identificador de llamadas utilizable, o no hay una cuenta de Twilio verificada conectada.
• 422Twilio rechazó la llamada, o un identificador de llamadas que nombró no es uno de su propiedad.
• 429Límite de tasa excedido: espere el tiempo en Retry-After. También se devuelve a una dirección que está temporalmente bloqueada después de repetidas claves no válidas.

La API no tiene clave de idempotencia. Si una solicitud para realizar una llamada agota el tiempo de espera, liste sus llamadas recientes antes de enviarla de nuevo.

Conectar

Con una clave API: envíela como un token Bearer en el encabezado de autorización.

Con OAuth: los clientes que admiten OAuth 2.1 con PKCE pueden iniciar sesión y se les concede acceso desde la consola. Cada concesión puede ser revocada.

Configuración del cliente

Añada el servidor a cualquier cliente MCP que admita servidores HTTP remotos y reemplace el marcador de posición con su clave.

{
  "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>"

Herramientas

• list_languagesListar los idiomas disponibles para llamadas con traducción.
• check_call_costEstimar el coste de una llamada antes de realizarla.
• get_callObtener una llamada, con su estado y coste.
• list_recent_activityListar la actividad reciente de su cuenta.
• place_translated_callRealizar una llamada con traducción: suena el teléfono de su operador y luego el de la otra parte. Gasta su saldo.
• delegate_call_taskEntregar una tarea telefónica al agente de IA de Owaa, con un objetivo y los campos a recopilar. Disponible cuando está habilitado para su negocio.
• get_taskComprobar el progreso y el resultado de una tarea delegada.
• cancel_taskCancelar una tarea delegada.

Ámbitos

• activity:readConsultar idiomas, costes, llamadas y tareas. Siempre concedido.
• calls:translateRealizar llamadas con traducción.
• tasks:delegateDelegar tareas telefónicas.

Los alcances de una clave API se configuran en la consola. Una herramienta fuera de los alcances de la clave devuelve scope_not_granted.

El servidor instruye a los asistentes para que comprueben el coste y confirmen con el usuario antes de cualquier llamada que implique un gasto.

Las herramientas devuelven errores como un código y un mensaje, por ejemplo, insufficient_balance, country_not_allowed o rate_limited. No reintente outcome_unknown a ciegas: compruebe primero la llamada.