> ## 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.

# Zoho Desk: راسل العملاء عند إغلاق التذكرة

> أطلق قالب واتساب من قاعدة سير عمل في Zoho Desk، دون أي شيفرة من جانبك.

عندما يغلق موظف تذكرة في Zoho Desk، أرسل للعميل تأكيدًا على واتساب. فـ Zoho يدفع إلينا — وأنت لا
تستطلع.

ويعمل هذا **دون كتابة أي شيفرة**، بشرط أن يكون رقم جهة الاتصال مخزنًا بصيغة نستطيع استخدامها.
اقرأ [قسم رقم الهاتف](#the-phone-number-is-the-hard-part) قبل أن تبدأ؛ فهناك تفشل هذه التكاملات
فعلًا.

## ما تحتاجه أولًا

<Steps>
  <Step title="مفتاح API نطاقه الإرسال">
    **الإعدادات ← مفاتيح API**، بنطاق `conversations:send`. ولا شيء غير ذلك — فهذا المفتاح سيعيش
    في إعدادات Zoho حيث يستطيع أي مسؤول Zoho قراءته. راجع [المصادقة](/ar/authentication).
  </Step>

  <Step title="معرّف قناتك">
    من [`GET /v1/connect/channels`](/api-reference/channels/list-your-connected-channels). ستلصقه
    في webhook الخاص بـ Zoho كقيمة حرفية.
  </Step>

  <Step title="قالب معتمد">
    من [`GET /v1/templates`](/api-reference/templates/list-approved-templates-for-a-channel). دوّن
    اسمه `name` بدقة، ولغته `language`، وكم عنصرًا نائبًا `{{n}}` في نصه.
  </Step>
</Steps>

## اضبط webhook في Zoho

في Zoho Desk: **Setup → Automation → Webhooks → Create Webhook**.

| الحقل     | القيمة                                                                                     |
| --------- | ------------------------------------------------------------------------------------------ |
| الرابط    | `https://social.linkiasoft.com/api/v1/conversations/send`                                  |
| الطريقة   | `POST`                                                                                     |
| الترويسات | `x-api-key: <مفتاحك>`، `X-Tenant-Id: <معرّف مساحة عملك>`، `Content-Type: application/json` |

ثم أضف معاملات الجسم:

| المعامل            | القيمة                                          |
| ------------------ | ----------------------------------------------- |
| `channelId`        | معرّف قناتك (قيمة حرفية)                        |
| `to`               | `${Contact.Mobile}`                             |
| `contactName`      | `${Contact.First Name}`                         |
| `templateName`     | اسم قالبك (قيمة حرفية)                          |
| `templateLanguage` | `ar` (أو اللغة التي اعتُمد بها)                 |
| `templateParams`   | `${Contact.First Name},${Ticket.Ticket Number}` |

<Note>
  هذه حقول **مسطّحة**، لا كائن `template` المتداخل الظاهر في مواضع أخرى من هذا التوثيق. فباني
  webhook في Zoho لا يستطيع إخراج غير أزواج مفتاح/قيمة مسطّحة، لذا تقبل
  `/v1/conversations/send` الحقول `templateName` و`templateLanguage` و`templateParams` في المستوى
  الأعلى كصيغة مكافئة. راجع [نقطة نهاية الإرسال](/api-reference/conversations/send-a-message)
  للصيغتين.

  كما يقبل `templateParams` نص مصفوفة JSON — `["Ahmed","4821"]`. استخدم هذه الصيغة حين قد تحتوي
  القيمة على فاصلة، مثل موضوع تذكرة أو عنوان.
</Note>

## أطلقه عند الإغلاق

**Setup → Automation → Workflows → Create Rule**

* **الوحدة** — `Tickets`
* **التنفيذ عند** — `Edit`، مقصورًا على حقل `Status`
* **المعيار** — `Status is Closed` (أضف `Resolved` أيضًا إن كان فريقك يستخدم الاثنين)
* **الإجراء** — الـ webhook الذي أنشأته للتو

<Warning>
  قواعد سير العمل **لكل قسم**. فإذا كان الفريق يعمل بعدة أقسام، فيجب أن توجد القاعدة في كل قسم، وإلا
  فالتذاكر المغلقة في غيره لن ترسل شيئًا بصمت.
</Warning>

<h2 id="the-phone-number-is-the-hard-part">
  رقم الهاتف هو الجزء الصعب
</h2>

يجب أن يكون `to` بصيغة **E.164 بدون `+`** — `201001234567`. أما Zoho فيخزّن ما كتبه الموظف، وهو
عمليًا يعني كل هذه الصيغ للشخص نفسه:

```
01001234567
0100 123 4567
+20 100 123 4567
(+20) 1001234567
```

والثالثة وحدها قريبة من الصالحة. والرقم بالصيغة المحلية **لا يُرفض** — بل يُقبل الإرسال ولا يصل
أبدًا، وهو أسوأ نمط فشل ممكن.

وثلاث طرق للتعامل معه، الأفضل أولًا:

<AccordionGroup>
  <Accordion title="أضف حقل «رقم واتساب» مع تحقق (موصى به)">
    أضف حقلًا مخصصًا في تخطيط التذكرة أو جهة الاتصال — `WhatsApp Number` — مع قاعدة تحقق تشترط
    صيغة E.164، واجعله إلزاميًا قبل إغلاق التذكرة. ثم استخدم `${Ticket.WhatsApp Number}` في `to`.

    وهذا الخيار الوحيد الذي يعالج المشكلة من مصدرها بدل التخمين، ويلغي فئة كاملة من تذاكر «لماذا لم
    تصل الرسالة إلى العميل».
  </Accordion>

  <Accordion title="طبّع الرقم في دالة Deluge مخصصة">
    استبدل الـ webhook البسيط بدالة مخصصة على قاعدة سير العمل نفسها، ونظّف الرقم قبل الإرسال:

    ```javascript theme={null}
    phone = contact.get("mobile").replaceAll(" ","").replaceAll("-","");
    if (phone.startsWith("00")) { phone = phone.removeFirstOccurence("00"); }
    else if (phone.startsWith("0")) { phone = "20" + phone.removeFirstOccurence("0"); }

    payload = Map();
    payload.put("channelId", "<your-channel-uuid>");
    payload.put("to", phone);
    payload.put("templateName", "ticket_resolved");
    payload.put("templateLanguage", "ar");
    payload.put("templateParams", ticket.get("ticketNumber"));

    response = invokeurl [ url: "https://social.linkiasoft.com/api/v1/conversations/send"
                           type: POST
                           parameters: payload.toString()
                           headers: {"Content-Type":"application/json", "x-api-key":"...", "X-Tenant-Id":"..."} ];
    ```

    وتثبيت `20` يفترض أن كل عميل في بلد واحد. فإن لم يكن ذلك صحيحًا، فهذا الأسلوب سيفسد الاستثناءات.
  </Accordion>

  <Accordion title="ارجع إلى عدة حقول بالتتابع">
    أرسل `${Contact.Mobile}` وارجع إلى `${Contact.Phone}` أو `${Ticket.Phone}` عند خلوه. وهذا
    يساعد فقط مع الأرقام *المفقودة* لا سيئة الصياغة — فمشكلة الصياغة تبقى.
  </Accordion>
</AccordionGroup>

## أمران تراقبهما في الإنتاج

**الإرسال المكرر.** يمكن إغلاق التذكرة وإعادة فتحها وإغلاقها مجددًا — وكل إغلاق يُطلق القاعدة. كما
يعيد Zoho المحاولة عند استجابة غير 2xx. فإذا كانت الرسالة المكررة تهم، أضف حقل خانة اختيار مخصصًا
مثل `Confirmation Sent`، وضمّن `Confirmation Sent is false` في معايير القاعدة، واضبطه كإجراء ثانٍ
في سير العمل.

**الإخفاقات الصامتة.** يسجّل Zoho إخفاقات webhook في سجله الخاص الذي لا يقرأه أحد. وواجهتنا تعيد
`202` بمجرد دخول الرسالة الطابور، فـ`202` لا تعني التسليم — افحص `status` على الرسالة إن كان تأكيد
التسليم يهم. راجع [الخطوة 4 من البداية السريعة](/ar/quickstart).

## اختباره

أغلق تذكرة حقيقية لجهة اتصال رقمها رقمك أنت. فإن لم يصل شيء، تحقق بهذا الترتيب:

1. **سجل webhook في Zoho** — هل عملت القاعدة أصلًا؟ إن لم تعمل، فالمعايير أو القسم خاطئ.
2. **رمز الاستجابة** — `401` تعني أن المفتاح أو الترويسات خاطئة، و`403` تعني أن المفتاح يفتقر إلى
   `conversations:send`، و`400` تعني أن الحمولة غير صالحة وحقل `message` يوضح كيف.
3. **حقل `status` في الرسالة** — `202` متبوعة بـ`failed` تعني أننا قبلناها ورفضتها المنصة.
   و`error_reason` سيوضح السبب؛ والأسباب المعتادة رقم سيئ الصياغة أو قالب لا يطابق عدد معاملاته.