Integre chamadas traduzidas nos seus próprios sistemas

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

Envie a chave no cabeçalho Authorization. As chaves não são aceites como parâmetro de consulta.

As chaves API só podem chamar os endpoints de integração listados nesta página e o servidor MCP. Gerir chaves API, membros da equipa, carregamentos de faturação, credenciais de operadora e limites de gastos requer uma sessão de consola iniciada.

Rode uma chave da consola (página de chaves API): a nova chave é mostrada uma vez e a antiga deixa de funcionar imediatamente.

Um pedido com uma chave em falta ou inválida retorna 401. Tentativas falhadas repetidas de um endereço são bloqueadas por um tempo.

• POST/calls/originate

  Inicie uma chamada traduzida entre o telefone do seu agente e uma parte remota, usando sua própria conta Twilio conectada.

• GET/caller-id/preview?destination=

  Teste um destino: mostra qual ID de chamador seria usado, para que problemas de ID de chamador apareçam antes de você discar.

• GET/calls

  Liste as pernas da chamada, as mais recentes primeiro. Filtre com limite (1 a 200) e status, e pagine com o cursor em next_cursor.

• GET/calls/{id}

  Busque uma única perna de chamada.

• GET/calls/{id}/recording

  Transmita a gravação de uma perna como áudio Opus. Escolha o lado com side=in ou side=out.

• GET/billing

  Leia seu saldo, taxa por minuto, minutos restantes e limite de saldo baixo.

• GET/twilio-numbers

  Liste seus números Twilio com seu ID, configurações de roteamento e status. Somente leitura: nenhuma credencial é retornada.

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

  Defina o URL de roteamento de entrada e o destino de fallback para um dos seus números 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
}

Uma solicitação bem-sucedida retorna 201 com os identificadores da chamada. Execute a pré-visualização do ID do chamador primeiro para evitar os casos 409.

Listar as pernas de chamadas recentes. Use o endpoint de faturação da mesma forma para ler o seu saldo.

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

Para definir o roteamento, você precisa do ID do número. Encontre-o com GET /twilio-numbers, que lista seus números (mostrado aqui com os campos principais).

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

Em seguida, defina o roteamento de entrada para esse número com PUT /twilio-numbers/{id}/route: o URL que Owaa chama para cada chamada de entrada, o destino de fallback e, opcionalmente, o idioma do agente e uma dica de idioma para o chamador.

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

Corpo da solicitação

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

Responda com 200 e conecte ou rejeite. Um caller_id que você não possui é ignorado.

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

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

X-Owaa-Signature Cada solicitação carrega um cabeçalho X-Owaa-Signature no formato t=<segundos unix>,v1=<hex>. O valor v1 é o HMAC-SHA256 do timestamp, um ponto e o corpo da solicitação bruto, com chave secreta de roteamento. Verifique-o em relação ao corpo bruto e rejeite timestamps com mais de cinco minutos.

Sua chave secreta de roteamento é mostrada uma vez na página de Roteamento do console.

A janela de tempo limita as repetições a cinco minutos. Para bloquear repetições dentro dela, lembre-se também do call_id de cada pedido que já tratou.

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 solicitações de leitura por minuto
• 120 solicitações de escrita por minuto
• 60 downloads de gravação por minuto

• 401Chave de API ausente ou inválida.
• 402Saldo insuficiente para iniciar a chamada.
• 409Nenhum ID de chamador utilizável, ou nenhuma conta Twilio verificada conectada.
• 422Twilio recusou a chamada, ou um ID de chamador que você nomeou não é um que você possui.
• 429Limite de taxa excedido: aguarde o tempo em Retry-After. Também devolvido a um endereço que está temporariamente bloqueado após repetidas chaves inválidas.

A API não possui chave de idempotência. Se uma solicitação para fazer uma chamada expirar, liste suas chamadas recentes antes de enviá-la novamente.

Conectar

Com uma chave API: envie-a como um token Bearer no cabeçalho de Autorização.

Com OAuth: clientes que suportam OAuth 2.1 com PKCE podem iniciar sessão e ter acesso concedido a partir da consola. Cada concessão pode ser revogada.

Configuração do cliente

Adicione o servidor a qualquer cliente MCP que suporte servidores HTTP remotos e substitua o espaço reservado pela sua chave.

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

Ferramentas

• list_languagesListar os idiomas disponíveis para chamadas traduzidas.
• check_call_costEstimar o custo de uma chamada antes de ser efetuada.
• get_callObter uma chamada, com o seu estado e custo.
• list_recent_activityListar a atividade recente na sua conta.
• place_translated_callFazer uma chamada traduzida: toca o telefone do seu operador, depois o da outra parte. Gasta o seu saldo.
• delegate_call_taskEntregar uma tarefa telefónica ao chamador de IA da Owaa, com um objetivo e os campos a recolher. Disponível quando ativado para o seu negócio.
• get_taskVerificar o progresso e o resultado de uma tarefa delegada.
• cancel_taskCancelar uma tarefa delegada.

Escopos

• activity:readConsultar idiomas, custos, chamadas e tarefas. Sempre concedido.
• calls:translateFazer chamadas traduzidas.
• tasks:delegateDelegar tarefas telefónicas.

Os âmbitos para uma chave API são definidos na consola. Uma ferramenta fora dos âmbitos da chave devolve scope_not_granted.

O servidor instrui os assistentes a verificar o custo e a confirmar com o utilizador antes de qualquer chamada que gaste dinheiro.

As ferramentas retornam erros como um código e uma mensagem, por exemplo, insufficient_balance, country_not_allowed ou rate_limited. Não tente novamente outcome_unknown cegamente: verifique a chamada primeiro.