Integrieren Sie übersetzte Anrufe in Ihre eigenen Systeme

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

Senden Sie den Schlüssel im Authorization-Header. Schlüssel werden nicht als Abfrageparameter akzeptiert.

API-Schlüssel können nur die auf dieser Seite und dem MCP-Server aufgeführten Integrations-Endpunkte aufrufen. Die Verwaltung von API-Schlüsseln, Teammitgliedern, Rechnungsaufladungen, Anbieterzugangsdaten und Ausgabenlimits erfordert eine angemeldete Konsolensitzung.

Drehen Sie einen Schlüssel aus der Konsole (API-Schlüssel-Seite): Der neue Schlüssel wird einmal angezeigt und der alte funktioniert sofort nicht mehr.

Eine Anfrage mit einem fehlenden oder ungültigen Schlüssel gibt 401 zurück. Wiederholte fehlgeschlagene Versuche von einer Adresse werden für eine Weile gesperrt.

• POST/calls/originate

  Starten Sie einen übersetzten Anruf zwischen dem Telefon Ihres Agenten und einem externen Teilnehmer, unter Verwendung Ihres eigenen verbundenen Twilio-Kontos.

• GET/caller-id/preview?destination=

  Führen Sie einen Probelauf für ein Ziel durch: Zeigt an, welche Anrufer-ID verwendet würde, damit Probleme mit der Anrufer-ID vor dem Wählen erkannt werden.

• GET/calls

  Listen Sie Anrufsegmente auf, die neuesten zuerst. Filtern Sie mit Limit (1 bis 200) und Status, und paginieren Sie mit dem Cursor in next_cursor.

• GET/calls/{id}

  Ein einzelnes Anrufsegment abrufen.

• GET/calls/{id}/recording

  Streamen Sie die Aufnahme eines Segments als Opus-Audio. Wählen Sie die Seite mit side=in oder side=out.

• GET/billing

  Lesen Sie Ihr Guthaben, den Minutenpreis, die verbleibenden Minuten und den Schwellenwert für geringes Guthaben ab.

• GET/twilio-numbers

  Listen Sie Ihre Twilio-Nummern mit ihrer ID, Routing-Einstellungen und Status auf. Nur lesbar: Es werden keine Anmeldeinformationen zurückgegeben.

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

  Legen Sie die eingehende Routing-URL und das Fallback-Ziel für eine Ihrer Twilio-Nummern fest.

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
}

Eine erfolgreiche Anfrage gibt 201 mit den Identifikatoren des Anrufs zurück. Führen Sie zuerst die Anrufer-ID-Vorschau aus, um die 409-Fälle zu vermeiden.

Liste der letzten Anrufabschnitte. Verwenden Sie den Abrechnungs-Endpunkt auf die gleiche Weise, um Ihr Guthaben abzufragen.

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

Um das Routing einzustellen, benötigen Sie die ID der Nummer. Finden Sie diese mit GET /twilio-numbers, das Ihre Nummern auflistet (hier mit den Hauptfeldern dargestellt).

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

Legen Sie dann das eingehende Routing für diese Nummer mit PUT /twilio-numbers/{id}/route fest: die URL, die Owaa für jeden eingehenden Anruf aufruft, das Fallback-Ziel und optional die Sprache des Agenten sowie einen Sprachhinweis für den Anrufer.

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

Anfragekörper

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

Antworten Sie mit 200 und verbinden oder ablehnen. Eine Anrufer-ID, die Ihnen nicht gehört, wird ignoriert.

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

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

X-Owaa-Signature Jede Anfrage enthält einen X-Owaa-Signature-Header in der Form t=<Unix-Sekunden>,v1=<Hex>. Der v1-Wert ist der HMAC-SHA256 des Zeitstempels, ein Punkt und der rohe Anfragekörper, verschlüsselt mit Ihrem Routing-Geheimnis. Überprüfen Sie ihn anhand des rohen Körpers und lehnen Sie Zeitstempel ab, die älter als fünf Minuten sind.

Ihr Routing-Geheimnis wird einmal auf der Routing-Seite der Konsole angezeigt.

Das Zeitstempelfenster begrenzt Wiederholungen auf fünf Minuten. Um Wiederholungen innerhalb dieses Zeitraums zu blockieren, merken Sie sich auch die call_id jeder Anfrage, die Sie bereits bearbeitet haben.

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 Leseanfragen pro Minute
• 120 Schreibanfragen pro Minute
• 60 Aufnahme-Downloads pro Minute

• 401Fehlender oder ungültiger API-Schlüssel.
• 402Unzureichendes Guthaben, um den Anruf zu starten.
• 409Keine verwendbare Anrufer-ID oder kein verifiziertes Twilio-Konto verbunden.
• 422Twilio hat den Anruf abgelehnt, oder eine von Ihnen genannte Anrufer-ID gehört Ihnen nicht.
• 429Ratenlimit überschritten: Warten Sie die Zeit in Retry-After ab. Wird auch an eine Adresse zurückgegeben, die nach wiederholten ungültigen Schlüsseln vorübergehend gesperrt ist.

Die API hat keinen Idempotenzschlüssel. Wenn eine Anfrage zum Tätigen eines Anrufs ein Timeout hat, listen Sie Ihre letzten Anrufe auf, bevor Sie sie erneut senden.

Verbinden

Mit einem API-Schlüssel: Senden Sie ihn als Bearer-Token im Authorization-Header.

Mit OAuth: Clients, die OAuth 2.1 mit PKCE unterstützen, können sich anmelden und erhalten Zugriff über die Konsole. Jede Berechtigung kann widerrufen werden.

Client-Konfiguration

Fügen Sie den Server zu jedem MCP-Client hinzu, der entfernte HTTP-Server unterstützt, und ersetzen Sie den Platzhalter durch Ihren Schlüssel.

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

Tools

• list_languagesListen Sie die für übersetzte Anrufe verfügbaren Sprachen auf.
• check_call_costSchätzen Sie die Kosten eines Anrufs, bevor er getätigt wird.
• get_callRufen Sie einen Anruf mit seinem Status und seinen Kosten ab.
• list_recent_activityListen Sie die letzten Aktivitäten Ihres Kontos auf.
• place_translated_callTätigen Sie einen übersetzten Anruf: Ihr Operator wird angerufen, dann die Gegenpartei. Verbraucht Ihr Guthaben.
• delegate_call_taskÜbergeben Sie eine Telefonaufgabe an den KI-Anrufer von Owaa, mit einem Ziel und den zu erfassenden Feldern. Verfügbar, wenn für Ihr Unternehmen aktiviert.
• get_taskÜberprüfen Sie den Fortschritt und das Ergebnis einer delegierten Aufgabe.
• cancel_taskEine delegierte Aufgabe abbrechen.

Bereiche

• activity:readSprachen, Kosten, Anrufe und Aufgaben nachschlagen. Immer gewährt.
• calls:translateÜbersetzte Anrufe tätigen.
• tasks:delegateTelefonaufgaben delegieren.

Bereiche für einen API-Schlüssel werden in der Konsole festgelegt. Ein Tool außerhalb der Bereiche des Schlüssels gibt scope_not_granted zurück.

Der Server weist Assistenten an, die Kosten zu überprüfen und mit dem Benutzer zu bestätigen, bevor ein Anruf getätigt wird, der Geld kostet.

Tools geben Fehler als Code und Nachricht zurück, zum Beispiel insufficient_balance, country_not_allowed oder rate_limited. Versuchen Sie outcome_unknown nicht blind erneut: Überprüfen Sie zuerst den Anruf.