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

# أرسل أول رسالة

> من مفتاح API جديد إلى قالب واتساب مُسلَّم في أربعة استدعاءات.

يشرح هذا المسار كاملًا: العثور على قناة، واختيار قالب، وإرساله، وتأكيد وصوله. وكل استدعاء يستخدم
الترويستين من [المصادقة](/ar/authentication).

<Steps>
  <Step title="اعثر على القناة التي سترسل منها">
    `channelId` يحدد الحساب المربوط الذي تخرج منه الرسالة. احصل عليه مرة وخزّنه — فهو لا يتغير.

    ```bash theme={null}
    curl https://social.linkiasoft.com/api/v1/connect/channels \
      -H "x-api-key: $LINKIA_API_KEY" \
      -H "X-Tenant-Id: $LINKIA_TENANT_ID"
    ```

    ```json theme={null}
    {
      "channels": [
        {
          "id": "3f2b1a9c-0d4e-4a7b-9c1e-8f6a2b3c4d5e",
          "type": "whatsapp",
          "display_name": "Support",
          "phone_number": "201001234567",
          "connection_status": "connected"
        }
      ]
    }
    ```

    استخدم قناة حالتها `connection_status` هي `connected`. فأي حالة أخرى لا تستطيع الإرسال.
  </Step>

  <Step title="اختر قالبًا معتمدًا">
    ```bash theme={null}
    curl "https://social.linkiasoft.com/api/v1/templates?channelId=$CHANNEL_ID" \
      -H "x-api-key: $LINKIA_API_KEY" \
      -H "X-Tenant-Id: $LINKIA_TENANT_ID"
    ```

    ```json theme={null}
    {
      "templates": [
        {
          "name": "ticket_resolved",
          "language": "ar",
          "status": "APPROVED",
          "category": "UTILITY",
          "components": [
            { "type": "BODY", "text": "مرحباً {{1}}، تم حل تذكرتك رقم {{2}}." }
          ]
        }
      ]
    }
    ```

    أمران تقرأهما من هذا:

    * **يجب أن تكون `status` هي `APPROVED`.** فالقالب `PENDING` يُرفض عند الإرسال.
    * **عُدّ العناصر النائبة في نص `BODY`.** فوجود `{{1}}` و`{{2}}` يعني أن عليك تمرير `templateParams`
      اثنين بالضبط وبهذا الترتيب. وأي عدم تطابق يُفشل الإرسال.
  </Step>

  <Step title="أرسله">
    ```bash theme={null}
    curl -X POST https://social.linkiasoft.com/api/v1/conversations/send \
      -H "x-api-key: $LINKIA_API_KEY" \
      -H "X-Tenant-Id: $LINKIA_TENANT_ID" \
      -H "Content-Type: application/json" \
      -d '{
        "channelId": "3f2b1a9c-0d4e-4a7b-9c1e-8f6a2b3c4d5e",
        "to": "201001234567",
        "contactName": "Ahmed Hassan",
        "template": {
          "templateName": "ticket_resolved",
          "templateLanguage": "ar",
          "templateParams": ["Ahmed", "4821"]
        }
      }'
    ```

    ستحصل على `202 Accepted` والرسالة المنشأة:

    ```json theme={null}
    {
      "id": "9a8b7c6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d",
      "conversation_id": "7c8d9e0f-1a2b-3c4d-5e6f-7a8b9c0d1e2f",
      "direction": "outbound",
      "type": "template",
      "status": "sent",
      "created_at": "2026-07-24T21:14:07.221Z"
    }
    ```

    <Warning>
      يجب أن يكون `to` بصيغة **E.164 بدون `+`** — `201001234567`. أما الرقم بالصيغة المحلية مثل
      `01001234567` فلا يُرفض؛ بل ببساطة لا يُسلَّم. طبّع الأرقام قبل الإرسال.
    </Warning>

    ولم تكن بحاجة إلى وجود محادثة مسبقًا: فـ`channelId` مع `to` يجد المحادثة أو يبدأ واحدة. وإن كان
    لديك `conversationId` بالفعل، فأرسله بدلًا منهما واحذفهما.
  </Step>

  <Step title="تأكد من وصولها">
    `202` تعني في الطابور لا مُسلَّمة. اقرأ الرسالة مجددًا لترى إلى أين وصلت:

    ```bash theme={null}
    curl "https://social.linkiasoft.com/api/v1/conversations/$CONVERSATION_ID/messages?limit=1" \
      -H "x-api-key: $LINKIA_API_KEY" \
      -H "X-Tenant-Id: $LINKIA_TENANT_ID"
    ```

    | `status`    | المعنى                                                 |
    | ----------- | ------------------------------------------------------ |
    | `pending`   | في الطابور، ولم تُسلَّم إلى المنصة بعد                 |
    | `sent`      | قبلتها المنصة                                          |
    | `delivered` | وصلت إلى جهاز العميل                                   |
    | `read`      | فُتحت — فقط إذا كانت إيصالات القراءة مفعّلة لدى العميل |
    | `failed`    | نهائية. و`error_reason` يوضح السبب.                    |

    استطلع لفترة قصيرة، أو اعتبر `sent` نجاحًا وعالج `failed` منفصلة. ولا تنتظر `read` — فكثير من
    العملاء يعطّلون إيصالات القراءة ولن تصل أبدًا.
  </Step>
</Steps>

## إرسال نص عادي

داخل نافذة الـ 24 ساعة — أي أن العميل راسلك مؤخرًا — يمكنك الرد بنص حر:

```json theme={null}
{
  "conversationId": "7c8d9e0f-1a2b-3c4d-5e6f-7a8b9c0d1e2f",
  "text": "Thanks — that's all sorted."
}
```

وخارج تلك النافذة يرفض واتساب ذلك. فإذا كان تكاملك يبدأ التواصل، أرسل قالبًا.

## التالي

<Card title="Zoho Desk: مراسلة العملاء عند إغلاق التذكرة" icon="ticket" href="/ar/guides/zoho-ticket-closed">
  تكامل كامل مشروح، بما في ذلك صيغة الحمولة المسطّحة للمستدعين الذين لا يستطيعون إرسال JSON متداخل.
</Card>