قوائم الرد الصوتي (IVR)

تُرحّب قائمة الرد الصوتي (IVR) بالمتّصل، وتقرأ عليه بعض الخيارات، ثم توجّهه حسب الزرّ الذي يضغطه — “اضغط 1 للمبيعات، اضغط 2 للدعم.” تُنشئ القائمة مرّة واحدة عبر هذه الواجهة (أو لوحة التحكّم)، وتربطها بأحد أرقام Wave لديك، فتُقدّمها Wave مباشرةً لكلّ متّصل — دون إعادة نشر. خلف الكواليس تُترجَم القائمة إلى أمر WaveML وهو <Gather> يُشغّل التحية ويجمع ضغطة زرّ واحدة، ثم يُنفّذ الفرع الخاصّ بذلك الرقم. هذه الواجهة هي طبقة التأليف فوق WaveML — تصف القائمة بصيغة JSON وتحوّلها Wave إلى مسار مكالمة.

هذه هي القائمة أحادية المستوى — تحية واحدة ومجموعة خيارات واحدة، ينهي كلٌّ منها المكالمة أو يحوّلها. القوائم الفرعية المتداخلة وأداة البناء المرئية ميزات منفصلة لاحقة. للتفريعات الكاملة اليوم، أعِد WaveML من نقطة النهاية الخاصّة بك بدلاً من ذلك.

المصادقة والطبقات

تتطلّب جميع نقاط /v1/callflows مفتاح واجهة بنطاق callflows:read أو callflows:write، أو جلسة لوحة تحكّم. يمكنك التأليف والاختبار بمفتاح sandbox (sk_sandbox_)، أمّا تقديم قائمة إلى مكالمة واردة حقيقية فيتطلّب مفتاح production (sk_live_) ومؤسسة بطبقة production ورقمًا مربوطًا (راجع ربط رقم أدناه).

تعريف القائمة

القائمة عبارة عن definition بصيغة JSON: تحية، وفروع لوحة المفاتيح، واحتياطيّ اختياريّ عند عدم ضغط المتّصل أيّ زرّ.

{
  "prompt": { "say": { "text": "To authenticate press 1, to decline press 2", "language": "en" } },
  "gather": { "num_digits": 1, "timeout_seconds": 8 },
  "branches": [
    { "digit": "1", "action": { "say": { "text": "You are authenticated. Goodbye." } }, "input": { "authenticated": true } },
    { "digit": "2", "action": { "say": { "text": "You chose not to authenticate. Goodbye." } }, "input": { "authenticated": false } }
  ],
  "no_input": { "action": { "say": { "text": "We didn't get your input. Goodbye." } } }
}

الحقل	النوع	إلزاميّ	ملاحظات
`prompt`	كائن	نعم	التحية. واحد فقط من `say` أو `play` (أدناه).
`gather.num_digits`	عدد صحيح	لا	عدد الأرقام المطلوب جمعها، `1`–`10`. الافتراضيّ `1`.
`gather.timeout_seconds`	عدد صحيح	لا	ثواني الانتظار لضغطة زرّ، `1`–`60`. الافتراضيّ `8`.
`branches`	مصفوفة	نعم	1–12 خيارًا. يجب أن يكون كلّ `digit` فريدًا.
`no_input`	كائن	لا	الإجراء عند عدم ضغط المتّصل أيّ زرّ قبل `timeout_seconds`.

التحية والإجراءات

التحية وكلّ إجراء فرع هو أحد هذه الأنواع. إجراء الفرع طرفيّ — ينهي المكالمة أو يحوّلها.

الإجراء	الشكل	ما يفعله
`say`	`{ "text": "…", "language"?: "en" }`	ينطق نصًّا (TTS). `text` ≤ 1000 محرف.
`play`	`{ "audio_ref": "https://…" }`	يشغّل مقطعًا صوتيًّا مسجّلًا (أدناه). تحيةً أو إجراءً.
`dial`	`{ "number": "0112345678" }`	يحوّل المتّصل إلى رقم سعوديّ.
`enqueue`	`{ "queue": "support", "strategy"?: "ring-all" }`	يُرسل المتّصل إلى طابور.
`hangup`	`true`	ينهي المكالمة.

أهداف dial مقيّدة بأرقام سعوديّة (KSA) — حماية من الاحتيال، لأنّ <Dial> يجسر المتّصل إلى مسار جديد.

مُدخل الفرع (حمولة webhook خاصّتك)

امنح الفرع كائن input، فتدمجه Wave في webhook باسم call.input حين يختار المتّصل ذلك الخيار — نقطة ربط تكاملك لمعرفة ما اختاره المتّصل.

حتّى 20 حقلًا؛ القيم نصّ (≤512) أو عدد أو قيمة منطقيّة.
المفتاحان call_id وdigits محجوزان (تضبطهما Wave) ويُرفضان.

إنشاء قائمة

POST /v1/callflows — أنشئ قائمة بالاسم. مرّر "activate": true لجعلها مباشرة فورًا.

curl -X POST https://api.wave.sa/v1/callflows \
  -H "Authorization: Bearer sk_sandbox_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "auth-ivr",
    "activate": true,
    "definition": {
      "prompt": { "say": { "text": "To authenticate press 1, to decline press 2" } },
      "branches": [
        { "digit": "1", "action": { "say": { "text": "You are authenticated. Goodbye." } }, "input": { "authenticated": true } },
        { "digit": "2", "action": { "say": { "text": "You chose not to authenticate. Goodbye." } }, "input": { "authenticated": false } }
      ]
    }
  }'

await fetch("https://api.wave.sa/v1/callflows", {
  method: "POST",
  headers: {
    Authorization: "Bearer sk_sandbox_xxxxxxxxxxxx",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "auth-ivr",
    activate: true,
    definition: {
      prompt: { say: { text: "To authenticate press 1, to decline press 2" } },
      branches: [
        { digit: "1", action: { say: { text: "You are authenticated. Goodbye." } }, input: { authenticated: true } },
        { digit: "2", action: { say: { text: "You chose not to authenticate. Goodbye." } }, input: { authenticated: false } },
      ],
    },
  }),
});

الحقل	النوع	إلزاميّ	ملاحظات
`name`	نصّ	نعم	`A–Z a–z 0–9 _ -` والمسافات، ≤100 محرف. فريد لكلّ مؤسسة — مفتاح التوجيه.
`definition`	كائن	نعم	تعريف القائمة (أعلاه).
`activate`	منطقيّ	لا	`true` يجعل هذا الإصدار مباشرًا عند الإنشاء. الافتراضيّ `false`.

يُعيد 201 Created القائمة، متضمّنةً سجلّ إصداراتها:

{
  "name": "auth-ivr",
  "version": 1,
  "is_active": true,
  "definition": { "kind": "menu", "gather": { "…": "…" }, "branches": { "…": "…" } },
  "created_at": "2026-08-28T10:00:00.000Z",
  "updated_at": "2026-08-28T10:00:00.000Z",
  "versions": [ { "version": 1, "is_active": true, "created_at": "2026-08-28T10:00:00.000Z" } ]
}

الاسم المكرّر يُعيد 409 — استخدم PUT لإضافة إصدار بدلاً من ذلك.

سرد القوائم وجلبها

يسرد GET /v1/callflows صفًّا واحدًا لكلّ قائمة (إصدارها النشط أو الأحدث):

{
  "data": [
    { "name": "auth-ivr", "version": 2, "is_active": true, "updated_at": "2026-08-28T11:00:00.000Z" }
  ]
}

يُعيد GET /v1/callflows/{name} القائمة كاملةً — definition الإصدار النشط (أو الأحدث) مع سجلّ versions الكامل. 404 إن لم تكن القائمة موجودة.

الإصدارات والاسترجاع

القوائم غير قابلة للتغيير وتُضاف فقط. التعديل لا يغيّر إصدارًا في مكانه أبدًا — بل يُضيف إصدارًا جديدًا.

PUT /v1/callflows/{name} بتعريف definition جديد (وactivate اختياريّ) يُضيف الإصدار التالي. 404 إن لم تكن القائمة موجودة.
POST /v1/callflows/{name}/activate بـ { "version": N } يجعل الإصدار N مباشرًا — الاسترجاع هو ببساطة تفعيل إصدار أقدم. 404 إن لم يكن ذلك الإصدار موجودًا.

# الاسترجاع إلى الإصدار 1
curl -X POST https://api.wave.sa/v1/callflows/auth-ivr/activate \
  -H "Authorization: Bearer sk_sandbox_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "version": 1 }'

await fetch("https://api.wave.sa/v1/callflows/auth-ivr/activate", {
  method: "POST",
  headers: {
    Authorization: "Bearer sk_sandbox_xxxxxxxxxxxx",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ version: 1 }),
});

يُعيد كلاهما كائن القائمة بالإصدار المُفعَّل حديثًا.

ربط رقم

POST /v1/callflows/{name}/bind-number يوجّه أحد أرقام Wave لديك إلى الإصدار النشط للقائمة — عندها تُنفّذ المكالمات الواردة إلى ذلك الرقم القائمة.

cURL

curl -X POST https://api.wave.sa/v1/callflows/auth-ivr/bind-number \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "phone_number_id": "f933e0c3-45a9-4b25-b469-624745a3f8ef" }'

الحقل	النوع	إلزاميّ	ملاحظات
`phone_number_id`	uuid	نعم	رقم تملكه مؤسستك. `404` إن لم يكن لك؛ `409` إن لم يكن للقائمة إصدار نشط.

يُعيد { "bound": true }. الأرقام تُوفّرها Wave — راجع الأرقام الافتراضيّة.

إيقاف قائمة

DELETE /v1/callflows/{name} يوقف القائمة إيقافًا ناعمًا: تتوقّف عن خدمة المتّصلين ويُلغى ربط أيّ رقم، لكن يُحفَظ سجلّ الإصدارات (يمكنك إعادة إنشائها لاحقًا). يُعيد { "retired": true }؛ و404 إن لم تكن القائمة موجودة.

webhook باسم `call.input`

حين يضغط المتّصل رقمًا، تُرسل Wave webhook باسم call.input. تحمل data الأرقام المضغوطة digits إضافةً إلى كائن input لذلك الفرع — فيعرف نظامك الخلفيّ بالضبط ما اختاره المتّصل:

{
  "event": "call.input",
  "data": { "call_id": "…", "digits": "1", "authenticated": true }
}

سجّل نقطة نهاية وتحقّق من التوقيع كما هو موضّح في Webhooks.

المقاطع الصوتيّة

تُشغّل تحية أو إجراء play ملفًّا مسجّلًا بدلاً من TTS — مناسب لتحية مُنتَجة، ويتجاوز تأخّر التركيب الصوتيّ. ارفع الملفّ أوّلًا، ثم أشِر إلى audio_ref المُعاد. POST /v1/callflows/audio يأخذ ملفّ WAV مُرمَّزًا بـ base64 (يُوصى بـ 8 kHz أحاديّ 16-bit PCM — جودة الهاتف) ويُعيد audio_ref مُستضافًا لدى Wave:

cURL

curl -X POST https://api.wave.sa/v1/callflows/audio \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "base64": "<base64-wav>", "content_type": "audio/wav", "file_name": "welcome.wav" }'

{ "audio_ref": "https://<bucket>.<region>.aliyuncs.com/prompts/<org>/<id>.wav" }

استخدم audio_ref في play:

{ "prompt": { "play": { "audio_ref": "https://…/prompts/<org>/<id>.wav" } } }

رفع الملفّات الصوتيّة قيد الإطلاق. حتّى تفعيله لحسابك، يُعيد الرفع 503 وتستخدم القوائم تحيات say (TTS). يجب أن يكون audio_ref ملفًّا رفعته أنت — تُرفض الروابط العشوائيّة.

الخطوات التالية

WaveML — الأوامر التي تُترجَم إليها القائمة، والمسارات المخصّصة الكاملة.
Webhooks — استقبال call.input والتحقّق منه.
الطوابير — حيث يُرسل فرع enqueue المتّصل.

البدء

الصوت

Web Callback

واتساب

المرجع

قوائم الرد الصوتي (IVR)

المصادقة والطبقات

تعريف القائمة

التحية والإجراءات

مُدخل الفرع (حمولة webhook خاصّتك)

إنشاء قائمة

سرد القوائم وجلبها

الإصدارات والاسترجاع

ربط رقم

إيقاف قائمة

webhook باسم `call.input`

المقاطع الصوتيّة

الخطوات التالية

​المصادقة والطبقات

​تعريف القائمة

​التحية والإجراءات

​مُدخل الفرع (حمولة webhook خاصّتك)

​إنشاء قائمة

​سرد القوائم وجلبها

​الإصدارات والاسترجاع

​ربط رقم

​إيقاف قائمة

​webhook باسم call.input

​المقاطع الصوتيّة

​الخطوات التالية

المصادقة والطبقات

تعريف القائمة

التحية والإجراءات

مُدخل الفرع (حمولة webhook خاصّتك)

إنشاء قائمة

سرد القوائم وجلبها

الإصدارات والاسترجاع

ربط رقم

إيقاف قائمة

webhook باسم `call.input`

المقاطع الصوتيّة

الخطوات التالية