البريد الصوتي

يحوّل البريد الصوتي المكالمة الواردة غير المُجابة إلى رسالة. فعّل البريد الصوتي على رقم Wave، وعندما تنتهي مكالمة إليه دون ردّ، يشغّل Wave رسالة ترحيب، ويسجّل المتّصل، ويحفظ التسجيل بريدًا صوتيًّا يمكنك عرضه وتشغيله ووسمه كمسموع وحذفه.

يُطرح البريد الصوتي خلف مفتاح تفعيل لكلّ بيئة. وإلى أن يُفعَّل لحسابك تُعيد كلّ نقطة نهاية 503 VOICEMAIL_DISABLED.

يعمل البريد الصوتي فقط على رقم لا ترتبط به قائمة (أحاديّة المستوى أو متعدّدة المستويات). عندما ترتبط قائمة أو قائمة متعدّدة المستويات بالرقم، لا تصل المكالمة التي لا يردّ عليها أحد إلى البريد الصوتي.

تفعيل رقم

تُفعّل PUT /v1/numbers/{id}/voicemail البريد الصوتي أو تعطّله لأحد أرقام Wave لديك. تتطلّب نطاق voicemail:write.

curl -X PUT https://api.wave.sa/v1/numbers/27d6dd39-…/voicemail \
  -H "Authorization: Bearer $WAVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "voicemail_enabled": true }'

const res = await fetch("https://api.wave.sa/v1/numbers/27d6dd39-…/voicemail", {
  method: "PUT",
  headers: {
    Authorization: `Bearer ${process.env.WAVE_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    voicemail_enabled: true,
  }),
});
console.log(await res.json());

import os

import requests

res = requests.put(
    "https://api.wave.sa/v1/numbers/27d6dd39-…/voicemail",
    headers={
        "Authorization": f"Bearer {os.environ['WAVE_API_KEY']}",
    },
    json={
        "voicemail_enabled": True,
    },
)
print(res.json())

{
  "id": "27d6dd39-…",
  "number": "+966590007001",
  "voicemail_enabled": true,
  "greeting_ref": null
}

رسالة ترحيب مخصّصة

يشغّل Wave افتراضيًّا رسالة ترحيب قياسيّة. ولتشغيل رسالتك الخاصّة، ارفع أولًا ملف WAV عبر POST /v1/callflows/audio — يُعيد ذلك audio_ref — ثم عيّنه بوصفه greeting_ref:

curl -X PUT https://api.wave.sa/v1/numbers/27d6dd39-…/voicemail \
  -H "Authorization: Bearer $WAVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "voicemail_enabled": true, "greeting_ref": "https://…/prompts/…wav" }'

const res = await fetch("https://api.wave.sa/v1/numbers/27d6dd39-…/voicemail", {
  method: "PUT",
  headers: {
    Authorization: `Bearer ${process.env.WAVE_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    voicemail_enabled: true,
    greeting_ref: "https://…/prompts/…wav",
  }),
});
console.log(await res.json());

import os

import requests

res = requests.put(
    "https://api.wave.sa/v1/numbers/27d6dd39-…/voicemail",
    headers={
        "Authorization": f"Bearer {os.environ['WAVE_API_KEY']}",
    },
    json={
        "voicemail_enabled": True,
        "greeting_ref": "https://…/prompts/…wav",
    },
)
print(res.json())

يجب أن يكون greeting_ref ملفًّا رفعته مؤسّستك — وأيّ رابط عشوائيّ يُعيد 400 VOICEMAIL_GREETING_INVALID. أرسل null لمسحه والعودة إلى الرسالة الافتراضيّة؛ واحذف المفتاح لإبقاء الرسالة الحاليّة دون تغيير.

عرض الصندوق

تُعيد GET /v1/voicemails رسائلك من الأحدث إلى الأقدم مع ترقيم بالمؤشّر. تتطلّب نطاق voicemail:read. يأتي البريد الصوتي من المكالمات الواردة، لذا ينتمي إلى بيئة الـ production. لا يرى الـ sandbox key أيّ رسالة: القائمة فارغة، ومعرّف الرسالة يُعيد 404 (القراءة، والوسم كمسموع، والحذف).

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

const res = await fetch("https://api.wave.sa/v1/voicemails?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/voicemails?limit=20",
    headers={
        "Authorization": f"Bearer {os.environ['WAVE_API_KEY']}",
    },
)
print(res.json())

{
  "data": [
    {
      "id": "9f2a…",
      "call_id": "27d6dd39-…",
      "number": "+966590007001",
      "from": "+966500000000",
      "duration_seconds": null,
      "recording_available": true,
      "transcription_status": "pending",
      "transcription_text": null,
      "listened_at": null,
      "created_at": "2026-09-07T10:00:00.000Z"
    }
  ],
  "next_cursor": "eyJ…",
  "limit": 20
}

مرّر next_cursor مجدّدًا بوصفه ?cursor= للتنقّل بين الصفحات. وضيّق القائمة بـ ?number= (صندوق رقم واحد) و?listened=true|false (المسموع مقابل الجديد). واجلب رسالة واحدة عبر GET /v1/voicemails/{id}.

حقلان محجوزان لإضافات لاحقة: قيمة transcription_status هي pending حاليًّا (يأتي النسخ النصّيّ التلقائيّ لاحقًا، ويبقى transcription_text بقيمة null إلى ذلك الحين)، وتبقى duration_seconds بقيمة null إلى أن يُبلّغ محرّك الاتّصالات بطول الرسالة.

تشغيل رسالة

تُعيد GET /v1/voicemails/{id}/recording-url رابط تشغيل محدود المدّة (صالح نحو ٦٠ دقيقة). تتطلّب نطاق voicemail:read ومفتاح production.

curl https://api.wave.sa/v1/voicemails/9f2a…/recording-url \
  -H "Authorization: Bearer $WAVE_API_KEY"

const res = await fetch("https://api.wave.sa/v1/voicemails/9f2a…/recording-url", {
  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/voicemails/9f2a…/recording-url",
    headers={
        "Authorization": f"Bearer {os.environ['WAVE_API_KEY']}",
    },
)
print(res.json())

{
  "voicemail_id": "9f2a…",
  "url": "https://oss.example.com/…?signature=…",
  "expires_in_seconds": 3600
}

لا يكون للرسالة صوت إلّا بعد التقاط التسجيل و تهيئة التخزين؛ وإلى ذلك الحين تُعيد هذه النقطة 404 VOICEMAIL_RECORDING_NOT_FOUND أو 503 VOICEMAIL_SERVICE_UNAVAILABLE. وتحصل مفاتيح sandbox على 400 SANDBOX_KEY_NOT_ALLOWED.

الوسم كمسموع، والحذف

تَسِم POST /v1/voicemails/{id}/listened الرسالة كمسموعة (في المرّة الأولى فقط، كي تبقى لحظة «أوّل استماع» ثابتة). وتحذف DELETE /v1/voicemails/{id} الرسالة حذفًا ناعمًا وتمسح تسجيلها. وكلتاهما تتطلّبان نطاق voicemail:write.

curl -X POST https://api.wave.sa/v1/voicemails/9f2a…/listened \
  -H "Authorization: Bearer $WAVE_API_KEY"

curl -X DELETE https://api.wave.sa/v1/voicemails/9f2a… \
  -H "Authorization: Bearer $WAVE_API_KEY"

const res1 = await fetch("https://api.wave.sa/v1/voicemails/9f2a…/listened", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.WAVE_API_KEY}`,
  },
});
console.log(await res1.json());

const res2 = await fetch("https://api.wave.sa/v1/voicemails/9f2a…", {
  method: "DELETE",
  headers: {
    Authorization: `Bearer ${process.env.WAVE_API_KEY}`,
  },
});
console.log(await res2.json());

import os

import requests

res1 = requests.post(
    "https://api.wave.sa/v1/voicemails/9f2a…/listened",
    headers={
        "Authorization": f"Bearer {os.environ['WAVE_API_KEY']}",
    },
)
print(res1.json())

res2 = requests.delete(
    "https://api.wave.sa/v1/voicemails/9f2a…",
    headers={
        "Authorization": f"Bearer {os.environ['WAVE_API_KEY']}",
    },
)
print(res2.json())

تلقّي الإشعارات

بدلًا من استطلاع الصندوق، اشترك في webhook الخاصّ بـ voicemail.received — يرسله Wave بمجرّد جهوز تسجيل رسالة جديدة:

{
  "event": "voicemail.received",
  "data": {
    "voicemail_id": "9f2a…",
    "call_id": "27d6dd39-…",
    "number": "+966590007001",
    "from": "+966500000000",
    "duration_seconds": null,
    "recording_available": true,
    "transcription_status": "pending"
  }
}

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

WaveML

الوسمان <Play> و<Record> وراء تدفّق البريد الصوتي.

Webhooks

استقبل voicemail.received مدفوعًا إليك بدلًا من الاستطلاع.

البدء

الصوت

Web Callback

واتساب

المرجع

البريد الصوتي

تفعيل رقم

رسالة ترحيب مخصّصة

عرض الصندوق

تشغيل رسالة

الوسم كمسموع، والحذف

تلقّي الإشعارات

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

WaveML

Webhooks

​تفعيل رقم

​رسالة ترحيب مخصّصة

​عرض الصندوق

​تشغيل رسالة

​الوسم كمسموع، والحذف

​تلقّي الإشعارات

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

WaveML

Webhooks

تفعيل رقم

رسالة ترحيب مخصّصة

عرض الصندوق

تشغيل رسالة

الوسم كمسموع، والحذف

تلقّي الإشعارات

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