إذا كنت قد تعاملت سابقاً مع WhatsApp Cloud API، فأنت تعرف واجهتنا بالفعل. نفس مسارات الطلب، نفس هيئة JSON، ونفس توثيق Bearer — فقط وجّه الكود لنطاقنا.
02إرسال أول رسالة
رسالة نصية عادية. جسم الطلب هو نفس هيكل كود Cloud API القياسي — نمرره مباشرة لـ Meta بدون تعديل.
cURL
curl -X POST https://api.smartsybox.com/v26.0/PHONE_NUMBER_ID/messages \
-H "Authorization: Bearer YOUR_DEVICE_KEY" \
-H "Content-Type: application/json" \
-d '{
"messaging_product": "whatsapp",
"to": "15551234567",
"type": "text",
"text": { "body": "Hello from SyBox 👋" }
}'
C# · HttpClient
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
var http = new HttpClient();
http.DefaultRequestHeaders.Authorization =
new AuthenticationHeaderValue("Bearer", "YOUR_DEVICE_KEY");
string json = @"{
""messaging_product"": ""whatsapp"",
""to"": ""15551234567"",
""type"": ""text"",
""text"": { ""body"": ""Hello from SyBox"" }
}";
var res = await http.PostAsync(
"https://api.smartsybox.com/v26.0/PHONE_NUMBER_ID/messages",
new StringContent(json, Encoding.UTF8, "application/json"));
Console.WriteLine(await res.Content.ReadAsStringAsync());
الاستجابة
تستقبل نفس الاستجابة الناتجة من Meta مع نفس كود حالة HTTP — لتستمر مكتبات الكود الحالية في قراءته بسلاسة.
200 OK · application/json
{
"messaging_product": "whatsapp",
"contacts": [{ "input": "15551234567", "wa_id": "15551234567" }],
"messages": [{ "id": "wamid.HBgLMTU1NTEyMzQ1NjcVAgARGBI…" }]
}
04اعرض بيانات نظامك بجانب المحادثة
عند فتح محادثة، يستدعي SyBox نقطةَ الوصول الخاصة بنظامك ويعرض ما تُرجِعه بجانب المحادثة مباشرةً — طلبات العميل ورصيده وتذاكره. نُرسل رقم هاتف العميل، أو بريده الإلكتروني في محادثات البريد.
Request · SyBox → your endpoint
POST YOUR_ERP_URL
Authorization: Bearer YOUR_ERP_KEY
X-Sybox-Action: lookup
# body: { "data": "<json string>" } — the decoded "data":
{
"phone": "15551234567",
"email": "customer@example.com",
"ref": ""
}
Your reply · application/json
{
"renderAs": "table",
"content": [
{ "Order": "#10432", "Status": "Shipped", "Total": "1,250 MAD" }
]
}
renderAs
حدِّد renderAs ليعرف SyBox كيف يعرض بياناتك — واحدة من:
table
Rows & columns. content = an array of flat objects (or { rows: [ … ] }). Object keys become the column headers.
cards · kpi
Compact tiles (a balance, an order count). content = an array of { label, value } (or { cards: [ … ] }).
feed · list · thread
A timeline of rich cards. content = an array of { title, text, date, tags, media:[{ type, url, name }] }.
message
A single message-style card (one record laid out as a note).
html
Your own trusted HTML — content = a string. Use only for markup you generate yourself.
sections
Several blocks at once: content = { sections: [ { title, renderAs, content } ] } — mix a table + cards + a feed in one reply.
json
The default when renderAs is omitted — SyBox pretty-prints your content as-is.
أضِف sybox_ref إلى أي صفٍّ في جدول أو بطاقة فيصبح قابلاً للنقر — يستدعيك SyBox مجدَّداً بذلك الـ ref لتُرجِع تفاصيل ذلك السجلّ وحده.
نُرسل الهاتف والبريد معاً، وقد يكون أحدهما فارغاً؛ طابِق العميل بأيّهما يُعرّفه في نظامك، وأجِب بـ { renderAs, content }.
05إنشاء حالة/تذكرة من نظامك الخارجي
هذا هو المسار الذي تستخدمه برامج الـ ERP والأنظمة المحاسبية. بدلاً من إرسال نص عادي، يطلب برنامجك من SyBox فتح حالة جديدة ومتابعتها.
cURL
curl -X POST "https://api.smartsybox.com/v1/case" \
-H "Authorization: Bearer $SYBOX_CASE_KEY" \
-H "Content-Type: application/json" \
-d '{
"customer_unique_id": "CUST-10432",
"header": "Screen replacement not delivered",
"description": "Paid on 12 Aug, promised in 3 days, still nothing.",
"ext_ref": "TICKET-99817"
}'
الحقول المطلوب تمريرها
customer_unique_id
معرّف السجل الخاص بالعميل في نظامك — نفس المفتاح المستعمل في مزامنة العملاء.
header / description
أحدهما على الأقل مطلوب. الهيدر هو العنوان الذي يظهر للموظفين بداخل القائمة.
ext_ref
رقم التذكرة بداخل نظامك. أرسله دائماً؛ فإعادة الطلب بنفس ext_ref تعيد الحالية الموجودة بدلاً من تكرارها.
يجب أن يكون العميل موجوداً مسبقاً. أي حالة لعميل غير موجود سيتم رفضها لضمان صحة البيانات.
استخدم مفتاحاً من نوع case. مفاتيح التمرير (الخاصة بالرسائل) سيتم رفضها بكود 403 لمنع استخدام مفاتيح المحادثات بداخل نظام CRM.