ادمج المكالمات المترجمة في أنظمتك الخاصة

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

  قائمة أرجل المكالمات، الأحدث أولاً. قم بالتصفية باستخدام limit (من 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 والاتصال أو الرفض. يتم تجاهل caller_id الذي لا تملكه.

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

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

X-Owaa-Signature يحمل كل طلب رأس X-Owaa-Signature بالصيغة t=<ثواني يونكس>,v1=<سداسي عشري>. قيمة 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 موثق متصل.
• 422رفض Twilio المكالمة، أو معرف المتصل الذي ذكرته ليس ملكًا لك.
• 429تجاوز حد المعدل: انتظر الوقت المحدد في Retry-After. يتم إرجاعه أيضًا إلى عنوان تم قفله مؤقتًا بعد مفاتيح غير صالحة متكررة.

لا تحتوي واجهة برمجة التطبيقات على مفتاح عدم التكرار. إذا انتهت مهلة طلب إجراء مكالمة، قم بإدراج مكالماتك الأخيرة قبل إرسالها مرة أخرى.

اتصال

باستخدام مفتاح API: أرسله كرمز حامل (Bearer token) في رأس التخويل (Authorization header).

باستخدام 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 بشكل أعمى: تحقق من المكالمة أولاً.