مرجع v1 للإنتاج

مرجع API InstantReply

ابنِ على REST API الإنتاجية لمحادثات واتساب وإنستغرام وماسنجر. ستجد هنا المصادقة، pagination، الرسائل، journeys، templates، webhooks الموقعة، تتبع التسليم، وendpoints المطورين.

ابدأ بالدليل السريع كتالوج endpoints مركز المطورين

ما الذي يستطيع المطور بناؤه

استخدم InstantReply كطبقة الرسائل لمنتجك أو أدواتك الداخلية. يستطيع backend قراءة المحادثات، إرسال الردود، تحديث contacts، توجيه leads، تشغيل journeys واتساب، التحقق من templates، والتفاعل مع رسائل العملاء فوريا.

سطح API بإصدار واضح

مسارات REST العامة تعمل تحت /v1. مسارات التوافق تحت /api/v1 تصل إلى نفس API.

مبني للعمل الحقيقي

هذا هو نفس سطح الإنتاج الذي يستخدمه dashboard والautomations وردود AI وإرسال journeys.

لا تحتاج polling

سجل endpoint webhook واحدا واستقبل POSTs موقعة عند رد العميل أو تغير حالة التسليم.

المصادقة، pagination، والأخطاء

صادق الطلبات باستخدام API key محددة النطاق في Authorization: Bearer $IR_API_KEY. افصل keys الإنتاج عن test. يمكن تدوير keys من developer settings بدون تغيير secret توقيع webhook.

authbash

curl https://api.instantreply.co/v1/conversations \
  -H "Authorization: Bearer $IR_API_KEY"

send-messagebash

curl -X POST https://api.instantreply.co/v1/conversations/$ID/messages \
  -H "Authorization: Bearer $IR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"Thanks for reaching out - how can we help?"}'

Cursor pagination

كل endpoint قائمة يقبل ?cursor= ويرجع cursor التالي عند وجود سجلات إضافية. اعتبر cursor قيمة opaque وأعد إرسالها كما وصلت.

أخطاء واضحة

الأخطاء ترجع JSON envelope فيه code وmessage وdoc_url وrequest_id. احتفظ ب X-Request-Id عندما تحتاج من الدعم تتبع الطلب.

مجموعات endpoints في الإنتاج

هذه أكثر المسارات التي يستخدمها المطورون. الكتالوج REST يحتوي المخزون الكامل، أما هذه الصفحة فتشرح وظيفة كل مجموعة وكيف تدخل في التكامل.

افتح كتالوج REST الكامل

المحادثات والرسائل

اقرأ محادثات العملاء، أرسل الردود، وزامن سجل الرسائل.

GET/v1/conversations
يعرض المحادثات مع فلاتر للحالة والقناة والمسؤول وcursor pagination.
GET/v1/conversations/:id
يقرأ محادثة واحدة مع العميل والقناة والمرحلة والوسوم وآخر نشاط.
PATCH/v1/conversations/:id
يحدّث التعيين أو الحالة أو الوسوم أو حقول التوجيه للمحادثة.
GET/v1/conversations/:id/messages
يقرأ سجل الرسائل داخل محادثة محددة.
POST/v1/conversations/:id/messages
يرسل ردا عبر القناة الصحيحة: واتساب أو إنستغرام أو ماسنجر.
GET/v1/messages
يعرض الرسائل عبر كل المحادثات للمراجعة أو المزامنة أو التحليلات.
POST/v1/messages
ينشئ رسالة صادرة عندما يعرف تكاملك سياق القناة مسبقا.
GET/v1/messages/:id
يجلب تفاصيل المحتوى والتسليم لرسالة واحدة.

Contacts والقنوات والتحليلات

حافظ على سجل العميل متزامنا واجلب المقاييس التشغيلية التي يحتاجها تطبيقك.

GET/v1/contacts
يعرض contacts مع المرحلة والscore والowner وهوية القناة.
GET/v1/contacts/:id
يقرأ ملف contact وسياق المحادثات المرتبطة به.
PATCH/v1/contacts/:id
يحدّث حقول contact من lead capture أو CRM.
GET/v1/channels
يعرض قنوات واتساب وإنستغرام وماسنجر المتصلة.
GET/v1/analytics/summary
يعرض ملخص السرعة والحجم والتحويل.
GET/v1/usage
يعرض استخدام الخطة للرسائل وAI وwebhooks وAPI calls.

Keys وwebhooks

أدر API keys واشترك بأحداث موقعة تصل إلى خادمك فوريا.

GET/v1/keys
يعرض API keys النشطة والنطاقات.
POST/v1/keys
ينشئ key محددة النطاق لbackend أو agent أو بيئة test.
POST/v1/keys/:id/rotate
يدور key بدون downtime.
DELETE/v1/keys/:id
يلغي key فورا.
GET/v1/webhooks
يعرض endpoints الخاصة بالwebhooks.
POST/v1/webhooks
يسجل endpoint webhook موقع.
DELETE/v1/webhooks/:id
يعطل endpoint webhook.
GET/v1/webhooks/:id/deliveries
يفحص محاولات التسليم الأخيرة والفشل.

Journeys وtriggers والحملات

شغّل journeys واتساب، افحص نتائج التسليم، وزامن أحداث العمل.

GET/v1/journeys
يعرض journey templates المتاحة لحسابك.
POST/v1/trigger
يدخل contact في journey أو template workflow.
GET/v1/trigger/status/:id
يشرح نتيجة التسليم الحالية لtrigger.
POST/v1/trigger/validate
يتحقق من payload قبل الإرسال.
POST/v1/trigger/batch
يشغل دفعة contacts مع نتيجة لكل صف.
POST/v1/events
يرسل event خارجي من عملك إلى InstantReply.
POST/v1/campaigns/:id/send
يبدأ إرسال حملة معتمدة.

Templates وأدوات المطورين

تحقق، أرسل، وdebug templates واتساب بدون تخمين سياسة Meta.

GET/v1/templates
يعرض templates وحالتها من InstantReply وMeta.
POST/v1/templates
ينشئ مسودة template.
POST/v1/templates/:id/validate
يفحص category fit ويقدم coaching لفئة UTILITY.
POST/v1/templates/:id/submit
يرسل template إلى مراجعة Meta.
GET/v1/developer/capabilities
يعرض scopes والميزات المفعلة والحدود.
GET/v1/developer/onboarding
يعرض checklist التكامل.
GET/v1/developer/limits
يعرض rate limits والحصص.
GET/v1/developer/troubleshooting/errors/:code
يبحث عن خطأ معروف من provider.

Webhooks والأمان

سجل POST /v1/webhooks مرة واحدة وسيقوم InstantReply بدفع الأحداث إلى خادمك فوريا. التسليم at-least-once، لذلك عالج X-InstantReply-Delivery بطريقة idempotent.

التحقق من التوقيع

كل webhook لديه signing secret يبدأ ب whsec_. تحقق من X-InstantReply-Signature باستخدام HMAC-SHA256 على timestamp.rawBody قبل الوثوق بالpayload. محاولات التسليم الأخيرة في GET /v1/webhooks/:id/deliveries.

verify-signaturets

app.post("/webhooks/instantreply", express.raw({ type: "application/json" }), (req, res) => {
  const timestamp = req.header("X-InstantReply-Timestamp")
  const signature = req.header("X-InstantReply-Signature")
  const rawBody = req.body.toString("utf8")

  verifyHmacSha256({
    secret: process.env.IR_WEBHOOK_SECRET,
    payload: timestamp + "." + rawBody,
    signature,
  })

  res.sendStatus(204)
})

أسماء الأحداث الحالية
Event	متى يحدث
`message.received`	يرسل العميل رسالة عبر واتساب أو إنستغرام أو ماسنجر.
`message.sent`	يخرج message من AI أو dashboard أو API أو automation أو journey.
`conversation.created`	تفتح محادثة جديدة من inbound أو coexistence أو journey.
`conversation.closed`	تغلق محادثة يدويا أو عبر automation.
`conversation.assigned`	يتغير owner عبر تعيين يدوي أو rules للتوجيه.
`contact.updated`	يقوم lead extraction أو CRM sync بتحديث contact.
`template.status_update`	ترسل Meta تحديث مراجعة أو جودة لtemplate.
`message.delivery_failed`	يفشل provider أو يرفض التسليم بعد المحاولات.

دورة templates وتتبع التسليم

تساعد endpoints الخاصة بالtemplates الفرق على نشر templates واتساب ملتزمة. تحقق من category fit، أرسل إلى Meta، افحص provider outcomes، واشرح الأخطاء المعروفة قبل التخمين.

POST /v1/templates/:id/validate يفحص category fit ويعطي coaching لفئة UTILITY.
POST /v1/templates/:id/submit يرسل template إلى مراجعة Meta.
GET /v1/trigger/status/:id يشرح نتائج التسليم للtriggers.
GET /v1/developer/onboarding و/limits يعرضان حالة setup والميزات والحصص وrate limits.

OpenAPI في الإنتاج

Swagger/OpenAPI المولد متاح في بيئات غير إنتاجية للتحقق الداخلي. الإنتاج لا يعرض /openapi.json عمدا. استخدم هذا المرجع وكتالوج REST والدليل السريع كسطح المطورين العام.

Checklist قبل الإطلاق

يكون التكامل جاهزا للإنتاج عندما تتحقق هذه النقاط.

استخدم https://api.instantreply.co/v1 في الإنتاج.

افصل API keys الخاصة بlive وtest.

تحقق من X-InstantReply-Signature قبل قبول أي webhook.

عالج التكرار باستخدام X-InstantReply-Delivery.

أعد محاولة POST فقط باستراتيجية idempotency.

احترم نوافذ الرسائل وopt-outs لكل قناة.

مرجع API InstantReply

ما الذي يستطيع المطور بناؤه

curl -X POST https://api.instantreply.co/v1/conversations/$ID/messages \ -H "Authorization: Bearer $IR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"text":"Thanks for reaching out - how can we help?"}'

المحادثات والرسائل

اقرأ محادثات العملاء، أرسل الردود، وزامن سجل الرسائل.

GET/v1/conversations
يعرض المحادثات مع فلاتر للحالة والقناة والمسؤول وcursor pagination.
GET/v1/conversations/:id
يقرأ محادثة واحدة مع العميل والقناة والمرحلة والوسوم وآخر نشاط.
PATCH/v1/conversations/:id
يحدّث التعيين أو الحالة أو الوسوم أو حقول التوجيه للمحادثة.
GET/v1/conversations/:id/messages
يقرأ سجل الرسائل داخل محادثة محددة.
POST/v1/conversations/:id/messages
يرسل ردا عبر القناة الصحيحة: واتساب أو إنستغرام أو ماسنجر.
GET/v1/messages
يعرض الرسائل عبر كل المحادثات للمراجعة أو المزامنة أو التحليلات.
POST/v1/messages
ينشئ رسالة صادرة عندما يعرف تكاملك سياق القناة مسبقا.
GET/v1/messages/:id
يجلب تفاصيل المحتوى والتسليم لرسالة واحدة.

app.post("/webhooks/instantreply", express.raw({ type: "application/json" }), (req, res) => { const timestamp = req.header("X-InstantReply-Timestamp") const signature = req.header("X-InstantReply-Signature") const rawBody = req.body.toString("utf8") verifyHmacSha256({ secret: process.env.IR_WEBHOOK_SECRET, payload: timestamp + "." + rawBody, signature, }) res.sendStatus(204) })

Event

متى يحدث

message.received

يرسل العميل رسالة عبر واتساب أو إنستغرام أو ماسنجر.

message.sent

يخرج message من AI أو dashboard أو API أو automation أو journey.

conversation.created

تفتح محادثة جديدة من inbound أو coexistence أو journey.

conversation.closed

تغلق محادثة يدويا أو عبر automation.

conversation.assigned

يتغير owner عبر تعيين يدوي أو rules للتوجيه.

contact.updated

يقوم lead extraction أو CRM sync بتحديث contact.

template.status_update

ترسل Meta تحديث مراجعة أو جودة لtemplate.

message.delivery_failed

يفشل provider أو يرفض التسليم بعد المحاولات.