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

# إرسال قوالب WhatsApp وFlows من Customer.io

> أرسل قوالب WhatsApp المعتمدة وFlows من حملات Customer.io عبر Flowella API، وزامن رسائل WhatsApp الواردة إلى Customer.io اختياريًا.

يتصل Flowella بـ Customer.io عبر إجراءات webhook في Customer.io وFlowella REST API. تستدعي حملة Customer.io خدمة Flowella لإرسال قالب WhatsApp معتمد، بما في ذلك القوالب التي تحتوي على زر WhatsApp Flow، إلى كل شخص يصل إلى تلك الخطوة. وإذا أردت أيضًا ردود WhatsApp في Customer.io، يمكن لـ Flowella إرسال كل رسالة واردة إلى أتمتة في Customer.io تُشغَّل عبر webhook وتتحكم بها أنت.

> [!NOTE]
>
> لا يوجد تطبيق لتثبيته في Customer.io. تبني الاتجاهين بإجراءات Customer.io القياسية، لذا تحدد بدقة الطلبات التي تُنفَّذ والسمات التي تتغير.

## كيف يعمل التكامل

| الاتجاه | ما يُنفَّذ | ما يتغير |
| - | - | - |
| من Customer.io إلى Flowella | يستدعي إجراء **Send and receive data** (webhook) في حملتك `POST /v1/templates/send` للشخص الموجود في الحملة. | يضع Flowella رسالة قالب WhatsApp واحدة في قائمة الانتظار. لا يُكتب أي شيء في Customer.io. |
| من Flowella إلى Customer.io (اختياري) | يرسل webhook صادر من Flowella أحداث `message.received` إلى أتمتة في Customer.io تُشغَّل عبر webhook. | سمات الشخص التي تربطها في إجراء **Create or Update Person** الخاص بك فقط. |

لا يستدعي Flowella أبدًا Customer.io API. في الاتجاه الوارد الاختياري، يرسل Flowella الأحداث فقط إلى عنوان webhook الذي تعطيه إياه، وتقرر أتمتتك ما تفعله بها.

```mermaid theme={null}
flowchart LR
    A["Customer.io: يصل الشخص إلى إجراء webhook"] --> B["Flowella: POST /v1/templates/send"]
    B --> C["Meta: تسليم رسالة WhatsApp"]
    C --> D["جهة الاتصال ترد على WhatsApp"]
    D --> E["Flowella: webhook message.received"]
    E --> F["Customer.io: أتمتة تُشغَّل عبر webhook"]
    F --> G["Customer.io: Create or Update Person"]
```

## قبل أن تبدأ

* مؤسسة في Flowella مع رقم WhatsApp مرتبط. راجع [تسلسل الإعداد](https://knowledge.flowella.io/ar/whatsapp/accounts/setup-sequence.md).
* قالب WhatsApp معتمد في Flowella. راجع [القوالب](https://knowledge.flowella.io/ar/app/templates.md).
* دور **Owner** أو **Admin** في Flowella، لإنشاء مفتاح API، ولإنشاء webhook من أجل المزامنة الواردة. راجع [الفريق والأدوار](https://knowledge.flowella.io/ar/settings/team.md).
* مساحة عمل في Customer.io يمكنك فيها إنشاء حملات أو عمليات أتمتة تحتوي على إجراءات webhook.
* رقم WhatsApp لكل شخص محفوظ في ملفه على Customer.io بالتنسيق الدولي، مثل `+447700900123`. راجع [تنسيق رقم الهاتف](https://knowledge.flowella.io/ar/hubspot/phone-number-format.md).
* موافقة كل شخص على تلقي رسائل WhatsApp منك. تشترط Meta الحصول على الموافقة قبل مراسلة أي شخص. راجع [إرشادات الموافقة](https://developers.facebook.com/documentation/business-messaging/whatsapp/getting-opt-in) لدى Meta.

## إرسال قالب WhatsApp من Customer.io

**1. أنشئ مفتاح API في Flowella**

في Flowella، انتقل إلى **Settings**، ثم **API keys**، وأنشئ مفتاحًا مباشرًا باسم مثل `Customer.io production`. انسخه فورًا: يعرضه Flowella مرة واحدة فقط. راجع [مفاتيح API](https://knowledge.flowella.io/ar/settings/api-keys.md).

**2. اعثر على معرّفات القالب والقناة**

استدعِ `GET /v1/templates?status=APPROVED` بمفتاحك. دوّن `id` و`wabaId` الخاصين بالقالب، و`whatsappChannelId` للرقم الذي تريد الإرسال منه. راجع [القنوات المتعددة](https://knowledge.flowella.io/ar/essentials/multi-channel.md) إذا كان لديك عدة أرقام.

```bash theme={null}
curl "https://api.flowella.io/v1/templates?status=APPROVED" \
  -H "Authorization: Bearer $FLOWELLA_API_KEY"
```

**3. أضف إجراء webhook إلى حملتك**

في سير عمل حملتك على Customer.io، أضف إجراء **Send and receive data** عند النقطة التي يجب أن تُرسل فيها رسالة WhatsApp. راجع دليل Customer.io حول [إجراءات webhook](https://docs.customer.io/webhooks-action).

**4. اضبط الطلب**

اضبط الطريقة على `POST` والعنوان على `https://api.flowella.io/v1/templates/send`. أضف هذه الترويسات:

| الترويسة | القيمة |
| - | - |
| `Authorization` | `Bearer ` متبوعة بمفتاح Flowella API |
| `Content-Type` | `application/json` |

**5. اكتب جسم الطلب**

الصق هذا الجسم واستبدل المعرّفات بمعرّفاتك. غيّر `customer.phone` إلى السمة التي تحفظ رقم WhatsApp الخاص بالشخص.

```json theme={null}
{
  "templateId": "1234567890123456",
  "templateWabaId": "102290129340398",
  "whatsappChannelId": "clxxxxxxxxxxxxxxxxxxxxxxxx",
  "recipients": [
    {
      "phone": "{{customer.phone}}",
      "bodyParameters": ["{{customer.first_name}}"]
    }
  ]
}
```

يملأ `bodyParameters` متغيرات نص القالب بالترتيب: تذهب القيمة الأولى إلى `{{1}}`، والثانية إلى `{{2}}`، وهكذا. اتركه قائمة فارغة، `[]`، إذا لم يكن في نص القالب متغيرات.

**6. اختبر الإجراء**

اختر شخصًا تجريبيًا يحمل رقم WhatsApp الخاص بك واختر **Test response** في Customer.io. أضف ترويسة `Idempotency-Key` بقيمة لم تستخدمها من قبل، مثل `test-2026-11-11-01`، وغيّرها في كل اختبار. راجع [الإرسال المتكرر ومنع التكرار](#repeat-sends-and-idempotency).

تعني الاستجابة `202` مع `"status": "accepted"` أن Flowella وضع الإرسال في قائمة الانتظار. ولا تؤكد التسليم: تحقق من علامة التبويب **Statistics** الخاصة بالقالب في Flowella لمعرفة النتيجة.

**7. أزل ترويسة الاختبار وابدأ الحملة**

احذف ترويسة `Idempotency-Key` التي استخدمتها للاختبار، أو استبدلها بقيمة تختلف لكل شخص. ثم ابدأ الحملة.

### خيارات القالب التي يمكنك ضبطها لكل شخص

يقبل جسم الطلب هذه الحقول لكل مستلم. يصف كل من [مقدمة API](https://knowledge.flowella.io/ar/api-reference/introduction.md) و[مستند OpenAPI](https://api.flowella.io/v1/openapi.json) الطلب الكامل.

| الحقل | استخدمه من أجل |
| - | - |
| `phone` | رقم WhatsApp الخاص بالشخص. مطلوب. |
| `bodyParameters` | قيم متغيرات النص، بالترتيب. حتى 20 قيمة. |
| `buttonParameters` | قيم متغيرات أزرار URL (`subType` `url`)، أو أزرار Flow (`subType` `flow`)، أو أزرار نسخ الرمز (`subType` `copy_code`). |

بالنسبة إلى قالب برأس صورة أو فيديو أو مستند، يمكنك تعيين رابط ملف عام في `headerMedia.url` في المستوى الأعلى من الجسم.

### الإرسال المتكرر ومنع التكرار

يحميك `POST /v1/templates/send` من إرسال الرسالة نفسها مرتين، وهذا مهم لأن Customer.io يعيد محاولة إجراء webhook عندما لا يتلقى استجابة `2xx`:

* دون ترويسة `Idempotency-Key`، يستخدم Flowella قيمة تجزئة لجسم الطلب كمفتاح. يُرجع الجسم المطابق بايتًا ببايت خلال 7 أيام قيمة `id` الأصلية ولا يرسل شيئًا. ولأن جسم كل شخص يحتوي على رقمه الخاص، ترسل الحملة العادية إلى كل شخص مرة واحدة.
* مع ترويسة `Idempotency-Key`، يُرجع أي طلب بالمفتاح نفسه خلال 7 أيام قيمة `id` الأصلية ولا يرسل شيئًا، حتى لو تغيّر الجسم.
* بشكل منفصل، يتخطى Flowella الإرسال الثاني للقالب نفسه إلى الرقم نفسه خلال 15 ثانية.

> [!WARNING]
>
> لا تترك أبدًا قيمة `Idempotency-Key` ثابتة في إجراء حملة مباشرة. سيتلقى الشخص الأول وحده الرسالة: يعيد كل طلب لاحق استخدام المفتاح، فيُرجع Flowella قيمة `id` الأولى ولا يرسل شيئًا. أزل الترويسة قبل بدء الحملة، أو أنشئ قيمة تختلف لكل شخص، مثل اسم الحملة متبوعًا بـ `{{customer.id}}`.

تفسّر القواعد نفسها معظم الاختبارات الفاشلة. إرسال القالب نفسه إلى الشخص التجريبي نفسه مرة أخرى ينتج الجسم نفسه، لذا لا يرسل Flowella شيئًا ما لم تغيّر قيمة `Idempotency-Key` في كل مرة.

### الإرسال إلى شريحة كبيرة

يضع كل طلب من Customer.io إرسالًا واحدًا في قائمة الانتظار، ويسلّمه Flowella في الخلفية، مع إعادة المحاولة عند أخطاء WhatsApp المؤقتة. ينطبق حدّان على الحملات الكبيرة:

* **حد المراسلة لدى Meta.** تحدد Meta عدد الأشخاص الذين يمكنك مراسلتهم خارج نافذة الـ 24 ساعة خلال أي 24 ساعة متتالية. راجع [حدود المراسلة](https://knowledge.flowella.io/ar/whatsapp/limits/messaging-limits.md).
* **حد المعدل لمفتاح API.** تُرجع الطلبات التي تتجاوز الحد `429` مع ترويسة `Retry-After`. راجع [حدود المعدل](https://knowledge.flowella.io/ar/api-reference/introduction.md#rate-limits).

وزّع الإرسالات الكبيرة باستخدام أدوات التحكم في الإرسال الخاصة بـ Customer.io، وتابع التقدم في علامة التبويب **Statistics** الخاصة بالقالب. يتخطى Flowella كل من ألغى اشتراكه على الرقم الذي ترسل منه. راجع [إلغاءات الاشتراك](https://knowledge.flowella.io/ar/app/opt-outs.md).

## مزامنة رسائل WhatsApp الواردة إلى Customer.io (اختياري)

يرسل هذا الجزء كل رسالة WhatsApp ترسلها إليك جهة اتصال إلى Customer.io، حتى تتمكن من تحديث الشخص أو بدء حملات أخرى منها.

**1. أنشئ أتمتة تُشغَّل عبر webhook في Customer.io**

أنشئ حملة أو أتمتة تُشغَّل عبر webhook وانسخ عنوان webhook الذي ينشئه Customer.io. راجع دليل Customer.io حول [حملات webhook](https://docs.customer.io/journeys/webhook-triggered-campaigns/).

**2. أضف webhook صادرًا في Flowella**

في Flowella، انتقل إلى **Settings**، ثم **Webhooks**، واختر **Add webhook**. الصق عنوان Customer.io في **Endpoint URL**، وأدخل سر توقيع، وحدد `message.received` فقط ضمن **Events**. راجع [Webhooks](https://knowledge.flowella.io/ar/settings/webhooks.md).

**3. أرسل بيانات نموذجية**

أرسل لنفسك قالب WhatsApp من Flowella ورد عليه، حتى يتلقى Customer.io حدث `message.received` حقيقيًا تبني منه سير العمل. يبدو كل حدث هكذا:

```json theme={null}
{
  "id": "evt_3f2b8c1d9a7e4f60b5c2d8e1a4f7b9c3",
  "type": "message.received",
  "created_at": "2026-10-21T09:30:00.000Z",
  "payload_version": "1",
  "data": {
    "messageId": "clxxxxxxxxxxxxxxxxxxxxxxxx",
    "conversationId": "clxxxxxxxxxxxxxxxxxxxxxxxx",
    "contactId": "clxxxxxxxxxxxxxxxxxxxxxxxx",
    "direction": "INBOUND",
    "type": "TEXT",
    "metaMessageId": "wamid.HBgLMTU1NTEyMzQ1NjcVAgASGBQzQUY"
  }
}
```

يرسل **Send test event** في Flowella حدث `webhook.test` لا يحتوي على جهة اتصال، لذا استبعده في الخطوة التالية.

**4. احتفظ بالرسائل الواردة الحقيقية فقط**

أضف **True/False Branch** لا يتابع إلا عندما تكون قيمة `type` في المُشغِّل `message.received`.

**5. ابحث عن جهة الاتصال في Flowella**

يحمل الحدث معرّفات، وليس رقم الهاتف. أضف إجراء **Send and receive data** بالطريقة `GET`، والعنوان `https://api.flowella.io/v1/contacts/{{trigger.data.contactId}}`، وترويسة `Authorization` نفسها كما سبق. تحتوي الاستجابة على `id` و`phone` و`waId` و`name` و`email` و`externalId` و`isOptedOut` و`createdAt` و`updatedAt` الخاصة بجهة الاتصال.

لحفظ الرسالة نفسها، أضف طلبًا آخر إلى `GET /v1/messages/{{trigger.data.messageId}}`. يحمل الحقل `body` نص الرسالة وقد يكون فارغًا.

**6. حدّث الشخص**

أضف إجراء **Create or Update Person**. اختر المعرّف الذي تستخدمه مساحة عملك للأشخاص، واضبط السمات التي تحتاجها فقط، مثل وقت آخر رد على WhatsApp. راجع دليل Customer.io حول [إنشاء شخص أو تحديثه](https://docs.customer.io/journeys/create-update-person/).

> [!WARNING]
>
> في أتمتة تُشغَّل عبر webhook، ينشئ **Create or Update Person** شخصًا جديدًا عندما لا يطابق أحد المعرّف. لتجنب إنشاء أشخاص لا تريدهم، أضف شرطًا للإجراء بحيث لا تُنفَّذ الخطوة إلا عند وجود قيمة المعرّف، واختبر برقم غير موجود في مساحة عملك.

### أمان webhook الوارد

يوقّع Flowella كل طلب بترويسة `X-Flowella-Signature`. لا تستطيع الأتمتة التي تُشغَّل عبر webhook في Customer.io التحقق من هذا التوقيع، لذا يمكن لأي شخص يملك عنوان webhook في Customer.io إرسال بيانات إليه. أبقِ العنوان سريًا، ولا تستخدم المزامنة الواردة لتغيير سمات الموافقة أو الفوترة. راجع [التحقق من التواقيع](https://knowledge.flowella.io/ar/api-reference/webhooks.md#verify-signatures) إذا كنت توجّه الأحداث عبر نقطة النهاية الخاصة بك أولًا.

### إلغاءات الاشتراك

عندما ترسل جهة اتصال `STOP` أو كلمة مفتاحية أخرى لإلغاء الاشتراك، يسجّل Flowella إلغاء الاشتراك على رقم WhatsApp ذلك ويحظر كل إرسال لاحق إليها منه، بما في ذلك الإرسالات من Customer.io. راجع [إلغاءات الاشتراك](https://knowledge.flowella.io/ar/app/opt-outs.md).

لنسخ إلغاءات الاشتراك إلى Customer.io، لا تعتمد على الحدث `optout.created`: فهو لا يُطلق حاليًا عند أول إلغاء اشتراك لجهة اتصال على رقم ما. استخدم بدلًا من ذلك `GET /v1/opt-outs` لسرد إلغاءات الاشتراك، وهو يقبل عاملَي التصفية `createdAfter` و`phone`.

## استكشاف الأخطاء وإصلاحها

| العَرَض | السبب | الحل |
| - | - | - |
| `401` مع `Invalid or expired API key` | أُلغي المفتاح أو استُبدل، أو لُصق بشكل خاطئ. | أنشئ مفتاحًا جديدًا وحدّث ترويسة `Authorization`. راجع [مفاتيح API](https://knowledge.flowella.io/ar/settings/api-keys.md). |
| **Could not load API keys** في Flowella | لا يمكن إلا لأصحاب دور Owner وAdmin إدارة مفاتيح API. | اطلب من صاحب دور Owner أو Admin إنشاء المفتاح. |
| `401` مع `Missing bearer token` | ذهب الطلب إلى `https://app.flowella.io/api/v1`، الذي يعيد التوجيه، فسقطت الترويسة. | استخدم `https://api.flowella.io/v1`. |
| يُرجع الاختبار `202` لكن لا يصل شيء | طابق الجسم أو `Idempotency-Key` إرسالًا سابقًا خلال 7 أيام، أو ذهب القالب نفسه إلى الرقم نفسه خلال 15 ثانية. | استخدم قيمة `Idempotency-Key` جديدة لكل اختبار. |
| تلقى الشخص الأول وحده في الحملة الرسالة | تُركت قيمة `Idempotency-Key` ثابتة في الإجراء. | أزل الترويسة، أو اجعل قيمتها فريدة لكل شخص. |
| يظهر فشل للإرسال في علامة التبويب **Statistics** | لم تتمكن Meta من تسليم الرسالة، مثلًا لأن الرقم غير موجود على WhatsApp. | اقرأ السبب في العمود **Details**. راجع [رموز أخطاء Meta](https://knowledge.flowella.io/ar/whatsapp/errors/error-codes.md). |
| **Invalid phone number.** في علامة التبويب **Statistics** | سمة الهاتف فارغة أو ليست بالتنسيق الدولي. | احفظ الأرقام مع رمز الدولة، مثل `+447700900123`. |
| لا يتلقى Customer.io أي أحداث واردة | webhook في Flowella غير نشط أو لم يُحدد `message.received`. | تحقق من **Delivery log** الخاص بـ webhook في Flowella. راجع [Webhooks](https://knowledge.flowella.io/ar/settings/webhooks.md#delivery-log). |

## ذات صلة

> [card] [مقدمة API](https://knowledge.flowella.io/ar/api-reference/introduction.md)
>
> المصادقة ومنع التكرار وحدود المعدل والأخطاء.

> [card] [مرجع Webhooks](https://knowledge.flowella.io/ar/api-reference/webhooks.md)
>
> أنواع الأحداث وأجسام الطلبات والتواقيع.

> [card] [متغيرات القوالب](https://knowledge.flowella.io/ar/app/template-variables.md)
>
> المتغيرات والنماذج والقيم الاحتياطية.

> [card] [الإرسال المجمّع](https://knowledge.flowella.io/ar/app/bulk-send.md)
>
> أرسل قالبًا إلى قائمة من تطبيق Flowella بدلًا من ذلك.


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