وثائق واجهة برمجة تطبيقات واتساب ناو

مقدمة

مرحبًا بك في وثائق واجهة برمجة تطبيقات WhatsApp Now الخاصة بمنتج Message Central. ستجد هنا تفاصيل للتعرف على كل حالة من حالات استخدام منصة WhatsApp Business API وتجربتها وتنفيذها. WhatsApp Now هو حل شامل للتكامل مع واجهات برمجة تطبيقات WhatsApp Business الرسمية. يستفيد منتجنا من منصة WhatsApp القوية والمستخدمة على نطاق واسع لتمكين الشركات من التواصل بسلاسة مع عملائها، وتوفير خدمة مراسلة موثوقة وفعالة.

المتطلبات الأساسية لاستخدام WhatsApp Now

قبل البدء في تكامل API، تأكد من أن لديك:

1. Gerente de negócios do Facebook verificado
2. Conta na Central de Mensagens
3. Vinculação da sua conta comercial do Facebook com a Central de Mensagens
4. Um número de telefone que precisa ser verificado e usado com a Central de Mensagens

المساعدة والدعم

للحصول على دعم التنفيذ وأي ملاحظات، يرجى التواصل معنا على operations@messagecentral.com

فهم رسائل WhatsApp

لا يمكن إرسال رسائل WhatsApp Business Solution إلا من قبل الشركات التي تمت الموافقة عليها من قبل Meta. سيحتوي ملف تعريف النشاط التجاري هذا أيضًا على علامة خضراء تم التحقق منها للإشارة إلى أنها شركة مشروعة.

ميزة WhatsApp هي أن معرف المستخدمين على المنصة هو رقم هاتفهم المحمول.

قواعد مراسلة العملاء

يحتوي WhatsApp على مفهوم نافذة خدمة العملاء على مدار 24 ساعة، حيث يمكن للشركة خلالها إرسال رسائل بحرية إلى المستخدم النهائي. يمكن بدء نافذة الـ 24 ساعة بطريقتين:

1. يقوم المستخدم النهائي بإرسال رسالة إلى النشاط التجاري
2. تقوم الشركة بإرسال رسالة نموذجية إلى المستخدم النهائي. تبدأ نافذة الـ 24 ساعة بمجرد رد المستخدم النهائي.

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

التسعير المستند إلى محادثة WhatsApp

تقدم Message Central نموذج التسعير القائم على المحادثة لرسائل WhatsApp. هذا يتماشى مع نموذج التسعير الذي قدمته WhatsApp في بداية فبراير 2022.

ما هي المحادثة؟

المحادثة هي أي عدد من الرسائل المرسلة داخل «الجلسة»، والتي يتم تعريفها على أنها فترة 24 ساعة تبدأ من وقت إرسال الرسالة الأولى من قبل الشركة.

من يبدأ المحادثة؟

يمكن أن تكون المحادثة بدأت إما عن طريق عميل (بمبادرة من المستخدم) أو اعمال (بدء النشاط التجاري)، ولكن في كلتا الحالتين تبدأ «الجلسة» بالرسالة الأولى التي يرسلها النشاط التجاري.

كيف يعمل التسعير لكل محادثة؟

يتم تسعير أسعار رسائل WhatsApp لكل محادثة. بدءًا من الأول من يونيو، يتم تسعير هذا السعر لكل محادثة ونوع محادثة. توجد الآن أربع فئات للمحادثة، كل منها يتم تحصيل الرسوم بمعدلات مختلفة:

1. محادثة المرافق - تمكين إكمال طلب أو معاملة معينة متفق عليها أو تزويد العميل بتحديث حول معاملة جارية، بما في ذلك إشعارات ما بعد الشراء وبيانات الفواتير العادية.
2. محادثة المصادقة - تمكن الشركات من استخدام رموز المرور لمرة واحدة للتحقق من المستخدمين في مراحل تسجيل الدخول المختلفة، إذا لزم الأمر (مثل التحقق من الحساب واسترداد الحساب وتحديات النزاهة)
3. محادثة تسويقية - المحادثات التي تبدأ من الأعمال لتسويق سلعة أو خدمة للعملاء، مثل إرسال العروض ذات الصلة للعملاء الذين اختاروا الاشتراك. قد يشمل ذلك أيضًا أي تفاعل متعلق بالأعمال لا يمثل مصادقة أو محادثة مفيدة.
4. محادثة الخدمة - المناقشات التي يبدأها المستخدم والتي تساعد المستهلكين في الحصول على إجابات لأسئلتهم.

واجهات برمجة تطبيقات واتساب ناو

يسهل Message Central إرسال الرسائل عبر قنوات الاتصال المختلفة، بما في ذلك SMS و WhatsApp و RCS (خدمات الاتصالات الغنية). توفر واجهة برمجة التطبيقات هذه ميزات قوية وخيارات مرنة لتلبية احتياجات المراسلة المتنوعة. WhatsApp Now هو أحد منتجات Message Central الذي يعتمد على واجهات برمجة تطبيقات WhatsApp Business الرسمية.

استخدم سيناريوهات الحالة

• حملات ترويجية: استخدم WhatsApp Now لإرسال رسائل ترويجية ورسائل مفيدة للعملاء عبر WhatsApp. أرسل الوسائط المتعددة والمستندات مباشرة من خلال WhatsApp. قم بتسليم رسائل وإشعارات وتحديثات مخصصة لتعزيز رضا العملاء وولائهم لتعزيز تجربة العملاء الخاصة بك.
  
• رسائل الدردشة الحية: إرسال واستقبال الرسائل والوسائط المتعددة والمستندات مباشرة من خلال WhatsApp، مما يضمن التواصل الفعال في الوقت المناسب مع جمهورك.
  
• التحقق من OTP: تنفيذ نظام تسليم OTP آمن لمصادقة المستخدم، والاختيار بين الرسائل القصيرة أو WhatsApp أو البريد الإلكتروني بناءً على تفضيلات المستخدم ومتطلبات الأمان.

أيضًا، يجب إرسال المعلمات التالية أثناء استخدام واجهات برمجة تطبيقات WhatsAppNow؛

بقية عناوين URL الأساسية لواجهة برمجة التطبيقات:

يجب أن تكون جميع نقاط نهاية Platform API أدناه مسبوقة بعنوان URL التالي:

https://cpaas.messagecentral.com

إنشاء رمز

عند استخدام واجهات برمجة تطبيقات WhatsApp Now لإنشاء قوالب وإرسال رسائل نصية ورسائل بث، يجب أن تكون المكالمة الأولية لواجهة برمجة تطبيقات إنشاء الرمز المميز. تقوم واجهة برمجة التطبيقات هذه بإرجاع رمز مميز يجب تضمينه في جميع المكالمات اللاحقة. يلزم وجود رمز مصادقة للتحقق من صحة المستخدم ويجب تضمينه في قسم العنوان لكل طلب.

معايير الطلب:

مسار عنوان URL للطلب:

/auth/v1/authentication/token 

cURL

1curl --location 'https://cpaas.messagecentral.com/auth/v1/authentication/token?customerId=<CustomerId>&key=<Base64 Encrypted password>&scope=NEW&country=91&email=test@messagecentral.com' \
2--header 'accept: */*'

‍

ملاحظة: لتحويل أمر cURL إلى كود باستخدام Postman، افتح Postman، واستورد الأمر cURL عبر زر «استيراد»، ثم قم بإنشاء الكود بلغتك المفضلة بالنقر فوق الزر «Code» على الجانب الأيمن من الطلب.

الاستجابة: جسون

ستؤدي الاستجابة الناجحة إلى إرجاع رمز الحالة 200.

1{
2      "status": Integer,
3      "token": "String"
4} 

إنشاء قالب

يمكنك إنشاء قوالب من أنواع وفئات مختلفة، بالإضافة إلى إنشاء أشكال لغوية متعددة للقالب. عند إنشاء قوالب بإصدارات متعددة اللغات، تأكد من الاتساق مع الترجمات عبر الإصدارات.

تأكد من أن القوالب الخاصة بك تتبع إرشادات قالب رسالة WhatsApp. ليس يمكن أن يؤثر اتباع الإرشادات بشكل صحيح على النماذج التي تتم الموافقة عليها.

‍

عملية الموافقة

يجب أن توافق Meta على القوالب قبل استخدامها في رسالة WhatsApp. عند الإنشاء، تتمتع القوالب في البداية بحالة معلق. بمجرد الموافقة عليها، سيكون لديهم وضع وافق، ويمكن استخدامها بعد ذلك.

فئات القالب

• فائدة: تمكين إكمال طلب أو معاملة معينة متفق عليها أو تزويد العميل بتحديث حول معاملة جارية، بما في ذلك إشعارات ما بعد الشراء وبيانات الفواتير العادية.
• المصادقة: يمكّن الشركات من استخدام رموز المرور لمرة واحدة للتحقق من المستخدمين في مراحل تسجيل الدخول المختلفة، إذا لزم الأمر (مثل التحقق من الحساب واسترداد الحساب وتحديات النزاهة).
• تسويق: محادثات بدأتها الشركات لتسويق سلعة أو خدمة للعملاء، مثل إرسال العروض ذات الصلة للعملاء الذين اختاروا الاشتراك. قد يشمل ذلك أيضًا أي تفاعل متعلق بالأعمال لا يمثل مصادقة أو محادثة مفيدة.

إلى إنشاء قالب فيما يلي معايير الطلب. رمز المصادقة مطلوب لإنشاء قالب تم إنشاؤه بواسطة واجهة برمجة تطبيقات الرمز المميز التي تم إنشاؤها (والتي يمكنك العثور عليها أعلاه في قسم المقدمة)

مسار عنوان URL للطلب:

POST: /verification/v3/template

معايير الطلب:

cURL

1curl --location 'https://cpaas.messagecentral.com/verification/v3/template' \
2--header 'authToken: eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJDLTM4MERBQzg1RDlGRjREMSIsImlhdCI6MTcyMDc2OTI2OCwiZXhwIjoxODc4NDQ5MjY4fQ.O8xl7vMUoOU4dCn61dqFTjBMxTVvnEpRCkzjMo4JW9YQrEdL0PK3sQW4PgZBWRUCvKDkoSRoDAdXhXy9rx' \
3--form 'phoneNumber="919457888189"' \
4--form 'name="template_without_media"' \
5--form 'language="en_US"' \
6--form 'category="MARKETING"' \
7--form 'headerFormat="TEXT"' \
8--form 'header="Congratulations"' \
9--form 'body="Hello Your account recharge of ₹100 is successful. Please use our services and enjoy!"' \
10--form 'footer="Type \"STOP\" to unsubscribe"'

‍

cURL

1curl --location 'https://cpaas.messagecentral.com/verification/v3/template' \
2--header 'authToken: eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJDLTM4MERBQzg1RDlGRjREMSIsImlhdCI6MTcyMDc2OTI2OCwiZXhwIjoxODc4NDQ5MjY4fQ.O8xl7vMUoOU4dCn61dqFTjBMxTVvnEpRCkzjMo4JW9YQrEdL0PK3sQW4PgZBWRUCvKDkoSRoDAdXYh9rxa' \
3--form 'phoneNumber="919457888189"' \
4--form 'name="template_without_media"' \
5--form 'language="en_US"' \
6--form 'category="MARKETING"' \
7--form 'headerFormat="TEXT"' \
8--form 'body="Hello Your account recharge of ₹100 is successful. Please use our services and enjoy!"' \
9--form 'footer="Type \"STOP\" to unsubscribe"' \
10--form 'file=@"/C:/Users/Kunal Suryawanshi/Downloads/Media (9).png"'

‍

استجابة JSON (بدون قوالب الوسائط ومعها):

ستؤدي الاستجابة الناجحة إلى إرجاع رمز الحالة 200.

1{
2    "responseCode": 200,
3    "data": {
4        "data": {
5            “name”: "example_template",
6            "id": "790937216444187",
7            "status": "PENDING",
8            "category": "MARKETING"
9        }
10    }
11}

استشارة لإنشاء قالب

1. الاسم - يجب أن يكون اسم القالب دائمًا بأحرف صغيرة. أيضًا، في حالة تعدد الكلمات، يرجى إضافة «_» بين كلمتين (على سبيل المثال: tes_template_01)
2. قالب متغير - لإنشاء قالب متغير، تحتاج إلى إضافة عناصر نائبة وقيم نصها الأساسي بشكل إلزامي أثناء إنشاء طلب لمثل هذا القالب.

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

‍رسالة نموذجية - مرحبًا {{1}}، احصل على خصم 50٪ من خلال تطبيق رمز الكوبون {{2}} الأحدث من {{3}}

BodyValue (للرسالة أعلاه) - «كونال MSGCTL50 20 يونيو»، هنا كونال هو مثال على قيمة الجسم الأولى وما إلى ذلك.

3. حد الأحرف - يمكن أن تكون الرسالة النصية بحد أقصى 4096 أحرف طويلة.

رموز الخطأ لإنشاء قالب

تحقق من حالة القالب

يتيح لك ذلك مراقبة حالة قوالب الرسائل المقدمة للموافقة عليها على WhatsApp. توفر واجهة برمجة التطبيقات هذه تحديثات في الوقت الفعلي حول ما إذا كانت القوالب الخاصة بك قد تمت الموافقة عليها أو تعليقها أو رفضها، مما يضمن لك البقاء على علم بمدى توفرها للاستخدام.

معايير الطلب:

cURL

1curl --location --request GET 
2'https://cpaas.messagecentral.com/verification/v3/template' \
3--header 'authToken: 
4eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJDLTM4MERBQzg1RDlGRjREMSIsImlhdCI6MTcyMDc2OT
5 I2OCwiZXhwIjoxODc4NDQ5MjY4fQ.O8xl7vMUoOU4dCn61dqFTjBMxTVvnEpRCkzjMo4JW9YQrE
6 dL0PK3sQW4PgZBWRUCvKDkoSRoDAdYXh9rxa' \
7 --form 'phoneNumber="919547888189"' \
8 --form 'templateId="205681076471259"' \
9 --form 'templateName="test_template"' 

‍

الاستجابة: جسون

ستؤدي الاستجابة الناجحة إلى إرجاع رمز الحالة 200.

1{
2    "name": "prod_test_temp_wmedia_1",
3    "components": [
4        {
5            "type": "HEADER",
6            "format": "TEXT",
7            "text": "Congratulations!"
8        },
9        {
10            "type": "BODY",
11            "text": "Your account recharge of $100 is successful. Please use our services and enjoy!"
12        },
13        {
14            "type": "FOOTER",
15            "text": "Type \"STOP\" to unsubscribe"
16        }
17    ],
18    "language": "en_US",
19    "status": "APPROVED",
20    "category": "UTILITY",
21    "id": "205681076471259"
22}

رموز الخطأ للحصول على حالة القالب

إرسال البث

لإرسال بث WhatsApp إلى أرقام الهواتف المحمولة، تكون معايير الطلب التالية مطلوبة. يعد رمز المصادقة، الذي تم إنشاؤه بواسطة واجهة برمجة تطبيقات إنشاء الرمز المميز، ضروريًا لإرسال رسائل القالب عبر البث.

مسار عنوان URL للطلب:

POST: /verification/v3/send

إرسال بث فردي

لإرسال رسالة بث WhatsApp إلى مستلم واحد للتواصل الشخصي أو ردود دعم العملاء أو الإشعارات العاجلة حيث يلزم الاتصال المستهدف.

معايير الطلب:

ملاحظة: يجب أن تتم الموافقة على القوالب المستخدمة من Meta. يمكن إرسال إجابتي CTA ديناميكيتين كحد أقصى فقط.

cURL

ملاحظة: يجب أن تكون جميع القوالب المستخدمة قوالب معتمدة من Meta.

يرجى العثور على نموذج الملف بتنسيق XLXS أدناه:

أوصاف الحقل:

ملاحظة: الأعمدة الأربعة الأولى (يجب دائمًا تضمين البلد، الهاتف المحمول، CTAVar1، CTAVar2) في العنوان، حتى في حالة عدم وجود CTAs ديناميكية في القالب. في مثل هذه الحالات، يجب أن تظل أسماء الأعمدة، ولكن يجب ترك القيم فارغة.

رقم متغير يجب أن تتطابق الأعمدة في ملف Excel مع عدد العناصر النائبة المتغيرة في القالب الخاص بك تمامًا. على سبيل المثال، إذا كان القالب الخاص بك يحتوي على عنصرين نائبين، فيجب أن يتضمن الملف var1 و var2—لا أكثر ولا أقل.

يرجى الرجوع إلى الأمثلة التالية لفهم التنسيق الصحيح للملف.

المثال 1: إذا أرادت مؤسسة إرسال رسالة مخصصة باستخدام تحميل ملف بدون CTA ديناميكي ومتغيرين، فيجب تنسيق حقل الرسالة على النحو التالي:

نموذج رسالة - مرحبًا {{1}}، احصل على خصم 50٪ من خلال تطبيق الكوبون {{2}} يجب أن يكون تنسيق XLxS كما يلي:

المثال 2: إذا أرادت مؤسسة إرسال رسالة مخصصة باستخدام تحميل الملفات باستخدام CTA الديناميكي و 3 متغيرات، فيجب تنسيق حقل الرسالة على النحو التالي:

نموذج رسالة - مرحبًا {{1}}، احصل على خصم 50٪ من خلال تطبيق الكوبون {{2}} الأحدث من {{3}} CTA - www.messagecentral.com/ {{1}}

يجب أن يكون تنسيق XLxS كما يلي:

cURL

1curl --location 
2'https://cpaas.messagecentral.com/verification/v3/send?flowType=WHATSAPP&se
3 nderId=919457848169&type=BROADCAST&templateName=template_without_media_1' \
4 --header 'authToken: 
5eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJDLTM4MERBQzg1RDlGRjREMSIsImlhdCI6MTcyMDc2OT
6 I2OCwiZXhwIjoxODc4NDQ5MjY4fQ.O8xl7vMUoOU4dCn61dqFTjBMxTVvnEpRCkzjMo4JW9YQrE
7 dL0PK3sQW4PgZBWRUCvKDkoSRoDAdYXh9rxa' \
8 --form 'file=@"/C:/Users/Kunal Suryawanshi/Documents/Test_WA_API.xlsx"'

‍

الاستجابة: جسون

ستؤدي الاستجابة الناجحة إلى إرجاع رمز الحالة 200.

1{
2    "responseCode": 200,
3    "message": "SUCCESS",
4    "data": null
5}
6

رموز الخطأ لإرسال البث

إرسال رسائل الدردشة

لإرسال رسالة WhatsApp (رسالة دردشة) إلى رقم هاتف محمول، تكون معايير الطلب التالية مطلوبة. يعد رمز المصادقة، الذي تم إنشاؤه بواسطة واجهة برمجة تطبيقات إنشاء الرموز، ضروريًا لإرسال أي رسائل عبر الدردشة الحية.

مسار عنوان URL للطلب:

/verification/v3/send

معايير الطلب:

cURL

1curl --location --request POST 'https://cpaas.messagecentral.com/verification/v3/send?countryCode=91&flowType=WHATSAPP&mobileNumber=7715836906&senderId=919457888189&type=CHAT&message=Welcome%20to%20Message%20Central' \
2--header 'authToken: eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJDLTM4MERBQzg1RDlGRjREMSIsImlhdCI6MTcyMDc2OTI2OCwiZXhwIjoxODc4NDQ5MjY4fQ.O8xl7vMUoOU4dCn61dqFTjBMxTVvnEpRCkzjMo4JW9YQrEdL0PK3sQW4PgZBWRUCvKDkoSRoDAdYXh9rxa'

‍

الاستجابة: جسون

ستؤدي الاستجابة الناجحة إلى إرجاع رمز الحالة 200.

1{
2    "responseCode": 200,
3    "message": "SUCCESS",
4    "data": {
5        "verificationId": null,
6        "mobileNumber": "917715836906",
7        "responseCode": "200",
8        "errorMessage": null,
9        "timeout": null,
10        "smsCLI": null,
11        "transactionId": "wamid.HBgMOTE3NzE1ODM2OTA2FQIAERgSOEFFNUM5MTFDRUVBMDUzMDFGAA=="
12    }
13}

رموز الخطأ لرسائل الدردشة

إعداد Webhook للرسائل الواردة

قبل أن تتمكن من بدء تلقي الإشعارات، ستحتاج إلى إنشاء نقطة نهاية على الخادم الخاص بك لتلقي الإشعارات.

عندما يحدث حدث مثير، ترى منصة WhatsApp Business Platform التابعة لـ Message Central الحدث وترسل إشعارًا إلى عنوان URL الخاص بـ Webhook الذي ستحدده. يمكنك الحصول على نوعين من الإشعارات:

1. الرسائل المستلمة: يتيح لك هذا التنبيه معرفة متى تلقيت رسالة. يمكن أيضًا تسمية هذه «الإشعارات الواردة» في جميع الوثائق.
2. حالة الرسالة: يتيح لك هذا التنبيه معرفة متى تغيرت حالة الرسالة - على سبيل المثال، تمت قراءة الرسالة أو تسليمها. يمكن أيضًا تسمية هذه «الإشعارات الصادرة».

للاشتراك في Webhooks، ستحتاج إلى اتباع الخطوات التالية:

1. المعلومات المطلوبة:بعض النصوص
   1. معرف العميل
   2. اسم العلامة التجارية
   3. معرف البريد الإلكتروني المسجل
   4. عنوان URL الخاص برد الاتصال
      
      
2. تعليمات التقديم: يرجى إرسال المعلومات أعلاه إلى operations@messagecentral.com مع سطر الموضوع «تكوين WhatsApp Webhook مع مركز الرسائل».
   
   
3. مواصفات عنوان URL الخاص برد الاتصال: تأكد من أن عنوان URL الخاص برد الاتصال الخاص بك يمكن الوصول إليه وقادر على تلقي طلبات HTTP POST التي تحتوي على حمولات JSON مع تحديثات الحالة. عند التشغيل، ستتلقى نقطة النهاية حمولة JSON التالية ويجب أن تستجيب بـ 200.

‍