REST API · v1.
واتساب + إنستغرام
Bearer auth. Cursor pagination. Idempotency keys. Webhooks موقّعة. الـ API التي كان فريقك سيبنيها لو امتلك عطلة نهاية الأسبوع.
اختر بيئة التشغيل
const API_BASE = process.env.IR_API_URL ?? 'https://api.instantreply.co';
const headers = { 'Authorization': `Bearer ${process.env.IR_API_KEY}` };
const res = await fetch(`${API_BASE}/v1/conversations?status=active`, { headers });
const { data } = await res.json();
for (const c of data) {
if (c.last_message_preview?.includes('refund')) {
await fetch(`${API_BASE}/v1/conversations/${c.id}`, {
method: 'PATCH', headers: { ...headers, 'Content-Type': 'application/json' },
body: JSON.stringify({ tags: ['priority:refund'] }),
});
}
}سطح v1
مسارات رئيسية وهيدر مصادقة واحد.
- GET
/v1/conversations - 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 - GET
/v1/contacts - GET
/v1/contacts/:id - PATCH
/v1/contacts/:id - GET
/v1/channels - GET
/v1/analytics/summary - GET
/v1/usage - GET
/v1/keys - POST
/v1/keys - POST
/v1/keys/:id/rotate - DELETE
/v1/keys/:id - GET
/v1/webhooks - POST
/v1/webhooks - DELETE
/v1/webhooks/:id - GET
/v1/webhooks/:id/deliveries - POST
/v1/webhooks/send - POST
/v1/webhooks/trigger-campaign - POST
/v1/webhooks/sign-payload - GET
/v1/journeys - POST
/v1/trigger - GET
/v1/trigger/status/:id - GET
/v1/trigger/history - POST
/v1/trigger/validate - POST
/v1/trigger/batch - DELETE
/v1/trigger/enrollments - POST
/v1/events - GET
/v1/templates - POST
/v1/templates - GET
/v1/templates/:id - POST
/v1/templates/generate/validate - POST
/v1/templates/:id/validate - POST
/v1/templates/:id/submit - GET
/v1/campaigns - POST
/v1/campaigns - GET
/v1/campaigns/:id - PATCH
/v1/campaigns/:id - POST
/v1/campaigns/:id/send - GET
/v1/pipeline/leads - GET
/v1/pipeline/leads/:id - PATCH
/v1/pipeline/leads/:id - PATCH
/v1/pipeline/leads/:id/stage - GET
/v1/pipeline/stages - GET
/v1/automations - GET
/v1/automations/:id - POST
/v1/automations/:id/trigger - GET
/v1/comments - GET
/v1/comments/:id - POST
/v1/comments/:id/reply - GET
/v1/developer/capabilities - GET
/v1/developer/onboarding - GET
/v1/developer/limits - GET
/v1/developer/troubleshooting/errors/:code
التصميم
خيارات مملّة، عن قصد.
- 01
Cursor pagination، دائمًا
كل endpoint قائمة يُرجع has_more وnext_cursor. لا سجلات مفقودة تحت الحمل، لا off-by-one.
- 02
Idempotency-Key على POST
مرّر UUID وأعد المحاولة بأمان لمدة 24 ساعة. تنطلق الآثار الجانبية مرة واحدة فقط.
- 03
X-Request-Id في كل ردّ
أَلصِق المعرّف في الدعم ونتتبّع النداء بالضبط، والردّ بالضبط، والنداء التابع بالضبط.
- 04
أخطاء بشكل ثابت
نفس غلاف JSON في كل فشل. code وmessage وdoc_url وrequest_id. بلا null مفاجئ.
الأخطاء
غلاف واحد، في كل مرّة.
بلا أعلام نجاح متداخلة. بلا خلط حالة الأحرف. بلا 200 صامت عند الفشل. إذا انكسر النداء، يخبرك الجسم بالضبط أي نداء وماذا توقّع وأين الوثائق.
// 422 Unprocessable Entity
{
"error": {
"code": "INVALID_PLATFORM",
"message": "Channel 'tiktok' is not yet supported on v1.",
"doc_url": "https://www.instantreply.co/api-docs#errors",
"request_id": "req_8f2a0b1c"
}
}Webhooks
سجّل مرة واحدة. احفظ السر الآن.
POST /v1/webhooks مع رابط الـ endpoint والأحداث. تُعيد الاستجابة signing secret يبدأ ب whsec_ مرة واحدة فقط — لا يُخزَّن بصيغة قابلة للقراءة ولا يُعرض مجددا. انسخه إلى INSTANTREPLY_WEBHOOK_SECRET. فقدته؟ لا يوجد endpoint لاستعادته: احذف الـ webhook وسجّل واحدا جديدا للحصول على سر جديد.
// POST /v1/webhooks (scope: webhooks:write)
// Request
{
"url": "https://your-app.com/instantreply/webhook",
"events": ["*"],
"description": "Inbound events"
}
// 201 Created — the secret is returned ONCE, here only.
{
"id": "b1e7…",
"url": "https://your-app.com/instantreply/webhook",
"events": ["*"],
"secret": "whsec_9f2c…" // ← store this now; never shown again
}