> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wave.sa/llms.txt
> Use this file to discover all available pages before exploring further.

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

> دع المتّصلين يتركون رسالة عندما لا يردّ أحد، ثم اعرض الرسائل وشغّلها وأدرها.

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

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

> [!NOTE]
>
> **يعمل البريد الصوتي فقط على رقم لا ترتبط به قائمة (أحاديّة المستوى أو متعدّدة
> المستويات).** عندما ترتبط
> [قائمة أو قائمة متعدّدة المستويات](https://docs.wave.sa/ar/voice/ivr.md) بالرقم، لا تصل المكالمة التي لا
> يردّ عليها أحد إلى البريد الصوتي.

## تفعيل رقم

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

```bash cURL theme={null}
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 }'
```

```javascript Node.js theme={null}
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());
```

```python Python theme={null}
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())
```

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

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

يشغّل Wave افتراضيًّا رسالة ترحيب قياسيّة. ولتشغيل رسالتك الخاصّة، ارفع أولًا ملف
WAV عبر [`POST /v1/callflows/audio`](https://docs.wave.sa/ar/voice/ivr) — يُعيد ذلك `audio_ref` — ثم
عيّنه بوصفه `greeting_ref`:

```bash cURL theme={null}
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" }'
```

```javascript Node.js theme={null}
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());
```

```python Python theme={null}
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` (القراءة، والوسم كمسموع، والحذف).

```bash cURL theme={null}
curl "https://api.wave.sa/v1/voicemails?limit=20" \
  -H "Authorization: Bearer $WAVE_API_KEY"
```

```javascript Node.js theme={null}
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());
```

```python Python theme={null}
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())
```

```json theme={null}
{
  "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}`.

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

## تشغيل رسالة

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

```bash cURL theme={null}
curl https://api.wave.sa/v1/voicemails/9f2a…/recording-url \
  -H "Authorization: Bearer $WAVE_API_KEY"
```

```javascript Node.js theme={null}
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());
```

```python Python theme={null}
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())
```

```json theme={null}
{
  "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`.

```bash cURL theme={null}
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"
```

```javascript Node.js theme={null}
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());
```

```python Python theme={null}
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](https://docs.wave.sa/ar/webhooks.md) الخاصّ بـ
`voicemail.received` — يرسله Wave بمجرّد جهوز تسجيل رسالة جديدة:

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

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

> [card] [WaveML](https://docs.wave.sa/ar/voice/waveml.md)
>
> الوسمان `<Play>` و`<Record>` وراء تدفّق البريد الصوتي.

> [card] [Webhooks](https://docs.wave.sa/ar/webhooks.md)
>
> استقبل `voicemail.received` مدفوعًا إليك بدلًا من الاستطلاع.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.