جهات الاتصال

/v1/contacts

استخدم العقدة contacts لإدارة مستخدمي واتساب في قاعدة بياناتك من خلال التحقق منهم قبل إرسال الرسائل، والتحقق من صحة هوية المستخدم باستخدام خوارزميات تجزئة الهوية.

باستخدام العقدة contacts، يمكنك:

• التحقق من أن رقم الهاتف الموجود في قاعدة بياناتك ينتمي إلى حساب واتساب صالح. يجب التأكد من أن status تتوفر بالقيمة valid قبل أن تتمكن من إرسال رسالة إلى المستخدم.
• الحصول على معرف واتساب المرتبط برقم هاتف محدد. يلزم توفير معرفات واتساب لإرسال الرسائل وإشعارات المستخدم.

قبل البدء

احرص على توفير خيار لعملائك يتيح لهم الاشتراك للتواصل مع نشاطك التجاري عن طريق واتساب. تتم المحافظة على تدفق الاشتراك هذا من جانب نشاطك التجاري. بمجرد أن يشترك العميل، استخدم العقدة contacts للتحقق من الرقم المسجّل. لمزيد من المعلومات، راجع التعرف على كيفية الاشتراك للتواصل في واتساب.

التقييدات

• استخدام نقطة النهاية هذه للتحقق من أن رقم الهاتف المتوفر في قاعدة بيانات النشاط التجاري ينتمي إلى حساب واتساب صالح
• يجب ألا يتخطى عدد الاستدعاءات عدد الرسائل التي يرسلها رقم الهاتف

الإنفاذ

إذا كان النشاط التجاري يُسيء استخدام نقطة النهاية، فسيتم اتخاذ الإجراءات التالية:

• سيتلقى كل المسؤولين المدرجين في مدير الأعمال تحذيرًا مبدئيًا عبر البريد الإلكتروني إذا تم الاشتباه في وجود إساءة استخدام
• سيكون لدى النشاط التجاري سبعة أيام بعد تلقي التحذير لتعديل سلوكه
• إذا لم يتم تعديل الاستدعاءات بعد مرور سبعة أيام، فسيتم تعطيل رقم الهاتف بشكل دائم

التوصيات

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

الإنشاء

قبل إرسال الرسائل إلى المستخدمين الذين اشتركوا، أرسل طلب POST إلى نقطة النهاية /v1/contacts لإنشاء طلب التحقق من مستخدم حساب واتساب. في الاستدعاء، قم بتضمين قائمة بأرقام الهواتف التي تريد التحقق منها.

مثال

POST /v1/contacts
{
  "blocking": "wait" | "no_wait",
  "contacts": [
  	"16315551000",
  	"+1 631 555 1001",
  	"6315551002",
  	"+1 (631) 555-1004",
  	"1-631-555-1005"
  ],
  "force_check": false | true
}

ستتلقى استجابة تتضمن status الحالية للأرقام المطلوبة ومعرفات واتساب المرتبطة بها (wa_id):

{
  "contacts": [ {
    "wa_id": "16315551000",
    "input": "16315551000",
    "status": "valid"
  },
  {
    "wa_id": "16315551001",
    "input": "+1 631 555 1001",
    "status": "processing" # Only applicable when request is non-blocking
  },
  {
    "input": "6315551002",
    "status": "invalid"
  },
  {
    "input": "+163155588",
    "status": "failed"
  }
}

احفظ معرفات واتساب المرتبطة بتلك الأرقام التي تقوم بإرجاع status بالقيمة valid. المستخدمون الصالحون هم أولئك الذين لديهم حساب على واتساب. استخدم معرفات واتساب لإرسال الرسائل والإشعارات.

كرّر هذه الخطوات على أساس ثابت لإدارة قائمة المستخدمين الصالحين الخاصة بك. يتم تخزين النتائج مؤقتًا في قاعدة بيانات عميل API داخل المواقع في واتساب للأعمال لمدة 7 أيام.

المعلمات

يتم دعم المعلمات التالية لإجراء استدعاءات POST إلى /v1/contacts:

عناصر الربط

ترتبط عناصر الربط التالية بهذه العقدة:

الحظر

يتوفر خياران للمعلمة blocking وهما: no_wait وwait. إذا لم يتم تحديد المعلمة blocking في أي استدعاء، فستتوفر بالقيمة no_wait افتراضيًا.

تحدد المعلمة blocking ما إذا كان ينبغي للطلب انتظار اكتمال عملية المعالجة (متزامن) أم لا (غير متزامن).

تنسيقات أرقام الهواتف

يمكن أن تكون أرقام الهواتف الموجودة في الطلب contacts بأي تنسيق يمكن الاتصال من خلاله.

فيما يلي أمثلة توضح هذا السلوك، على افتراض أنه تم تسجيل عميل API داخل المواقع في واتساب للأعمال برقم هاتف هندي (مما يعني أن كود البلد هو +91):

الحقول التي يتم إرجاعها

تحتوي حمولة بيانات استجابة contacts على المصفوفة نفسها التي تتضمن أرقام الهواتف المُرسلة في الطلب مع الخصائص input وstatus وwa_id:

بالإضافة إلى الحالة processing، يجب أن تظهر حالة HTTP بالقيمة 200 OK.

إذا تم إرسال رسالة قالب إلى رقم الهاتف بدون توفر حساب واتساب، فستتلقى رسالة خطأ تشير إلى أن "المستخدم غير صالح" مع عرض رمز الخطأ 1013.

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

حظر جهات الاتصال

يمكن اعتبار الحظر ميزة دفاعية لإيقاف المحتالين من متابعة التصرفات الضارة. لحظر جهة اتصال، يجب أن تكون تلك الجهة قد أرسلت إليك رسالة في غضون الـ 24 ساعة الماضية.

مثال

أرسل استدعاء API إلى /v1/contacts/{phone_number}/block يتضمن سببًا لحظر حساب واتساب آخر.

POST /v1/contacts/+16315551000/block
{
   "reason": "Optional string(0;60). Freeform block reason. Will be used when another WhatsApp account is being blocked"
}

يكون للاستجابة الناجحة حالة HTTP 200 ولا يوجد كائن "للأخطاء".

تبدو الاستجابة الفاشلة على النحو التالي:

{   
    "errors": [
        {
            "code": 2048,
            "title": "Not engaged contact",
            "details": "Invalid Request. This contact hasn't engaged with you in the last 24 hrs."
        }
    ]
}

المعلمات

يتم دعم المعلمات التالية لإجراء استدعاءات POST إلى /v1/contacts/{phone_number}/block:

إلغاء حظر جهات الاتصال

قم بإجراء هذه المكالمة لإلغاء حظر جهة اتصال

مثال

أرسل استدعاء API إلى /v1/contacts/{phone_number}/unblock

POST /v1/contacts/+16315551000/unblock

يكون للاستجابة الناجحة حالة HTTP 200 ولا يوجد كائن "للأخطاء".

تبدو الاستجابة الفاشلة على النحو التالي:

{   
    "errors": [
        {
            "code": 1009,
            "title": "Parameter value is not valid",
            "details": "Provided WhatsApp ID is not valid. Please provide a valid WhatsApp ID or a phone number with a country code"
        }
    ]
}

المعلمات

يتم دعم المعلمات التالية لإجراء استدعاءات POST إلى /v1/contacts/{phone_number}/unblock:

قائمة الحظر

هذه هي الطريقة التي تحصل بها على قائمة بجهات الاتصال المحظورة لديك.

مثال

أرسل استدعاء API إلى /v1/contacts/blocklist لاستلام قائمة مقسمة إلى صفحات تتضمن جهات الاتصال المحظورة لديك

GET /v1/contacts/blocklist?limit=10&offset=0

ستتلقى استجابة عبر صفحة تتضمن قائمة الحظر مع معلومات تقسيم الصفحات

{
   "contacts": [
       {
           "wa_id": "16315551000@s.whatsapp.net"
       }
   ],
   "pagination": {
       "limit": 10,
       "offset": 0,
       "total": 1
   }
}

المعلمات

يتم دعم المعلمات التالية لإجراء استدعاءات GET إلى /v1/contacts/blocklist:

إعداد التقارير

توفر ميزة إعداد التقارير إشارات مهمة لإنشاء حل وقائي ضد المحتالين. قبل الإبلاغ عن جهة اتصال، يجب أن تكون تلك الجهة قد أرسلت إليك رسالة في غضون الـ 24 ساعة الماضية.

مثال

أرسل استدعاء API إلى /v1/contacts/{phone_number}/report يتضمن سببًا إذا كنت تحاول حظر حساب واتساب آخر.

POST /v1/contacts/+16315551000/block
{
   "reason": "Optional string(0;60). Freeform block reason. Will be used when another WhatsApp account is being blocked",
   "block": "true | false optional boolean with default of false",
   "message_id": "message-id. Optional reported message id"
}

يكون للاستجابة الناجحة حالة HTTP 200 ولا يوجد كائن "للأخطاء".

تبدو الاستجابة الفاشلة على النحو التالي:

{  
    "errors": [
        {
            "code": 2048,
            "title": "Not engaged contact",
            "details": "Invalid Request. This contact hasn't engaged with you in the last 24 hrs."
        }
    ]
}

المعلمات

يتم دعم المعلمات التالية لإجراء استدعاءات POST إلى /v1/contacts/{phone_number}/report: