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

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

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

قبل أن تبدأ

  • مؤسسة في Flowella مع رقم WhatsApp مرتبط. راجع تسلسل الإعداد.
  • قالب WhatsApp معتمد في Flowella. راجع القوالب.
  • دور Owner أو Admin في Flowella، لإنشاء مفتاح API، ولإنشاء webhook من أجل المزامنة الواردة. راجع الفريق والأدوار.
  • مساحة عمل في Customer.io يمكنك فيها إنشاء حملات أو عمليات أتمتة تحتوي على إجراءات webhook.
  • رقم WhatsApp لكل شخص محفوظ في ملفه على Customer.io بالتنسيق الدولي، مثل +447700900123. راجع تنسيق رقم الهاتف.
  • موافقة كل شخص على تلقي رسائل WhatsApp منك. تشترط Meta الحصول على الموافقة قبل مراسلة أي شخص. راجع إرشادات الموافقة لدى Meta.

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

1

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

في Flowella، انتقل إلى Settings، ثم API keys، وأنشئ مفتاحًا مباشرًا باسم مثل Customer.io production. انسخه فورًا: يعرضه Flowella مرة واحدة فقط. راجع مفاتيح API.
2

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

استدعِ GET /v1/templates?status=APPROVED بمفتاحك. دوّن id وwabaId الخاصين بالقالب، وwhatsappChannelId للرقم الذي تريد الإرسال منه. راجع القنوات المتعددة إذا كان لديك عدة أرقام.
3

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

في سير عمل حملتك على Customer.io، أضف إجراء Send and receive data عند النقطة التي يجب أن تُرسل فيها رسالة WhatsApp. راجع دليل Customer.io حول إجراءات webhook.
4

اضبط الطلب

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

اكتب جسم الطلب

الصق هذا الجسم واستبدل المعرّفات بمعرّفاتك. غيّر customer.phone إلى السمة التي تحفظ رقم WhatsApp الخاص بالشخص.
يملأ bodyParameters متغيرات نص القالب بالترتيب: تذهب القيمة الأولى إلى {{1}}، والثانية إلى {{2}}، وهكذا. اتركه قائمة فارغة، []، إذا لم يكن في نص القالب متغيرات.
6

اختبر الإجراء

اختر شخصًا تجريبيًا يحمل رقم WhatsApp الخاص بك واختر Test response في Customer.io. أضف ترويسة Idempotency-Key بقيمة لم تستخدمها من قبل، مثل test-2026-11-11-01، وغيّرها في كل اختبار. راجع الإرسال المتكرر ومنع التكرار.تعني الاستجابة 202 مع "status": "accepted" أن Flowella وضع الإرسال في قائمة الانتظار. ولا تؤكد التسليم: تحقق من علامة التبويب Statistics الخاصة بالقالب في Flowella لمعرفة النتيجة.
7

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

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

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

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

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

يحميك POST /v1/templates/send من إرسال الرسالة نفسها مرتين، وهذا مهم لأن Customer.io يعيد محاولة إجراء webhook عندما لا يتلقى استجابة 2xx:
  • دون ترويسة Idempotency-Key، يستخدم Flowella قيمة تجزئة لجسم الطلب كمفتاح. يُرجع الجسم المطابق بايتًا ببايت خلال 7 أيام قيمة id الأصلية ولا يرسل شيئًا. ولأن جسم كل شخص يحتوي على رقمه الخاص، ترسل الحملة العادية إلى كل شخص مرة واحدة.
  • مع ترويسة Idempotency-Key، يُرجع أي طلب بالمفتاح نفسه خلال 7 أيام قيمة id الأصلية ولا يرسل شيئًا، حتى لو تغيّر الجسم.
  • بشكل منفصل، يتخطى Flowella الإرسال الثاني للقالب نفسه إلى الرقم نفسه خلال 15 ثانية.
لا تترك أبدًا قيمة Idempotency-Key ثابتة في إجراء حملة مباشرة. سيتلقى الشخص الأول وحده الرسالة: يعيد كل طلب لاحق استخدام المفتاح، فيُرجع Flowella قيمة id الأولى ولا يرسل شيئًا. أزل الترويسة قبل بدء الحملة، أو أنشئ قيمة تختلف لكل شخص، مثل اسم الحملة متبوعًا بـ {{customer.id}}.
تفسّر القواعد نفسها معظم الاختبارات الفاشلة. إرسال القالب نفسه إلى الشخص التجريبي نفسه مرة أخرى ينتج الجسم نفسه، لذا لا يرسل Flowella شيئًا ما لم تغيّر قيمة Idempotency-Key في كل مرة.

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

يضع كل طلب من Customer.io إرسالًا واحدًا في قائمة الانتظار، ويسلّمه Flowella في الخلفية، مع إعادة المحاولة عند أخطاء WhatsApp المؤقتة. ينطبق حدّان على الحملات الكبيرة:
  • حد المراسلة لدى Meta. تحدد Meta عدد الأشخاص الذين يمكنك مراسلتهم خارج نافذة الـ 24 ساعة خلال أي 24 ساعة متتالية. راجع حدود المراسلة.
  • حد المعدل لمفتاح API. تُرجع الطلبات التي تتجاوز الحد 429 مع ترويسة Retry-After. راجع حدود المعدل.
وزّع الإرسالات الكبيرة باستخدام أدوات التحكم في الإرسال الخاصة بـ Customer.io، وتابع التقدم في علامة التبويب Statistics الخاصة بالقالب. يتخطى Flowella كل من ألغى اشتراكه على الرقم الذي ترسل منه. راجع إلغاءات الاشتراك.

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

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

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

أنشئ حملة أو أتمتة تُشغَّل عبر webhook وانسخ عنوان webhook الذي ينشئه Customer.io. راجع دليل Customer.io حول حملات webhook.
2

أضف webhook صادرًا في Flowella

في Flowella، انتقل إلى Settings، ثم Webhooks، واختر Add webhook. الصق عنوان Customer.io في Endpoint URL، وأدخل سر توقيع، وحدد message.received فقط ضمن Events. راجع Webhooks.
3

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

أرسل لنفسك قالب WhatsApp من Flowella ورد عليه، حتى يتلقى Customer.io حدث message.received حقيقيًا تبني منه سير العمل. يبدو كل حدث هكذا:
يرسل 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 حول إنشاء شخص أو تحديثه.
في أتمتة تُشغَّل عبر webhook، ينشئ Create or Update Person شخصًا جديدًا عندما لا يطابق أحد المعرّف. لتجنب إنشاء أشخاص لا تريدهم، أضف شرطًا للإجراء بحيث لا تُنفَّذ الخطوة إلا عند وجود قيمة المعرّف، واختبر برقم غير موجود في مساحة عملك.

أمان webhook الوارد

يوقّع Flowella كل طلب بترويسة X-Flowella-Signature. لا تستطيع الأتمتة التي تُشغَّل عبر webhook في Customer.io التحقق من هذا التوقيع، لذا يمكن لأي شخص يملك عنوان webhook في Customer.io إرسال بيانات إليه. أبقِ العنوان سريًا، ولا تستخدم المزامنة الواردة لتغيير سمات الموافقة أو الفوترة. راجع التحقق من التواقيع إذا كنت توجّه الأحداث عبر نقطة النهاية الخاصة بك أولًا.

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

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

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

مقدمة API

المصادقة ومنع التكرار وحدود المعدل والأخطاء.

مرجع Webhooks

أنواع الأحداث وأجسام الطلبات والتواقيع.

متغيرات القوالب

المتغيرات والنماذج والقيم الاحتياطية.

الإرسال المجمّع

أرسل قالبًا إلى قائمة من تطبيق Flowella بدلًا من ذلك.
آخر تعديل في ٢١ نوفمبر ٢٠٢٦