المصادقة الصوتية

المصادقة الصوتية هي أداة اتصال-للموافقة صادرة. يطلب نظامك من Wave التحقّق من شخص؛ فتتّصل Wave بذلك الرقم، وتُشغّل رسالة قصيرة ثنائية اللغة تصف ما تجري الموافقة عليه، ثم تلتقط ضغطة المفتاح وتُعيد نتيجة موثوقة قابلة للقراءة آليًا عبر webhook موقّع (وواجهة استعلام عن الحالة). هي المكافئ الصوتي لخطوة الموافقة-بالدفع / رمز OTP — عامل أمان، وليست قائمة رد صوتي. ولأن النتيجة تحكم الوصول، فهي مصمّمة لتفشل بأمان: الموافقة الصريحة وحدها تمنح الوصول، ولا يمكن لردّ آليّ / بريد صوتي أن يوافق أبدًا.

هذا مسار صادر يبدأ عبر الواجهة (Wave تتّصل بالمستخدم). وهو يختلف عن قوائم الرد الصوتي (حيث يتّصل المتصل بك). المصادقة الصوتية مُقيّدة — اطلب من جهة تواصلك في Wave تفعيلها لحسابك.

المصادقة والفئات

كل مسار ضمن /v1/voice-auth يتطلّب مفتاح إنتاج (sk_live_) مع صلاحية voice_auth:write (أو voice_auth:read للاستعلام). لا تستطيع المفاتيح التجريبية إجراء مكالمات مصادقة حقيقية.

إنشاء طلب تحقّق (challenge)

curl https://api.wave.sa/v1/voice-auth/challenges \
  -H "Authorization: Bearer $WAVE_API_KEY" \
  -H "Idempotency-Key: 4e1a…" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+9665XXXXXXXX",
    "locale": "ar",
    "context": { "action": "login", "app_name": "Wave Secure" },
    "assurance": "standard",
    "ttl_seconds": 90,
    "retry_on_no_answer": 0,
    "metadata": { "ref": "REF-8842" }
  }'

const res = await fetch("https://api.wave.sa/v1/voice-auth/challenges", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.WAVE_API_KEY}`,
    "Idempotency-Key": "4e1a…",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    phone_number: "+9665XXXXXXXX",
    locale: "ar",
    context: {
      action: "login",
      app_name: "Wave Secure",
    },
    assurance: "standard",
    ttl_seconds: 90,
    retry_on_no_answer: 0,
    metadata: {
      ref: "REF-8842",
    },
  }),
});
console.log(await res.json());

import os

import requests

res = requests.post(
    "https://api.wave.sa/v1/voice-auth/challenges",
    headers={
        "Authorization": f"Bearer {os.environ['WAVE_API_KEY']}",
        "Idempotency-Key": "4e1a…",
    },
    json={
        "phone_number": "+9665XXXXXXXX",
        "locale": "ar",
        "context": {
            "action": "login",
            "app_name": "Wave Secure",
        },
        "assurance": "standard",
        "ttl_seconds": 90,
        "retry_on_no_answer": 0,
        "metadata": {
            "ref": "REF-8842",
        },
    },
)
print(res.json())

الحقل	مطلوب	ملاحظات
`phone_number`	✅	بصيغة E.164 (`+9665…`). الرقم الذي تتّصل به Wave.
`locale`	—	`ar` (افتراضي) أو `en` — لغة الرسالة.
`context`	—	`{ action, app_name, reference }` تُدرَج في الرسالة. بلا أسرار — لا كلمة مرور/OTP/رقم بطاقة.
`assurance`	—	`standard` (اضغط 1) أو `number_match` (انظر أدناه). الافتراضي `standard`.
`ttl_seconds`	—	من 30 إلى 180، الافتراضي 90. ينتهي الطلب بعدها.
`retry_on_no_answer`	—	من 0 إلى 2، الافتراضي 0 — إعادة اتصال تلقائية عند عدم الردّ/الانشغال، ضمن مدّة الصلاحية.
`idempotency_key`	—	أرسله كترويسة `Idempotency-Key`؛ تُعيد المحاولة نفس الطلب دون مكالمة ثانية.
`metadata`	—	بيانات معتمة؛ تُعاد في الـ webhook.
`brand_id`	—	اسم متصل معتمد يُنطق بدلًا من «Wave». احذفه لاستخدام الاسم الافتراضي لمشروعك، وإلا «Wave».

تُعيد 201 معرّف الطلب و(في وضع number_match) الأرقام المطلوب عرضها:

{ "challenge_id": "9f1c…", "state": "initiated", "expires_at": "2026-09-01T12:01:30Z", "brand_id": null }

النتيجة — الفشل الآمن

يصل الطلب إلى حالة نهائية واحدة state:

الحالة	المعنى	تمنح الوصول؟
`approved`	وافق المستخدم (ضغط 1، أو أدخل أرقام المطابقة)	✅ نعم
`declined`	رفض المستخدم (ضغط 2)	لا
`timeout`	ردّ لكن دون إدخال صالح بعد إعادة المحاولة	لا
`no_answer` / `busy` / `failed`	لم تتّصل المكالمة	لا
`machine_detected`	ردّ بريد صوتي/آلة	لا
`expired`	لا قرار قبل `expires_at`	لا

approved وdeclined فقط قراران صريحان من المستخدم. عامِل كل حالة أخرى كعدم منح وافشل بأمان. وتحقّق دائمًا من النتيجة عبر واجهة الحالة قبل اعتماد الموافقة — دفاعًا في العمق.

كشف الردّ الآلي (AMD)

قبل أي رسالة، تُصنّف Wave من ردّ على المكالمة. ردّ الآلة أو البريد الصوتي ينتهي إلى machine_detected ولا تُشغَّل رسالة الموافقة أبدًا — فلا يمكن لبريد صوتي التقاط ضغطة أو ترك موافقة. هذا مُطبَّق، وليس بأفضل جهد.

المطابقة الرقمية عالية التوكيد

للإجراءات عالية القيمة (المدفوعات، تغييرات المشرف)، اضبط assurance: "number_match". تتضمّن استجابة 201 قيمة match_digits (مثل "47") — اعرضها لمستخدمك. تطلب المكالمة حينها من المتّصل إدخال تلك الأرقام بالضبط للموافقة. أي إدخال خاطئ لا يوافق — وهذا يُبطل إرهاق المصادقة (“فقط اضغط 1”) والموافقات العرضية.

{ "challenge_id": "9f1c…", "state": "initiated", "expires_at": "…", "match_digits": "47" }

اسم المتصل

تقول المكالمة افتراضيًا «مكالمة من Wave…». يمكن لمؤسّستك أن تجعلها تقول اسمك أنت (اسم المتصل) بدلًا من ذلك، بلغة المكالمة: «مكالمة من أكمي للتحقّق من…». اسم المتصل اسمٌ منطوق فقط — يبقى رقم المتصل هو رقم Wave الموثَّق. اعتماد اسم (البوابة). في بوابة المطوّرين، افتح أسماء المتصل واطلب اسمًا بالإنجليزية وبالعربية. يحتاج الاسم إلى موافقتين قبل أن تستخدمه أي مكالمة: مالك أو مسؤول في مؤسّستك (طلب المالك أو المسؤول يتجاوز هذه الخطوة)، ثم Wave. الاسم من 2 إلى 40 حرفًا (حروف وأرقام ومسافات و. & ' -؛ بلا عناوين ويب؛ بلا 4 أرقام متتالية أو أكثر)، ويجب أن يستخدم الاسم العربي حروفًا عربية. لا يتغيّر اسم بعد طلبه — لاستخدام اسم جديد، اطلب اسمًا جديدًا. استخدامه في طلب تحقّق. أرسل brand_id عند الإنشاء. تنطق المكالمة:

قيمة brand_id التي ترسلها، إن وُجدت؛ وإلا
الاسم الافتراضي لمشروعك (يُضبط من صفحة أسماء المتصل)؛ وإلا
«Wave» — فيستمر عمل أي تكامل لا يرسل brand_id.

يجب أن يكون brand_id اسمًا معتمدًا لمؤسّستك؛ أي شيء آخر (غير معروف، أو قيد المراجعة، أو مرفوض، أو متوقف، أو تابع لمؤسّسة أخرى) يُعيد 422 VOICE_AUTH_BRAND_NOT_APPROVED ولا تُجرى أي مكالمة. يحتفظ الطلب بالاسم الذي بدأ به، فإيقاف اسم أثناء مكالمة لا يغيّر ما يسمعه المستخدم. تحمل استجابة 201 وواجهة الحالة والـ webhook قيمة brand_id (null = «Wave»). عرض أسمائك من نظامك.

curl https://api.wave.sa/v1/voice-auth/brands?limit=20 \
  -H "Authorization: Bearer $WAVE_API_KEY"

const res = await fetch("https://api.wave.sa/v1/voice-auth/brands?limit=20", {
  headers: {
    Authorization: `Bearer ${process.env.WAVE_API_KEY}`,
  },
});
console.log(await res.json());

import os

import requests

res = requests.get(
    "https://api.wave.sa/v1/voice-auth/brands?limit=20",
    headers={
        "Authorization": f"Bearer {os.environ['WAVE_API_KEY']}",
    },
)
print(res.json())

{
  "data": [
    {
      "brand_id": "7b0e…",
      "name_en": "Acme",
      "name_ar": "أكمي",
      "status": "approved",
      "rejection_reason": null,
      "is_default": true,
      "created_at": "2026-10-01T09:12:00Z",
      "decided_at": "2026-10-01T11:40:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

يتطلّب مفتاح إنتاج بصلاحية voice_auth:read. يُعيد كل أسماء مؤسّستك مع status (pending_tenant، pending_wave، approved، rejected، retired) وسبب الرفض، و is_default لـ مشروع المفتاح. للصفحة التالية أرسل cursor = قيمة next_cursor السابقة.

إذا تعذّرت خدمة تحويل النص إلى كلام، يمكن أن تنتقل Wave إلى رسائل مسجّلة مسبقًا. في هذا الوضع لا تذكر الرسالة العادية اسم أي متصل (لا «Wave» ولا اسمك)؛ وتبقى رسالة مطابقة الرقم تذكر اسمك. ويبقى brand_id محفوظًا ومُعادًا.

webhook النتيجة

{
  "event": "voice_auth.completed",
  "data": {
    "challenge_id": "9f1c…",
    "state": "approved",
    "decided_at": "2026-09-01T12:00:41Z",
    "attempts": 1,
    "amd_result": "human",
    "brand_id": null
  }
}

عند بلوغ حالة نهائية ترسل Wave حدث voice_auth.completed موقّعًا إلى نقطة webhook الخاصّة بمشروعك. تحقّق من كل تسليم:

X-Wave-Signature — sha256=…، توقيع HMAC-SHA256 للمحتوى الخام بسرّ التوقيع الخاصّ بنقطتك. ارفض أي عدم تطابق.
X-Wave-Timestamp — بالثواني (unix)؛ ارفض التسليمات الأقدم من نافذتك (مثلًا 5 دقائق).
X-Wave-Event-Id — ثابت عبر إعادات الإرسال؛ استخدمه لمنع التكرار.

الـ webhook إشعار — أعد التأكيد عبر واجهة الحالة قبل المنح.

الاستعلام عن الحالة

curl https://api.wave.sa/v1/voice-auth/challenges/9f1c… \
  -H "Authorization: Bearer $WAVE_API_KEY"

const res = await fetch("https://api.wave.sa/v1/voice-auth/challenges/9f1c…", {
  headers: {
    Authorization: `Bearer ${process.env.WAVE_API_KEY}`,
  },
});
console.log(await res.json());

import os

import requests

res = requests.get(
    "https://api.wave.sa/v1/voice-auth/challenges/9f1c…",
    headers={
        "Authorization": f"Bearer {os.environ['WAVE_API_KEY']}",
    },
)
print(res.json())

تُعيد الحالة الحالية state وعدد المحاولات وamd_result وbrand_id والطوابع الزمنية و(عند الانتهاء) القرار. مقصورة على مؤسّستك فقط.

المعرّف الفريد للطلب، حدود المعدّل، ومكافحة الإساءة

Idempotency — أرسل Idempotency-Key؛ تُعيد المحاولة بنفس المفتاح نفس الطلب ولا تُجري مكالمة ثانية.
حدود لكل رقم ولكل جهة إصدار — تحدّ Wave من عدد الطلبات لرقم واحد ولكل مفتاح، وتحجب الأرقام/البادئات المُسيئة، لمنع القصف الصوتي والاحتيال. عند تجاوز الحدّ → 429.

الأخطاء

الرمز	HTTP	متى
`VOICE_AUTH_DISABLED`	503	غير مُفعّل لهذا الحساب
`SANDBOX_KEY_NOT_ALLOWED`	400	استُخدم مفتاح تجريبي
`VALIDATION_ERROR`	400	رقم/لغة/مدّة غير صالحة، أو `context` يحوي سرًّا
`VOICE_AUTH_BLOCKED`	403	الرقم الهدف محظور
`VOICE_AUTH_RATE_LIMITED`	429	تجاوُز حدّ لكل رقم/جهة إصدار
`VOICE_AUTH_NOT_FOUND`	404	لا يوجد طلب بهذا المعرّف لمؤسّستك
`VOICE_AUTH_BRAND_NOT_APPROVED`	422	`brand_id` ليس اسم متصل معتمدًا لمؤسّستك

البدء

الصوت

Web Callback

واتساب

المرجع

المصادقة الصوتية

المصادقة والفئات

إنشاء طلب تحقّق (challenge)

النتيجة — الفشل الآمن

كشف الردّ الآلي (AMD)

المطابقة الرقمية عالية التوكيد

اسم المتصل

webhook النتيجة

الاستعلام عن الحالة

المعرّف الفريد للطلب، حدود المعدّل، ومكافحة الإساءة

الأخطاء

​المصادقة والفئات

​إنشاء طلب تحقّق (challenge)

​النتيجة — الفشل الآمن

​كشف الردّ الآلي (AMD)

​المطابقة الرقمية عالية التوكيد

​اسم المتصل

​webhook النتيجة

​الاستعلام عن الحالة

​المعرّف الفريد للطلب، حدود المعدّل، ومكافحة الإساءة

​الأخطاء

المصادقة والفئات

إنشاء طلب تحقّق (challenge)

النتيجة — الفشل الآمن

كشف الردّ الآلي (AMD)

المطابقة الرقمية عالية التوكيد

اسم المتصل

webhook النتيجة

الاستعلام عن الحالة

المعرّف الفريد للطلب، حدود المعدّل، ومكافحة الإساءة

الأخطاء