وثائق المطورين والربط البرمجي

أرسل رسائل واتساب بنفس الكود والبنية البرمجية التي تعرفها بالفعل

إذا كنت قد تعاملت سابقاً مع WhatsApp Cloud API، فأنت تعرف واجهتنا بالفعل. نفس مسارات الطلب، نفس هيئة JSON، ونفس توثيق Bearer — فقط وجّه الكود لنطاقنا.

01البدء السريع

ثلاثة عناصر أساسية لإرسال أول رسالة: العنوان الرئيسي Base URL، مفتاح الجهاز Device Key، ومسار الرسائل.

Base URL
https://api.smartsybox.com
Authentication
Authorization: Bearer <YOUR_DEVICE_KEY>
Content type
application/json

نقطة الاتصال Endpoint

POST /v26.0/{phone-number-id}/messages
يُقبل جزء الإصدار بأي صيغة v مثل (v26.0 أو v1.0) — احتفظ بنفس الصيغة المستخدمة في كودك الحالي. بينما {phone-number-id} هو معرّف رقم واتساب الخاص بك مطابثاً لـ Meta.

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…" }]
}

03دعم كامل لجميع أنواع الرسائل

نظراً لتمرير جسم الطلب كما هو، فإن كافة أنواع الرسائل مدعومة — القوالب، الصور، المستندات، والرسائل التفافلية. إليك مثال لإرسال قالب Template.

Request body · template
{
  "messaging_product": "whatsapp",
  "to": "15551234567",
  "type": "template",
  "template": {
    "name": "hello_world",
    "language": { "code": "en_US" }
  }
}

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.

06حقن وتمرير رسالة قادمة من برنامج آخر

لأي نظام خارج واتساب: تنبيه من نقاط البيع POS، إشعار من جهاز، أو سطر من نظام قديم. تظهر الرسالة بداخل محادثة العميل بوضوح مع اسم البرنامج الصادر منه.

cURL
curl -X POST "https://api.smartsybox.com/v1/inbound" \
  -H "Authorization: Bearer $SYBOX_INBOUND_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "212600112233",
    "text": "Order 4821 has left the warehouse."
  }'
للوارد فقط تصميمياً. هذا المسار يكتب بداخل المحادثة ولا يرسل أي شيء للعميل.

07معالجة الأخطاء

تعود الأخطاء بنفس صيغتها وهيكليتها وكود حالتها الصادر من Meta دون إعادة صياغة.

4xx · application/json
{
  "error": {
    "message": "(#131030) Recipient phone number not in allowed list",
    "type": "OAuthException",
    "code": 131030
  }
}

08إنشاء واستخراج مفاتيح الأجهزة Device Keys

يتم إنشاء المفاتيح بداخل مساحة عملك وتتحمل التوجيه ذاتياً.

  • افتح مساحة العمل ← الإعدادات ← مفاتيح API وأنشئ مفتاح جهاز جديد.
  • كل مفتاح مربوط برقم واحد محدد ويمكن إلغاؤه في أي وقت.
  • رمز WhatsApp Token الحقيقي لا يغادر سيرفراتنا إطلاقاً — المفتاح يقوم بالنيابة عنه.
  • البوابة مغلقة افتراضياً؛ وتفعيل وصول API يضمن تشغيلها بآمان.

WhatsApp, Messenger, and Instagram are trademarks of Meta Platforms, Inc.
SyBox™ is an independent product built on Meta Cloud API.

SMART SOUQ

SMART SOUQ SARL AU · RC Marrakech N° 154779 · RC Fès N° 87323 · ICE 003587569000031
© 2026. All rights reserved.