# القوالب

> اعرض قوالب رسائل واتساب المعتمدة وأرسلها

- الصفحة: https://tbit.app/ar/docs/api/templates
- عنوان URL الأساسي: `https://rest-api.tbit.app/v1`
- المصادقة: ترويسة `X-API-Key` تحمل مفتاحك في كل طلب (تقرأه الأمثلة من متغير البيئة `TBIT_API_KEY`)

## نظرة عامة

القوالب صيغ رسائل واتساب معتمدة مسبقًا، وهي مطلوبة لبدء محادثات خارج نافذة المراسلة البالغة 24 ساعة. لا يمكن إرسال إلا القوالب التي اعتمدتها Meta.

## نقاط النهاية

| الطريقة | المسار | الوصف |
| --- | --- | --- |
| `GET` | `/v1/templates` | عرض قوالب واتساب المعتمدة |
| `GET` | `/v1/templates/:id` | جلب تفاصيل قالب |
| `POST` | `/v1/templates/:id/send` | إرسال قالب إلى جهة اتصال |
| `GET` | `/v1/channels/:channel_id/templates` | القوالب المعتمدة لخط واتساب واحد |
| `GET` | `/v1/campaigns/:key/executions` | حالة التسليم لكل مستلم (الإرسالات التي تمت بمفتاح حملة) |

## عرض القوالب

`GET /v1/templates`

```bash
curl "https://rest-api.tbit.app/v1/templates" \
  -H "X-API-Key: $TBIT_API_KEY"
```

## جلب تفاصيل قالب

`GET /v1/templates/tpl_abc123`

```bash
curl "https://rest-api.tbit.app/v1/templates/tpl_abc123" \
  -H "X-API-Key: $TBIT_API_KEY"
```

## القوالب حسب خط واتساب

يُعتمد القالب في حساب WhatsApp Business واحد فقط، لذا فالوكيل الذي يملك عدة خطوط لديه مجموعة قوالب لكل خط. يجمع GET /v1/templates كل الخطوط معًا (يحمل كل عنصر قيمة channel_id الخاصة به)؛ استخدم نقطة النهاية هذه لعرض ما يستطيع خط واحد إرساله فقط. معرّف القناة هو الظاهر في المنصة ← القنوات.

`GET /v1/channels/6a7268abec6ecaf999a6c0ba/templates`

```bash
curl "https://rest-api.tbit.app/v1/channels/6a7268abec6ecaf999a6c0ba/templates" \
  -H "X-API-Key: $TBIT_API_KEY"
```

## إرسال قالب

ملاحظة حول الإرسال

تتبع مصفوفة المكوّنات صيغة WhatsApp Business API. أضف مكوّنات الترويسة والنص والأزرار حسب ما يتطلبه قالبك.

`POST /v1/templates/tpl_abc123/send`

```bash
curl -X POST "https://rest-api.tbit.app/v1/templates/tpl_abc123/send" \
  -H "X-API-Key: $TBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "573001234567",
    "components": [
      {
        "type": "body",
        "parameters": [
          {
            "type": "text",
            "text": "John"
          },
          {
            "type": "text",
            "text": "your order #1234"
          }
        ]
      }
    ]
  }'
```

## حالة التسليم

استجابة الإرسال تعني فقط أن Meta قَبِلت الرسالة؛ أما حالات التسليم والقراءة والفشل فتصل بعد دقائق عبر webhooks من Meta. لقراءتها، مرّر `campaign` {key, name} في body الإرسال (يُسجَّل الإرسال تحت هذا المفتاح، ويظهر أيضًا في المنصة ← الحملات) ثم استعلم من نقطة النهاية هذه. قيمة `status` هي sent أو delivered أو read أو failed؛ و`message_id` هو الـ wamid الذي يُرجعه الإرسال (ويأتي أيضًا في استجابة الإرسال).

`GET /v1/campaigns/my-app/executions`

```bash
curl "https://rest-api.tbit.app/v1/campaigns/my-app/executions?since=2026-08-27T00:00:00Z&limit=100" \
  -H "X-API-Key: $TBIT_API_KEY"
```

الاستجابة:

```json
{
  "data": [
    {
      "id": "6a90ea1f...",
      "to": "573001234567",
      "template_id": "tpl_abc123",
      "message_id": "wamid.HBgLNTcz...",
      "status": "failed",
      "error_message": "This message was not delivered to maintain healthy ecosystem engagement.",
      "sent_at": "2026-08-28T02:17:59.494Z",
      "delivered_at": null,
      "read_at": null
    }
  ]
}
```

## صيغة الاستجابة

كائن قالب:

```json
{
  "data": [
    {
      "id": "tpl_abc123",
      "name": "order_confirmation",
      "language": "es",
      "status": "APPROVED",
      "category": "UTILITY",
      "channel_id": "6a7268abec6ecaf999a6c0ba",
      "components": [
        {
          "type": "BODY",
          "text": "Hola {{1}}, {{2}} ha sido confirmado."
        }
      ],
      "created_at": "2024-08-15T10:00:00Z"
    }
  ]
}
```

## استجابة الإرسال

يُرجع الإرسال الناجح معرّف الرسالة:

```json
{
  "data": {
    "message_sent": true,
    "message_id": "wamid.HBgLNTczMDAxMjM0NTY3FQIAERgSMUY2RUZGM0Y3RTJCRTQ5AA==",
    "parsed_message": "Hola John, your order #1234 ha sido confirmado."
  }
}
```