ما هي واجهات برمجة تطبيقات التتبع الخاصة بـ Interakt؟

فيما يلي المستندات المرجعية للاتصال بواجهات برمجة التطبيقات الخاصة بنا. تحقق من مجموعة ساعي البريد & بايثون SDK.

مقدمة إلى واجهات برمجة تطبيقات Interakt

تسمح لك نقاط نهاية Interakt Track API بتشغيل بيانات محددة إلى Interakt. يمكن استخدام نقاط نهاية واجهة برمجة التطبيقات هذه لإضافة مستخدمين وأحداثهم إلى حساب Interakt الخاص بك، والذي يمكن أن يكون متاحًا بعد ذلك لبناء المزيد من السياق عند الدردشة مع عملائك، وإعداد إشعارات مخصصة وذات صلة على نطاق واسع. يمكنك استدعاء واجهات برمجة التطبيقات هذه بمجرد إنشاء مستخدم جديد على موقع الويب الخاص بك أو تطبيقك أو حتى في وقت لاحق حسبما تراه مناسبًا. هناك نوعان من واجهات برمجة التطبيقات المتاحة:‍ • واجهات برمجة التطبيقات لتتبع المستخدم: لإنشاء مستخدم جديد وإدراج سماته في لوحة تحكم Interakt و • واجهات برمجة التطبيقات لتتبع الأحداث: لتسجيل أي أحداث تخص هذا المستخدم في لوحة تحكم Interakt الخاصة بك. هناك فرق بين "السمة" المرسلة إلى نقطة نهاية المستخدم، مقارنةً بـ "السمة" المرسلة إلى نقطة نهاية الحدث: • نقطة نهاية المستخدم: بالنسبة لنفس السمة، إذا قمت بإرسال قيمة جديدة، فسوف تحل محل القيمة الحالية. • نقطة نهاية الحدث: يتم تمثيل الأحداث نفسها المرسلة في أوقات مختلفة على خط زمني ولا تحل محل بعضها البعض.

رسومات عامة

1. افترض أنك أرسلت حدث اسمه "النظام الجديد" للمستخدم الخاص بك مع السمات "رقم الطلب" و"مبلغ الطلب"، عندما يقدم المستخدم طلبًا على موقع الويب الخاص بك. في كل مرة يتم فيها تلقي حدث "طلب جديد" على نقطة نهاية مسار الحدث لدينا، يتم تسجيله في الجدول الزمني للأحداث للمستخدم كما هو موضح أدناه.

2. من ناحية أخرى، لنفترض أنك تريد تسجيل "إجمالي مبلغ الطلب" حتى الآن للمستخدم. لذلك، يمكنك إرسال السمة 'مقدار' إلى نقطة نهاية تتبع المستخدم، والتي يتم عرضها بعد ذلك في بطاقة التفاصيل الشخصية، كما هو مبين أدناه. على عكس نقطة نهاية الأحداث، سيتم استبدال القيم القديمة للسمات المرسلة إلى نقطة نهاية المستخدمين بالقيمة الجديدة. وهنا تظهر السمة "المبلغ" القيمة 2000 في البداية. عند إرسال 7000 كقيمة جديدة، يتم استبدال القيمة القديمة، كما هو موضح أدناه.

المصادقة: يمكنك المصادقة باستخدام Interakt Track APIs عن طريق إرسال مفتاح API مع بيانات الطلب تستخدم آلية المصادقة مصادقة HTTP الأساسية والذي يتطلب منك إرسال Base64 مشفر 'اسم المستخدم كلمة المرور' مسبوقة بـ "أساسي' سلسلة.

‍ مفتاح API = ترميز base64 'اسم المستخدم كلمة المرور'

يتم تمرير هذه القيمة في رأس الطلب تحت "التفويض"، وسيبدو زوج المفاتيح في رأس الطلب كالتالي: "التفويض: أساسي"مفتاح واجهة برمجة التطبيقات>'.

‍ يرجى الملاحظة: يمكنك العثور على مفتاح API في لوحة القيادة الخاصة بك. انتقل إلى الإعدادات > إعداد المطور > المفتاح السري. ‍

نوع المحتوى: يجب عليك تعيين رأس نوع المحتوى إلى 'application/json' لتتمكن من إرسال البيانات إلى نقطة نهاية HTTP API الخاصة بنا.

الأخطاء: ستعيد نقاط نهاية API الخاصة بنا 200 رمز حالة لجميع الطلبات الناجحة. إذا كان الطلب كبيرًا، فقد تحصل على رمز الحالة 400.

‍ ملاحظة: في حالة احتواء السمة على أي مما يلي، سيعيد استدعاء API رمز الحالة 400:

‍"سطر جديد / علامة تبويب / أكثر من مسافتين متتاليتين"

• حدود المعدل: يوجد حد أقصى لكل دقيقة لعدد طلبات واجهة برمجة التطبيقات، وذلك حسب خطة الاشتراك الخاصة بك. إذا تم تجاوز حد المعدل، فسيتم إرجاع خطأ (رمز الحالة: 429 ورسالة الخطأ: تم تجاوز حد المعدل لهذا المورد).

• خطة النمو - 300 طلب في الدقيقة

• الخطة المتقدمة - 600 طلب في الدقيقة

• خطة المؤسسات - قابلة للتكوين وفقًا لحدود معدل البيانات المسموح بها من Meta

(ملاحظة - لا يمكن الوصول إلى واجهات برمجة التطبيقات العامة في الخطة الأساسية)

الحد الأقصى لحجم الطلب: الحد الأقصى لحجم الطلب هو 32 كيلو بايت لكل طلب. إذا تم تجاوز هذا المعدل، تستجيب واجهة برمجة التطبيقات (API) بـ 400 طلب سيئ.

واجهة برمجة تطبيقات تتبع المستخدم

كيفية إضافة/تحديث تفاصيل المستخدم على Interakt عبر واجهات برمجة تطبيقات تتبع المستخدم تسمح واجهة برمجة تطبيقات تتبع المستخدم للعملاء بتسجيل السمات الخاصة بالمستخدم. يمكنهم تسجيل خصائص (سمات) مستخدم محددة مثل معرف المستخدم ومعرف البريد الإلكتروني ورقم الهاتف والاسم وما إلى ذلك. يمكن للعملاء الاتصال بواجهة برمجة تطبيقات تتبع المستخدم عند إنشاء حساب مستخدم جديد على موقع الويب/التطبيق/إدارة علاقات العملاء الخاص بهم. على سبيل المثال: لإضافة مستخدم جديد إلى لوحة تحكم Interakt، يمكن إرسال الحمولة التالية في استدعاء API:

POST https://api.interakt.ai/v1/public/track/users/
{
 “userId”: “0123abc45d”,
 “phoneNumber”: “9967536783”,
 “countryCode”: “+91”,
 “traits”: {
   “name”: “Gavin Roberts”,
   “email”: “[email protected]”,
   “dob”: “1996-12-01”,
   "Sample trait a":"value y"
 }
}

يمكن أن تكون سمات (سمات) المستخدم المختلفة من أنواع البيانات التالية: String، Numbers، Boolean، Datetime، List. اطلع على خيارات التصفية المختلفة المتاحة في برنامج Interakt، لأنواع السمات المختلفة - وصلة ملحوظة**: تحديد إما معرف المستخدم or رقم الهاتف (مع رمز البلد) is إلزامي

يسجل استدعاء واجهة برمجة التطبيقات أعلاه "معرف المستخدم" أو "رقم الهاتف" (مع "رمز البلد") كمعرف فريد للمستخدم ويضيف أيضًا سمات مثل الاسم والبريد الإلكتروني وتاريخ الميلاد.

‍ لتحديث السمات للمستخدم أعلاه، يمكن إرسال الحمولة التالية في استدعاء API: (لنفترض أن السمة "dob" بحاجة إلى التغيير إلى "1997-12-01"). 

POST https://api.interakt.ai/v1/public/track/users/
{
 “userId”: “0123abc45d”,
 “phoneNumber”: “9967536783”,
 “countryCode”: “+91”,
 “traits”: {
   “dob”: “1997-12-01”
 }
}

‍ لإضافة سمة جديدة للمستخدم أعلاه، يمكن إرسال الحمولة التالية في استدعاء API: (لنفترض أنه يجب إضافة سمة "الرمز السري"). 

POST https://api.interakt.ai/v1/public/track/users/
{
 “userId”: “0123abc45d”,
 “phoneNumber”: “9967536783”,
 “countryCode”: “+91”,
 “traits”: {
   “Pin code”: “400001”
 }
}

يمكنك الآن إضافة علامات على عملائك في Interakt عبر واجهات برمجة التطبيقات.

ما عليك سوى تضمين مفتاح "tags" في استدعاء واجهة برمجة تطبيقات تتبع المستخدم. حمولة العينة:

{
 "phoneNumber": "9967536783",
 "countryCode": "+91",
 "traits": {
   "name": "Gavin Roberts",
   "email": "[email protected]"
 },
 "tags": ["new customer", "potential lead"]
}

‍ • يمكنك إضافة علامات متعددة. • يمكنك فقط إضافة علامات جديدة. لا يمكنك حذف العلامات الموجودة. • إضافة العلامات غير حساسة لحالة الأحرف، أي إذا أضفت علامة "عميل جديد" على العميل أ وكانت علامة "عميل جديد" موجودة بالفعل على العميل أ، فلن تتم إضافة أي علامة جديدة على العميل أ.

كيف يكون هذا مفيداً تحديداً للعملاء الذين لديهم قوائم مستخدمين طويلة لا يتم تصفيتها بواسطة سمات المستخدم المخصصة؟

• إذا أراد العميل تصفية قائمة المستخدمين الخاصة به لإرسال حملة لمرة واحدة، فإنه يواجه مشكلات إذا كان يقوم بالتصفية باستخدام سمة مخصصة. • لنفترض أن السمة المخصصة التي يستخدمها هي "المدينة" وأن شرط التصفية هو "المدينة" = "كولكاتا". • الآن، بدلاً من إضافة سمة مخصصة لـ "المدينة = كولكاتا"، يمكنه إضافة وسم "كولكاتا" للمستخدم. • ثم يمكنه تصفية قائمة المستخدمين حسب هذه العلامة وإرسال الحملات

‍ تنويه هام: يوصى المستخدمين بعدم إضافة أكثر من 50 علامة للعميل ملاحظة: 1. في حالة إضافة المستخدم أعلاه في الأصل عبر لوحة معلومات Interakt (وليس عن طريق الاتصال بـ User Track API)، فلن يكون هناك معرف مستخدم لهذا المستخدم. في هذه الحالة، يمكنك إما: • اتصل بـ User Track API دون تحديد "معرف المستخدم" (وتحديد "رقم الهاتف" و"رمز البلد" فقط)، أو، • قم بتضمين معرف المستخدم في استدعاء واجهة برمجة التطبيقات، والذي ستتم إضافته بعد ذلك لهذا المستخدم، ويمكنك استخدام معرف المستخدم هذا للإشارة إلى هذا المستخدم في استدعاءات واجهة برمجة التطبيقات المستقبلية.*

2. حاليًا، لا نوفر خيار حذف أي مستخدم / سمة مستخدم. *يُرجى التأكد من أن معرف المستخدم المضاف لا ينتمي إلى مستخدم موجود بالفعل في حساب Interakt الخاص بك، وإلا ستلقي واجهة برمجة التطبيقات خطأً.

أين يمكنك رؤية المستخدمين المضافين في لوحة تحكم Interakt الخاصة بك؟ عند إنشاء مستخدم عن طريق استدعاء User Track API، سيكون المستخدم (مع السمات) مرئيًا في الأقسام التالية من لوحة معلومات Interakt: • سيتم إدراج المستخدم الجديد في صفحة "المستخدمون":

‍ • ستكون سمات المستخدم مرئية في بطاقة "البيانات الشخصية". - تظهر هذه البطاقة في مكانين: 1) في محادثة صندوق الوارد مع المستخدم المحدد؛ 2) في قسم تفاصيل المستخدم (عند النقر على إدخال المستخدم).

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

إعداد الحملات للمستخدمين المضافين بناءً على شروط سمات المستخدم:

‍ • حملة لمرة واحدة: يمكن استخدام هذه الحملة لرسالة بث لمرة واحدة تريد إرسالها إلى المستخدمين لديك.

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

للقيام بذلك، ستحتاج إلى تحديد حملة "مرة واحدة" وتعيين شرط التصفية التالي في صفحة إنشاء الحملة: '"نوع الشركة" يحتوي على "بقالة". (في المثال أدناه، عدد المستخدمين المؤهلين لهذا المعيار هو 38.)

- بمجرد تفعيل الحملة من صفحة إنشاء الحملة، سيتم إرسال الإشعار إلى جميع هؤلاء المستخدمين الـ 38 في التاريخ المحدد.

‍ انقر هنا للتحقق من الخطوات التفصيلية لإعداد حملة مباشرة.

• الحملة المستمرة: اعرف المزيد

ما هي واجهة برمجة تطبيقات تتبع الأحداث الخاصة بـ Interakt؟

كيفية إضافة تفاصيل الحدث لمستخدم على Interakt عبر واجهات برمجة تطبيقات تتبع الأحداث

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

POST https://api.interakt.ai/v1/public/track/events/
{
 “userId”: “0123abc45d”,
 “event”: “OrderPlaced”,
 “traits”: {
   “orderCreatedBy”: “Gavin Roberts”,
   “orderCreatedDate”: “2020-11-01T012:10:26.122Z”,
   “orderNumber”: “CUS001”,
   “orderValue”: “50.00”
 }
}

يؤدي استدعاء واجهة برمجة التطبيقات (API) أعلاه إلى تشغيل حدث OrderPlaced عندما يقوم المستخدم بإجراء طلب على موقع الويب/التطبيق الخاص بك. يقوم استدعاء API بتمرير خصائص الحدث orderCreatedBy وorderCreatedDate وorderNumber وorderValue إلى نقطة نهاية API.

‍ يرجى الملاحظة: في حالة عدم وجود معرف المستخدم (userId) للمستخدم، يجب تحديد "رقم الهاتف" و "رمز البلد" في استدعاء واجهة برمجة تطبيقات تتبع الأحداث أعلاه.

‍ أين يمكنك رؤية الأحداث المضافة في لوحة تحكم Interakt؟

تظهر تفاصيل الحدث في بطاقة "الأحداث" - هذه البطاقة مرئية في مكانين: 1. في محادثة البريد الوارد مع المستخدم المحدد 2. في قسم تفاصيل المستخدم (عند النقر على إدخال المستخدم)

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

باستخدام واجهات برمجة التطبيقات، قم بتشغيل حملة مستمرة على Interakt

اعرف المزيد

واجهة برمجة تطبيقات استرداد جهات الاتصال

مجموعة ساعي البريد لواجهة برمجة التطبيقات هذه.

عند حصولك على عميل محتمل جديد عبر واتساب من خلال Interakt، يمكنك الآن ضمان نقل تفاصيل هذا العميل إلى أنظمة إدارة علاقات العملاء (CRM) وقواعد البيانات الأخرى لديك باستخدام واجهة برمجة تطبيقات استرجاع جهات الاتصال. ما عليك سوى إضافة استدعاءات واجهة برمجة التطبيقات إلى كود نظامك، أو استخدامها في منصات الربط (مثل Integromat وZapier) لمزامنة Interakt مع أنظمة إدارة علاقات العملاء (CRM) السحابية لديك. المصادقة: تستخدم آلية المصادقة مصادقة HTTP الأساسية والذي يتطلب منك إرسال مفتاح API الخاص بك مُسبقًا بـ "أساسي' سلسلة نصية. تُمرر هذه القيمة في رأس الطلب ضمن قسم "التفويض"، وسيبدو زوج المفاتيح في رأس الطلب كالتالي: "التفويض: أساسي"مفتاح واجهة برمجة التطبيقات>'.

‍ يرجى الملاحظة: يمكنك العثور على مفتاح API في لوحة القيادة الخاصة بك. انتقل إلى الإعدادات > إعداد المطور > المفتاح السري.

‍ معلمات الاستعلام: هناك معلمتان للاستعلام يمكن تضمينهما في عنوان URL الذي سيتم استدعاء واجهة برمجة التطبيقات (API) عليه:

https://api.interakt.ai/v1/public/apis/users/?offset=0&limit=100

‍ الحد: القيمة الافتراضية هي 100. إذا كانت استجابة واجهة برمجة التطبيقات تحتوي على أكثر من 100 جهة اتصال، فسيكون الحقل "has_next_page" في استجابة واجهة برمجة التطبيقات صحيحًا ويجب استدعاء واجهة برمجة التطبيقات مرة أخرى، مع الاحتفاظ بالإزاحة بقيمة 100.

‍ عوض: القيمة الافتراضية هي 0.

‍ الأخطاء: ستعيد نقطة نهاية API الخاصة بنا 200 رمز حالة لجميع الطلبات الناجحة. سيتم عرض أخطاء 4xx في الحالات التالية:

‍ • إذا تم إدخال بيانات اعتماد الترخيص بشكل غير صحيح.

‍ • إذا تم تعيين معلمة الاستعلام "الحد" على > 100 • إذا لم يكن "val" الخاص بـ "created_at_utc" أو "modified_at_utc" بتنسيق UTC في حمولة API • إذا لم يتم إدخال الخاصيتين 'op' أو 'supr_op' بشكل صحيح

ستظهر أخطاء 5xx في حالة حدوث بعض الأخطاء الداخلية.

‍ كيفية استدعاء API:

للحصول على جهات الاتصال التي تم إنشاؤها على Interakt بعد الساعة 5 مساءً (IST) في 8 سبتمبر 2021، يمكن إرسال الحمولة التالية في استدعاء API.

POST https://api.interakt.ai/v1/public/apis/users/?offset=0&limit=100
{
 "filters": [
   {
     "trait": "created_at_utc",
     "op": "gt",
     "val": "2021-09-08T11:30:00.000Z"
   }
 ]
}

‍ ‍لاسترداد جهات الاتصال التي تم إنشاؤها على Interakt قبل الساعة 5 مساءً (IST) في 8 سبتمبر 2021، يمكن إرسال الحمولة التالية في استدعاء API.

POST https://api.interakt.ai/v1/public/apis/users/?offset=0&limit=100
{
 "filters": [
   {
     "trait": "created_at_utc",
     "op": "lt",
     "val": "2021-09-08T11:30:00.000Z"
   }
 ]
}

‍لاسترداد جهات الاتصال التي تم إنشاؤها على Interakt بعد الساعة 5 مساءً (IST) في 7 سبتمبر 2021 وقبل الساعة 5 مساءً (IST) في 8 سبتمبر 2021، يمكن إرسال الحمولة التالية في استدعاء API.

POST https://api.interakt.ai/v1/public/apis/users/?offset=0&limit=100
{
 "filters": [
   {
     "trait": "created_at_utc",
     "op": "gt",
     "val": "2021-09-07T11:30:00.0000"
   },
   {
     "trait": "created_at_utc",
     "op": "lt",
     "supr_op": "and",
     "val": "2021-09-08T11:30:00.0000"
   }
 ]
}

‍لاستعادة جهات الاتصال التي كانت تم التعديل على Interakt بعد الساعة 5 مساءً (IST) في 8 سبتمبر 2021، يمكن إرسال الحمولة التالية في استدعاء API.

POST https://api.interakt.ai/v1/public/apis/users/?offset=0&limit=100
{
 "filters": [
   {
     "trait": "modified_at_utc",
     "op": "gt",
     "val": "2021-09-08T11:30:00.000Z"
   }
 ]
}

‍ ملاحظة:‍ قم دائمًا بإرسال قيمة التاريخ والوقت بتنسيق UTC. إذا تم إرسال التاريخ فقط بدون وقت (على سبيل المثال: 2021-09-08)، فسيتم افتراض أن الوقت هو 00:00 ساعة.