دليل المطوّرين

اربط تطبيقك أو موقعك أو نظامك ببوتزو بثلاث أدوات: إرسال رسائل واتساب، وموتشي (المساعد الذكي الذي يرد على عملائك)، والـ Webhooks التي تخبر سيرفرك بكل جديد لحظة حدوثه.

هذا الدليل مكتوب لكل مبرمج، حتى لو كانت أول مرة تتعامل مع واتساب. اقرأ هذه الصفحة أولاً، ثم انتقل للقسم الذي تحتاجه.

#ماذا تستطيع أن تبني؟

كل ما يحدث عبر الـ API يظهر في صندوق المحادثات (Inbox) في لوحة تحكم بوتزو، ويستطيع فريقك الرد منه مباشرة.

#العنوان الأساسي

كل الطلبات تذهب إلى:

https://botzo.net/api

• كل الطلبات والردود بصيغة JSON وترميز UTF-8 (العربية والإيموجي مدعومة).
• أرسل دائماً الهيدرين: Accept: application/json و Content-Type: application/json.
• الاتصال عبر HTTPS فقط.

#ابدأ في 5 دقائق

#1) أنشئ مفتاح API

من لوحة التحكم: أدوات المطوّرين ← مفاتيح الوصول. اكتب اسماً للمفتاح (مثلاً «سيرفر المتجر»)، اختر الصلاحية، ثم اضغط إنشاء مفتاح. انسخ المفتاح فوراً لأنه يظهر مرة واحدة فقط.

مهم: المفتاح مثل كلمة السر. ضعه في متغيرات البيئة على سيرفرك (BOTZO_API_KEY)، ولا تضعه في كود الواجهة أو في تطبيق الموبايل. التفاصيل في المفاتيح والأمان.

#2) تأكد أن المفتاح يعمل

curl https://botzo.net/api/verify \
  -H "Authorization: Bearer $BOTZO_API_KEY" \
  -H "Accept: application/json"

const res = await fetch('https://botzo.net/api/verify', {
  headers: { Authorization: `Bearer ${process.env.BOTZO_API_KEY}`, Accept: 'application/json' },
});
console.log(res.status, await res.json());

$response = Http::withToken(env('BOTZO_API_KEY'))->acceptJson()->get('https://botzo.net/api/verify');
echo $response->status(); // 200

import os, requests
r = requests.get("https://botzo.net/api/verify",
                 headers={"Authorization": f"Bearer {os.environ['BOTZO_API_KEY']}", "Accept": "application/json"})
print(r.status_code, r.json())

الرد:

{
  "statusCode": 200,
  "message": "API key is valid and active"
}

#3) أرسل أول رسالة

العميل يجب أن يكون أرسل لك رسالة خلال آخر 24 ساعة حتى تستطيع إرسال نص حر (هذه قاعدة واتساب، اقرأ قواعد واتساب). للتجربة: أرسل «مرحبا» من جوالك لرقم واتساب مؤسستك، ثم:

curl -X POST https://botzo.net/api/send \
  -H "Authorization: Bearer $BOTZO_API_KEY" \
  -H "Accept: application/json" -H "Content-Type: application/json" \
  -d '{"phone": "+966501234567", "message": "طلبك في الطريق 🚚"}'

const res = await fetch('https://botzo.net/api/send', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.BOTZO_API_KEY}`,
    Accept: 'application/json',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ phone: '+966501234567', message: 'طلبك في الطريق 🚚' }),
});
const result = await res.json();
console.log(result.message_id); // احفظه لتتابع حالة الرسالة

$result = Http::withToken(env('BOTZO_API_KEY'))->acceptJson()
    ->post('https://botzo.net/api/send', ['phone' => '+966501234567', 'message' => 'طلبك في الطريق 🚚'])
    ->json();
echo $result['message_id'];

r = requests.post("https://botzo.net/api/send",
                  headers={"Authorization": f"Bearer {os.environ['BOTZO_API_KEY']}", "Accept": "application/json"},
                  json={"phone": "+966501234567", "message": "طلبك في الطريق 🚚"})
print(r.json()["message_id"])

النجاح يرجع 200 ومعه message_id. إذا رفضت واتساب الرسالة يرجع خطأ واضح مثل outside_24h_window، والتفاصيل في الأخطاء.

#4) استقبل ردود عملائك

من أدوات المطوّرين ← Webhooks اضغط «استخدم المستقبِل التجريبي» ثم «إضافة Webhook». أرسل رسالة من جوالك، ثم اضغط «تحديث» في قسم المستقبِل التجريبي: سترى الحدث message.received كما سيصل لسيرفرك تماماً، ومعه حالة التوقيع. عندما يجهز سيرفرك ضع رابطه بدل المستقبِل التجريبي. التفاصيل في الـ Webhooks.

#شكل الردود

نجاح: يحتوي دائماً على statusCode بنفس رقم الـ HTTP، وباقي الحقول حسب الطلب.

خطأ: نفس الشكل في كل الـ API:

{
  "statusCode": 422,
  "code": "outside_24h_window",
  "message": "(#131047) Re-engagement message",
  "request_id": "9fb64a88-f0f1-4a36-a1e8-0ba3eef81360"
}

#اصطلاحات مهمة

• أرقام الجوال بالصيغة الدولية E.164 مع رمز الدولة: +966501234567. لو أرسلتها بدون + نضيفها لك.
• الأوقات بتوقيت UTC. أغلب الحقول بصيغة ISO 8601 مثل 2026-10-22T18:23:06+00:00، وبعضها بصيغة 2026-10-22 18:23:06 (UTC أيضاً).
• المعرّفات: رسائل واتساب لها message_id يبدأ بـ wamid.، وجهات الاتصال والمجموعات والقوالب لها uuid، ومحادثات موتشي لها conversation_id.
• الهيدر Server-Timing يرجع مع كل رد ويقول أين ذهب الوقت، مثلاً: app;dur=27.4, db;dur=12.1, meta;dur=980. القيمة app هي الطلب كله، وmeta وقت خوادم واتساب، وdb وقت قاعدة البيانات. مفيد جداً لو احتجت تعرف سبب أي بطء.

#الخطوة التالية

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