# المحادثات

صندوق الوارد المشترك: اقرأ المحادثات وأسندها وأغلقها وأعد فتحها.

يضم صندوق الوارد المشترك محادثة واحدة لكل عميل وقناة. عبر الواجهة البرمجية يمكنك توجيه المحادثات من أنظمتك (نظام الدعم، أو CRM، أو جدول المناوبات)، وقراءة المحادثات وإغلاقها، بينما يواصل فريقك العمل في المنصة.

## دورة حياة المحادثة {#states}

| الحالة | المعنى |
|---|---|
| `bot` | يرد تدفق أو روبوت ذكاء اصطناعي |
| `needs_agent` | تنتظر موظفًا: حوّلها الروبوت، أو طلب العميل التحدث مع شخص |
| `assigned` | أُسندت لعضو في الفريق لم يرد بعد |
| `human` | يتولاها شخص |
| `snoozed` | مؤجلة حتى `snoozed_until` |
| `resolved` | مغلقة، وتُفتح تلقائيًا إن كتب العميل من جديد |

تكون `open` بقيمة `true` في كل الحالات عدا `resolved`، ويوضح `unread` هل كتب العميل منذ آخر مرة قرأ فيها أحدٌ المحادثة.

## وجّه المحادثات إلى الشخص المناسب {#routing}

تكامل شائع: عندما تحتاج محادثة إلى موظف، اختر من يتولاها في نظامك ثم أسندها.

1. اشترك بنقطة استقبال في `conversation.needs_agent`.
2. اختر عضوًا من [`GET /members`](/docs/reference/conversations#listMembers) (لا يُسند للمشاهدين).
3. أسند المحادثة عبر [`POST /conversations/{id}/assign`](/docs/reference/conversations#assignConversation):

```json
{ "member_id": "usr_41" }
```

يجب أن يملك العضو صلاحية على رقم المحادثة أو حسابها، وإلا فالرد هو [`assignee_invalid`](/docs/errors#assignee_invalid) بدل محادثة لا يستطيع أحد فتحها.

## اقرأ المحادثة {#read}

- يبني [`GET /conversations`](/docs/reference/conversations#listConversations) مع عوامل التصفية أي طابور تريده: `open=true&assignee=none` تعني كل ما ينتظر من يتولاه، و`customer=0501234567` تجد محادثة عميل واحد.
- يُرجع [`GET /conversations/{id}/messages`](/docs/reference/conversations#listConversationMessages) الرسائل في الاتجاهين، الأحدث أولًا. لا تُضمَّن الملاحظات الداخلية بين الموظفين أبدًا.

## الرد والإغلاق {#reply}

رد عبر [`POST /messages`](/docs/reference/messages#sendMessage) بإرسال `to` إلى `customer.address` للمحادثة (ومعه `channel` لإنستغرام أو ماسنجر). يظهر الرد في المحادثة داخل المنصة كأي رد آخر.

أغلق عبر [`POST /conversations/{id}/resolve`](/docs/reference/conversations#resolveConversation)، وأعد الفتح عبر [`POST /conversations/{id}/reopen`](/docs/reference/conversations#reopenConversation) (دون إسناد، أو إلى `member_id`). يُسجَّل كل إجراء تتخذه في سجل المحادثة باسم الواجهة البرمجية مع المفتاح الذي نفذه.

## الأحداث {#events}

| الحدث | متى |
|---|---|
| `conversation.created` | بدأ عميل محادثة جديدة |
| `conversation.needs_agent` | تنتظر موظفًا |
| `conversation.assigned` | أُسندت (من شخص أو قاعدة أو عبر الواجهة) |
| `conversation.resolved` | أُغلقت |
| `conversation.reopened` | عادت محادثة مغلقة إلى النشاط |

يستمر وصول `message.received` مع كل رسالة من العميل، فتستطيع عكس المحادثة في أداتك.

:::note
محادثات البريد الإلكتروني (Gmail) غير متاحة عبر الواجهة البرمجية أبدًا، لأن سياسة Google تُبقي محتوى صندوق البريد داخل المنتج.
:::

## عرض المحادثات

```
GET https://api.saei.automize.sa/v1/conversations
```

محادثات صندوق الوارد المشترك، الأحدث أولًا، على واتساب وإنستغرام وماسنجر. استخدم عوامل التصفية لبناء طابورك: `open=true&assignee=none` تعني كل ما ينتظر من يتولاه.

- الصلاحية: conversations:read
- لمفاتيح التشغيل فقط

### المعاملات

- `limit` (query): عدد العناصر المطلوبة، من 1 إلى 100.
- `cursor` (query): قيمة `next_cursor` من الصفحة السابقة.
- `open` (query): `true` للمحادثات غير المغلقة، و`false` للمغلقة.
- `state` (query): 
- `channel` (query): 
- `assignee` (query): معرّف عضو (`usr_…`)، أو `none` لغير المُسندة.
- `customer` (query): هاتف العميل (بأي صيغة) أو معرّفه في إنستغرام أو ماسنجر.
- `unread` (query): 

### الاستجابة 200

صفحة من المحادثات.

```json
{
  "object": "list",
  "data": [
    {
      "id": "conv_311",
      "object": "conversation",
      "channel": "whatsapp",
      "customer": {
        "contact_id": "string",
        "address": "string",
        "name": "string"
      },
      "number_id": "string",
      "state": "bot",
      "open": false,
      "assignee": {
        "id": "string",
        "name": "string"
      },
      "unread": false,
      "label": "string",
      "last_customer_message_at": "2026-10-01T09:30:00Z",
      "last_agent_message_at": "2026-10-01T09:30:00Z",
      "reply_window_expires_at": "2026-10-01T09:30:00Z",
      "resolved_at": "2026-10-01T09:30:00Z",
      "snoozed_until": "2026-10-01T09:30:00Z",
      "created_at": "2026-10-01T09:30:00Z",
      "updated_at": "2026-10-01T09:30:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": "string"
}
```

### الاستجابة 401

مفتاح API مفقود أو غير صالح أو ملغى أو منتهي الصلاحية.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "api_key_invalid",
    "message": "The API key is not valid.",
    "doc_url": "https://app.example.com/docs/errors#api_key_invalid",
    "request_id": "req_01j9x3k2m4n5p6q7r8s9t0v1w2"
  }
}
```

### الاستجابة 403

المفتاح ينقصه صلاحية، أو الباقة لا تشمل الوصول للواجهة، أو الطلب غير متاح في هذا الوضع.

```json
{
  "error": {
    "type": "permission_error",
    "code": "insufficient_scope",
    "message": "This API key does not have the \"messages:send\" scope. Create a key with it in Developers > API keys.",
    "required_scope": "messages:send",
    "doc_url": "https://app.example.com/docs/errors#insufficient_scope",
    "request_id": "req_01j9x3k2m4n5p6q7r8s9t0v1w2"
  }
}
```

### الأخطاء المحتملة

`parameter_invalid`, `test_mode_unsupported`, `rate_limited`

## جلب محادثة

```
GET https://api.saei.automize.sa/v1/conversations/{id}
```



- الصلاحية: conversations:read
- لمفاتيح التشغيل فقط

### المعاملات

- `id` (path, مطلوب): معرّف العنصر.

### الاستجابة 200

المحادثة.

```json
{
  "id": "conv_311",
  "object": "conversation",
  "channel": "whatsapp",
  "customer": {
    "contact_id": "ct_1052",
    "address": "+966501234567",
    "name": "سارة القحطاني"
  },
  "number_id": "num_3",
  "state": "assigned",
  "open": true,
  "assignee": {
    "id": "usr_41",
    "name": "نورة العتيبي"
  },
  "unread": true,
  "label": "شكوى",
  "last_customer_message_at": "2026-10-01T09:29:10Z",
  "last_agent_message_at": "2026-10-01T09:20:00Z",
  "reply_window_expires_at": "2026-10-02T09:29:10Z",
  "resolved_at": null,
  "snoozed_until": null,
  "created_at": "2026-09-28T14:00:00Z",
  "updated_at": "2026-10-01T09:29:10Z"
}
```

### الاستجابة 401

مفتاح API مفقود أو غير صالح أو ملغى أو منتهي الصلاحية.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "api_key_invalid",
    "message": "The API key is not valid.",
    "doc_url": "https://app.example.com/docs/errors#api_key_invalid",
    "request_id": "req_01j9x3k2m4n5p6q7r8s9t0v1w2"
  }
}
```

### الاستجابة 403

المفتاح ينقصه صلاحية، أو الباقة لا تشمل الوصول للواجهة، أو الطلب غير متاح في هذا الوضع.

```json
{
  "error": {
    "type": "permission_error",
    "code": "insufficient_scope",
    "message": "This API key does not have the \"messages:send\" scope. Create a key with it in Developers > API keys.",
    "required_scope": "messages:send",
    "doc_url": "https://app.example.com/docs/errors#insufficient_scope",
    "request_id": "req_01j9x3k2m4n5p6q7r8s9t0v1w2"
  }
}
```

### الاستجابة 404

لا يوجد عنصر بهذا المعرّف في مساحة العمل هذه (وفي هذا الوضع).

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_missing",
    "message": "No such message: msg_999.",
    "param": "id",
    "doc_url": "https://app.example.com/docs/errors#resource_missing",
    "request_id": "req_01j9x3k2m4n5p6q7r8s9t0v1w2"
  }
}
```

### الأخطاء المحتملة

`resource_missing`, `test_mode_unsupported`, `rate_limited`

## إسناد محادثة

```
POST https://api.saei.automize.sa/v1/conversations/{id}/assign
```

يسند المحادثة إلى عضو في الفريق. يجب أن يملك صلاحية على رقمها أو حسابها، ولا يُسند للمشاهدين.

- الصلاحية: conversations:write
- لمفاتيح التشغيل فقط

### المعاملات

- `id` (path, مطلوب): معرّف العنصر.

### الطلب

```json
{
  "member_id": "usr_41"
}
```

### الاستجابة 200

المحادثة بعد الإسناد.

```json
{
  "id": "conv_311",
  "object": "conversation",
  "channel": "whatsapp",
  "customer": {
    "contact_id": "string",
    "address": "string",
    "name": "string"
  },
  "number_id": "string",
  "state": "bot",
  "open": false,
  "assignee": {
    "id": "string",
    "name": "string"
  },
  "unread": false,
  "label": "string",
  "last_customer_message_at": "2026-10-01T09:30:00Z",
  "last_agent_message_at": "2026-10-01T09:30:00Z",
  "reply_window_expires_at": "2026-10-01T09:30:00Z",
  "resolved_at": "2026-10-01T09:30:00Z",
  "snoozed_until": "2026-10-01T09:30:00Z",
  "created_at": "2026-10-01T09:30:00Z",
  "updated_at": "2026-10-01T09:30:00Z"
}
```

### الاستجابة 401

مفتاح API مفقود أو غير صالح أو ملغى أو منتهي الصلاحية.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "api_key_invalid",
    "message": "The API key is not valid.",
    "doc_url": "https://app.example.com/docs/errors#api_key_invalid",
    "request_id": "req_01j9x3k2m4n5p6q7r8s9t0v1w2"
  }
}
```

### الاستجابة 403

المفتاح ينقصه صلاحية، أو الباقة لا تشمل الوصول للواجهة، أو الطلب غير متاح في هذا الوضع.

```json
{
  "error": {
    "type": "permission_error",
    "code": "insufficient_scope",
    "message": "This API key does not have the \"messages:send\" scope. Create a key with it in Developers > API keys.",
    "required_scope": "messages:send",
    "doc_url": "https://app.example.com/docs/errors#insufficient_scope",
    "request_id": "req_01j9x3k2m4n5p6q7r8s9t0v1w2"
  }
}
```

### الاستجابة 404

لا يوجد عنصر بهذا المعرّف في مساحة العمل هذه (وفي هذا الوضع).

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_missing",
    "message": "No such message: msg_999.",
    "param": "id",
    "doc_url": "https://app.example.com/docs/errors#resource_missing",
    "request_id": "req_01j9x3k2m4n5p6q7r8s9t0v1w2"
  }
}
```

### الاستجابة 409

يجب إعادة فتح المحادثة المغلقة أولًا.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "string",
    "message": "string",
    "param": "string",
    "doc_url": "string",
    "request_id": "string",
    "details": [
      {
        "param": "string",
        "code": "string",
        "message": "string"
      }
    ],
    "channel_error": {
      "provider": "string",
      "code": 0,
      "subcode": 0,
      "title": "string",
      "message": "string"
    }
  }
}
```

### الاستجابة 422

الطلب غير صالح. يوضّح `details` كل حقل به خطأ.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_missing",
    "message": "The to field is required.",
    "param": "to",
    "details": [
      {
        "param": "to",
        "code": "parameter_missing",
        "message": "The to field is required."
      }
    ],
    "doc_url": "https://app.example.com/docs/errors#parameter_missing",
    "request_id": "req_01j9x3k2m4n5p6q7r8s9t0v1w2"
  }
}
```

### الأخطاء المحتملة

`parameter_missing`, `resource_missing`, `assignee_invalid`, `state_conflict`, `test_mode_unsupported`, `rate_limited`

## عرض رسائل محادثة

```
GET https://api.saei.automize.sa/v1/conversations/{id}/messages
```

كل رسائل المحادثة في الاتجاهين، الأحدث أولًا. لا تُضمَّن الملاحظات الداخلية بين الموظفين أبدًا.

- الصلاحية: conversations:read
- لمفاتيح التشغيل فقط

### المعاملات

- `id` (path, مطلوب): معرّف العنصر.
- `limit` (query): عدد العناصر المطلوبة، من 1 إلى 100.
- `cursor` (query): قيمة `next_cursor` من الصفحة السابقة.

### الاستجابة 200

صفحة من الرسائل.

```json
{
  "object": "list",
  "data": [
    {
      "id": "msg_48213",
      "object": "message",
      "livemode": false,
      "direction": "outbound",
      "channel": "whatsapp",
      "from": "+966112345678",
      "to": "+966501234567",
      "type": "text",
      "text": {
        "body": "string"
      },
      "template": {
        "name": "string",
        "language": "string",
        "variables": {},
        "body": "string"
      },
      "image": {},
      "video": {},
      "audio": {},
      "document": {},
      "sticker": {},
      "location": {},
      "contacts": [],
      "interactive": {},
      "reaction": {},
      "status": "accepted",
      "error": {
        "code": "string",
        "title": "string",
        "message": "string"
      },
      "reference": "string",
      "conversation_id": "string",
      "provider_message_id": "string",
      "contact": {
        "name": "string"
      },
      "context": {
        "provider_message_id": "string"
      },
      "created_at": "2026-10-01T09:30:00Z",
      "updated_at": "2026-10-01T09:30:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": "string"
}
```

### الاستجابة 401

مفتاح API مفقود أو غير صالح أو ملغى أو منتهي الصلاحية.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "api_key_invalid",
    "message": "The API key is not valid.",
    "doc_url": "https://app.example.com/docs/errors#api_key_invalid",
    "request_id": "req_01j9x3k2m4n5p6q7r8s9t0v1w2"
  }
}
```

### الاستجابة 403

المفتاح ينقصه صلاحية، أو الباقة لا تشمل الوصول للواجهة، أو الطلب غير متاح في هذا الوضع.

```json
{
  "error": {
    "type": "permission_error",
    "code": "insufficient_scope",
    "message": "This API key does not have the \"messages:send\" scope. Create a key with it in Developers > API keys.",
    "required_scope": "messages:send",
    "doc_url": "https://app.example.com/docs/errors#insufficient_scope",
    "request_id": "req_01j9x3k2m4n5p6q7r8s9t0v1w2"
  }
}
```

### الاستجابة 404

لا يوجد عنصر بهذا المعرّف في مساحة العمل هذه (وفي هذا الوضع).

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_missing",
    "message": "No such message: msg_999.",
    "param": "id",
    "doc_url": "https://app.example.com/docs/errors#resource_missing",
    "request_id": "req_01j9x3k2m4n5p6q7r8s9t0v1w2"
  }
}
```

### الأخطاء المحتملة

`resource_missing`, `test_mode_unsupported`, `rate_limited`

## إعادة فتح محادثة

```
POST https://api.saei.automize.sa/v1/conversations/{id}/reopen
```

يعيد فتح محادثة مغلقة، غير مُسندة في طابور الفريق، أو مُسندة إلى `member_id`.

- الصلاحية: conversations:write
- لمفاتيح التشغيل فقط

### المعاملات

- `id` (path, مطلوب): معرّف العنصر.

### الطلب

```json
{
  "member_id": "usr_41"
}
```

### الاستجابة 200

المحادثة بعد إعادة الفتح.

```json
{
  "id": "conv_311",
  "object": "conversation",
  "channel": "whatsapp",
  "customer": {
    "contact_id": "string",
    "address": "string",
    "name": "string"
  },
  "number_id": "string",
  "state": "bot",
  "open": false,
  "assignee": {
    "id": "string",
    "name": "string"
  },
  "unread": false,
  "label": "string",
  "last_customer_message_at": "2026-10-01T09:30:00Z",
  "last_agent_message_at": "2026-10-01T09:30:00Z",
  "reply_window_expires_at": "2026-10-01T09:30:00Z",
  "resolved_at": "2026-10-01T09:30:00Z",
  "snoozed_until": "2026-10-01T09:30:00Z",
  "created_at": "2026-10-01T09:30:00Z",
  "updated_at": "2026-10-01T09:30:00Z"
}
```

### الاستجابة 401

مفتاح API مفقود أو غير صالح أو ملغى أو منتهي الصلاحية.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "api_key_invalid",
    "message": "The API key is not valid.",
    "doc_url": "https://app.example.com/docs/errors#api_key_invalid",
    "request_id": "req_01j9x3k2m4n5p6q7r8s9t0v1w2"
  }
}
```

### الاستجابة 403

المفتاح ينقصه صلاحية، أو الباقة لا تشمل الوصول للواجهة، أو الطلب غير متاح في هذا الوضع.

```json
{
  "error": {
    "type": "permission_error",
    "code": "insufficient_scope",
    "message": "This API key does not have the \"messages:send\" scope. Create a key with it in Developers > API keys.",
    "required_scope": "messages:send",
    "doc_url": "https://app.example.com/docs/errors#insufficient_scope",
    "request_id": "req_01j9x3k2m4n5p6q7r8s9t0v1w2"
  }
}
```

### الاستجابة 404

لا يوجد عنصر بهذا المعرّف في مساحة العمل هذه (وفي هذا الوضع).

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_missing",
    "message": "No such message: msg_999.",
    "param": "id",
    "doc_url": "https://app.example.com/docs/errors#resource_missing",
    "request_id": "req_01j9x3k2m4n5p6q7r8s9t0v1w2"
  }
}
```

### الاستجابة 409

المحادثة غير مغلقة.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "string",
    "message": "string",
    "param": "string",
    "doc_url": "string",
    "request_id": "string",
    "details": [
      {
        "param": "string",
        "code": "string",
        "message": "string"
      }
    ],
    "channel_error": {
      "provider": "string",
      "code": 0,
      "subcode": 0,
      "title": "string",
      "message": "string"
    }
  }
}
```

### الاستجابة 422

الطلب غير صالح. يوضّح `details` كل حقل به خطأ.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_missing",
    "message": "The to field is required.",
    "param": "to",
    "details": [
      {
        "param": "to",
        "code": "parameter_missing",
        "message": "The to field is required."
      }
    ],
    "doc_url": "https://app.example.com/docs/errors#parameter_missing",
    "request_id": "req_01j9x3k2m4n5p6q7r8s9t0v1w2"
  }
}
```

### الأخطاء المحتملة

`resource_missing`, `state_conflict`, `test_mode_unsupported`, `rate_limited`

## إغلاق محادثة

```
POST https://api.saei.automize.sa/v1/conversations/{id}/resolve
```

يغلق المحادثة. إن كتب العميل مرة أخرى تُفتح تلقائيًا ويصلك حدث `conversation.reopened`.

- الصلاحية: conversations:write
- لمفاتيح التشغيل فقط

### المعاملات

- `id` (path, مطلوب): معرّف العنصر.

### الاستجابة 200

المحادثة بعد الإغلاق.

```json
{
  "id": "conv_311",
  "object": "conversation",
  "channel": "whatsapp",
  "customer": {
    "contact_id": "string",
    "address": "string",
    "name": "string"
  },
  "number_id": "string",
  "state": "bot",
  "open": false,
  "assignee": {
    "id": "string",
    "name": "string"
  },
  "unread": false,
  "label": "string",
  "last_customer_message_at": "2026-10-01T09:30:00Z",
  "last_agent_message_at": "2026-10-01T09:30:00Z",
  "reply_window_expires_at": "2026-10-01T09:30:00Z",
  "resolved_at": "2026-10-01T09:30:00Z",
  "snoozed_until": "2026-10-01T09:30:00Z",
  "created_at": "2026-10-01T09:30:00Z",
  "updated_at": "2026-10-01T09:30:00Z"
}
```

### الاستجابة 401

مفتاح API مفقود أو غير صالح أو ملغى أو منتهي الصلاحية.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "api_key_invalid",
    "message": "The API key is not valid.",
    "doc_url": "https://app.example.com/docs/errors#api_key_invalid",
    "request_id": "req_01j9x3k2m4n5p6q7r8s9t0v1w2"
  }
}
```

### الاستجابة 403

المفتاح ينقصه صلاحية، أو الباقة لا تشمل الوصول للواجهة، أو الطلب غير متاح في هذا الوضع.

```json
{
  "error": {
    "type": "permission_error",
    "code": "insufficient_scope",
    "message": "This API key does not have the \"messages:send\" scope. Create a key with it in Developers > API keys.",
    "required_scope": "messages:send",
    "doc_url": "https://app.example.com/docs/errors#insufficient_scope",
    "request_id": "req_01j9x3k2m4n5p6q7r8s9t0v1w2"
  }
}
```

### الاستجابة 404

لا يوجد عنصر بهذا المعرّف في مساحة العمل هذه (وفي هذا الوضع).

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_missing",
    "message": "No such message: msg_999.",
    "param": "id",
    "doc_url": "https://app.example.com/docs/errors#resource_missing",
    "request_id": "req_01j9x3k2m4n5p6q7r8s9t0v1w2"
  }
}
```

### الاستجابة 409

مغلقة بالفعل.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "string",
    "message": "string",
    "param": "string",
    "doc_url": "string",
    "request_id": "string",
    "details": [
      {
        "param": "string",
        "code": "string",
        "message": "string"
      }
    ],
    "channel_error": {
      "provider": "string",
      "code": 0,
      "subcode": 0,
      "title": "string",
      "message": "string"
    }
  }
}
```

### الأخطاء المحتملة

`resource_missing`, `state_conflict`, `test_mode_unsupported`, `rate_limited`

## عرض أعضاء الفريق

```
GET https://api.saei.automize.sa/v1/members
```

أعضاء مساحة العمل لإسناد المحادثات إليهم. المشاهدون يطّلعون على صندوق الوارد لكن لا تُسند إليهم محادثات.

- الصلاحية: conversations:read
- يعمل في وضع الاختبار

### المعاملات

- `role` (query): 

### الاستجابة 200

كل الأعضاء.

```json
{
  "object": "list",
  "data": [
    {
      "id": "usr_41",
      "object": "member",
      "name": "نورة العتيبي",
      "email": "noura@example.com",
      "role": "customer_service"
    }
  ],
  "has_more": false,
  "next_cursor": null
}
```

### الاستجابة 401

مفتاح API مفقود أو غير صالح أو ملغى أو منتهي الصلاحية.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "api_key_invalid",
    "message": "The API key is not valid.",
    "doc_url": "https://app.example.com/docs/errors#api_key_invalid",
    "request_id": "req_01j9x3k2m4n5p6q7r8s9t0v1w2"
  }
}
```

### الاستجابة 403

المفتاح ينقصه صلاحية، أو الباقة لا تشمل الوصول للواجهة، أو الطلب غير متاح في هذا الوضع.

```json
{
  "error": {
    "type": "permission_error",
    "code": "insufficient_scope",
    "message": "This API key does not have the \"messages:send\" scope. Create a key with it in Developers > API keys.",
    "required_scope": "messages:send",
    "doc_url": "https://app.example.com/docs/errors#insufficient_scope",
    "request_id": "req_01j9x3k2m4n5p6q7r8s9t0v1w2"
  }
}
```

### الأخطاء المحتملة

`parameter_invalid`, `rate_limited`