تخطّ إلى المحتوى الرئيسي

واجهة الرسائل

أرسل رسالة مفردة، وأدر قوالب واتساب التي ترسل منها، واقرأ ما يرسله الناس إليك.

هذه ليست واجهة الحملات. الحملة تستهدف جمهورًا وتُقاس كحملة؛ أما هذه المسارات فترسل رسالة واحدة إلى شخص واحد، للحالات التي لا يصفها الجمهور - تحديث طلب، أو رد دعم، أو تأكيد قرر نظامك إرساله.

كل نقاط النهاية في هذه الصفحة نسبية إلى عنوان الأساس: https://api-eu1.joryio.com/api - راجع نظرة عامة على الـAPI.

المصادقة​

Authorization: Bearer your_api_key_or_jwt
Content-Type: application/json

إرسال واتساب​

إرسال رسالة قالب​

POST /whatsapp/send/template

الشيء الوحيد الذي يمكنك إرساله إلى شخص خارج نافذة محادثة مفتوحة مدتها 24 ساعة. ويجب أن يكون القالب معتمدًا مسبقًا من Meta.

{
  "to": "+306912345678",
  "templateName": "order_shipped",
  "language": "en",
  "variables": { "1": "Alex", "2": "GR-40921" }
}

إرسال رسالة جلسة​

POST /whatsapp/send/text

نص حر، ويُسمح به فقط أثناء فتح نافذة الـ24 ساعة - أي خلال 24 ساعة من آخر رسالة واردة من ذلك الشخص. وخارجها يُعاد 409 وعليك إرسال قالب بدلًا من ذلك. لا يتيح واتساب بدء محادثة بنص حر؛ فإن لم تكن واثقًا، أرسل قالبًا.

{ "to": "+306912345678", "text": "Your order is out for delivery." }

القوالب​

GET /whatsapp/templates
POST /whatsapp/templates

كل القوالب مع حالة اعتمادها. القوالب APPROVED وحدها قابلة للإرسال. والإنشاء يقدّم القالب إلى Meta للاعتماد - وهو ليس فوريًا وقد يُرفض.

{
  "templates": [
    { "name": "order_shipped", "language": "en", "status": "APPROVED",
      "category": "UTILITY", "variables": 2 }
  ]
}

قوالب SMS (Delivyr فقط)​

Delivyr فقط. تعمل هذه المسارات فقط في مساحة عمل رقم SMS فيها مرتبط بحساب Delivyr. ترسل Delivyr القوالب التي اعتمدتها فقط، وإلى أرقام الولايات المتحدة وكندا. في أي مساحة عمل أخرى، تُرجع كل المسارات باستثناء GET /sms/templates/accounts الرمز 403 مع code: "delivyr_account_required":

{ "statusCode": 403, "code": "delivyr_account_required",
  "message": "SMS templates are available only to workspaces that send SMS through a Delivyr account. Connect one under Integrations > Delivyr." }

تتطلب القراءة templates:read، ويتطلب الإنشاء والتحديث والحذف templates:write.

حسابات Delivyr لمساحة العمل​

يُرجع [] عند عدم وجود حساب، حتى يتحقق العميل قبل أي استدعاء آخر. key هو accountKey الذي تقبله المسارات الأخرى.

GET /sms/templates/accounts
[
  { "key": "6f1c2a9e-3b4d-4e5f-8a7b-9c0d1e2f3a4b", "smsAccountId": "6f1c2a9e-3b4d-4e5f-8a7b-9c0d1e2f3a4b",
    "provider": "delivyr", "name": "Delivyr US" }
]

قائمة القوالب​

مرشحات اختيارية: status (pending وapproved وrejected وsystem) وaccountKey. يمكن إرسال قوالب approved وsystem فقط. mappableVariables هي المتغيرات التي تملؤها لكل جهة اتصال، وتملأ Delivyr الباقي (account_dba) بنفسها.

GET /sms/templates?status=approved
[
  { "id": "1d2e3f40-5a6b-4c7d-8e9f-0a1b2c3d4e5f", "accountKey": "6f1c2a9e-3b4d-4e5f-8a7b-9c0d1e2f3a4b",
    "provider": "delivyr", "providerTemplateId": "NMPNWAS6", "title": "We Miss You",
    "body": "Hi {{first_name}}, we miss you: {{link}}", "status": "approved", "source": "portal",
    "variables": ["first_name", "link"], "mappableVariables": ["first_name", "link"] }
]

التحديث من Delivyr​

يجلب الآن قوالب الحساب من Delivyr، بما فيها القوالب المنشأة في بوابة Delivyr، ويحدّث حالة مراجعتها. يحدّث Joryio أيضًا كل 30 دقيقة. جسم اختياري: { "accountKey": "..." }.

POST /sms/templates/sync
{ "results": [ { "accountKey": "6f1c2a9e-3b4d-4e5f-8a7b-9c0d1e2f3a4b", "added": 2, "updated": 5, "removed": 0, "total": 7 } ] }

إنشاء قالب​

يرسل القالب إلى مراجعة Delivyr. يبدأ بحالة pending، وتتغير الحالة بعد المراجعة. استخدم متغيرات {{name}}. ضع {{link}} حيث يجب أن يظهر الرابط، ويملؤه Joryio عند الإرسال برابط قصير متتبَّع خاص به. لا يلزم accountKey إلا عندما ترسل مساحة العمل عبر أكثر من حساب Delivyr واحد. لا يمكن تغيير النص المعتمد، فلتغيير الصياغة أنشئ قالبًا جديدًا.

POST /sms/templates
{
  "title": "Weekend offer",
  "body": "Hi {{first_name}}, your weekend offer is ready: {{link}} Reply STOP to opt out.",
  "tags": ["promo"]
}

جلب قالب أو حذفه​

يحذف الحذف القالب في Delivyr أيضًا. لا يمكن حذف قوالب نظام Delivyr.

GET /sms/templates/:id
DELETE /sms/templates/:id

الاستخدام والحدود​

GET /whatsapp/usage?period=monthly&startDate=2026-08-01&endDate=2026-08-31
GET /whatsapp/usage/limits?wabaId=waba_120363

يحاسب واتساب لكل محادثة مدتها 24 ساعة لا لكل رسالة، لذا فعدد الرسائل لا يتنبأ بالتكلفة. يعيد مسار الاستخدام صفوف الاستخدام المخزنة لحسابات مساحة العمل - صف لكل حساب وفترة، والفترة الأحدث أولًا. المعاملات (كلها اختيارية): wabaId (حساب واحد)، وperiod (daily أو monthly)، وstartDate / endDate (تواريخ ISO؛ الصفوف التي تبدأ فترتها في startDate أو بعده وتنتهي في endDate أو قبله). يحمل كل صف أيضًا organizationId وworkspaceId وcreatedAt وupdatedAt.

[
  {
    "id": "usage_9f2c", "wabaId": "waba_120363", "period": "monthly",
    "periodStart": "2026-08-01", "periodEnd": "2026-08-31",
    "conversations": { "marketing": 4120, "utility": 8802, "authentication": 310, "service": 1904, "total": 15136 },
    "messages": { "sent": 31204, "delivered": 30877, "read": 22410, "failed": 327, "received": 4810 },
    "estimatedCost": 812.4,
    "currency": "USD"
  }
]

يعرض مسار الحدود الفئة التي تسمح بها Meta لرقمك وما استُهلك منها - وبلوغ السقف يُفشل الإرسال ولا يضعه في طابور. wabaId اختياري - وبدونه تكون الحدود حدود الحساب الافتراضي وتعود أرقام الاستخدام الثلاثة بقيمة 0، لأن الاستخدام لا يُبحث عنه إلا لحساب مسمّى.

{
  "tier": "TIER_10K",
  "dailyLimit": 10000,
  "dailyConversations": 3410,
  "monthlyConversations": 41200,
  "monthlyEstimatedCost": 812.4,
  "qualityRating": "GREEN"
}

رسائل جهة الاتصال​

GET /messages?userId=665f1e2a9b3c4d5e6f7a8b9c&direction=outbound&channel=email&limit=50&offset=0

ما أرسلته إلى جهة اتصال وما أرسلته إليك، الأحدث أولًا: كل message.sent من حملة أو رحلة (البريد الإلكتروني وSMS وWhatsApp وPush وViber - وليس عُقد webhook) والردود التي يعيدها GET /messages/inbound. هذه هي علامة تبويب الرسائل في ملف جهة الاتصال.

المعاملالوصف
userIdمطلوب. معرّف جهة الاتصال في Joryio أو externalId الخاص بها. جهة اتصال غير معروفة تعيد صفحة فارغة.
directionاختياري. outbound (المرسلة) أو inbound (الردود)؛ بدونه يعيد الاثنين.
channelاختياري. قناة واحدة، مثل email أو sms أو whatsapp أو push.
limitاختياري. الافتراضي 50، ضمن 1-200.
offsetاختياري. عدد الصفوف المتخطاة، الافتراضي 0، وبحد أقصى 5000.

Response:

{
  "data": [
    { "direction": "outbound", "channel": "email", "eventName": "message.sent",
      "timestamp": "2026-10-28 10:00:00.000", "subject": "Your cart is still here",
      "messageId": "0100019a2b3c", "status": "opened",
      "source": { "kind": "journey", "id": "8f0c2d1e-5b7a-4c3e-9f1a-2d3e4f5a6b7c", "name": "Cart recovery" },
      "body": null, "from": null, "toNumber": null, "account": null, "messageType": null },
    { "direction": "inbound", "channel": "sms", "eventName": "sms.message.received",
      "timestamp": "2026-10-27 18:02:00.000", "body": "thanks!", "from": "+306912345678",
      "toNumber": "+302101234567", "account": "Support line", "messageType": "text",
      "subject": null, "messageId": null, "source": null, "status": null }
  ],
  "total": 2
}

تذكر الرسالة المرسلة في source ما أرسلها (kind هو journey أو campaign، وname يكون null عندما لا يمكن التعرف عليه)، وsubject البريد الإلكتروني، وstatus - أبعد نتيجة سُجّلت للرسالة: sent أو delivered أو opened أو clicked، أو failed / bounced اللتان تتقدمان على غيرهما. يحمل الرد from وtoNumber وaccount وbody كما في /messages/inbound. يقرأ المسار آخر 12 شهرًا؛ وtotal هو حجم الصفحة، لذا تنقّل باستخدام offset حتى تعود صفحة أقصر من limit.

الرسائل الواردة​

GET /messages/inbound?userId=665f1e2a9b3c4d5e6f7a8b9c&channel=whatsapp&limit=50&offset=0
GET /sms/messages?userId=665f1e2a9b3c4d5e6f7a8b9c&limit=50

ما أرسلته جهة اتصال واحدة إليك عبر واتساب والرسائل النصية - تأتي الصفوف من أحداث <channel>.message.received الخاصة بجهة الاتصال. userId (معرّف Joryio لجهة الاتصال، وهو الـ id الذي يعيده Users API) إلزامي - وبدونه يعيد المسار صفحة فارغة. channel يقصر النتائج على قناة واحدة (sms أو whatsapp)؛ وlimit افتراضيه 50 ومحصور بين 1 و200؛ وoffset افتراضيه 0. total هو حجم الصفحة المعادة لا عددًا إجماليًا - صفّح بـ offset حتى تعود صفحة أقصر من limit. لا يوجد مؤشر since في هذا المسار. toNumber هو الرقم الذي وصلت إليه الرسالة وaccount تسمية الحساب المستقبِل؛ وكلاهما null للرسائل المسجلة قبل أن يبدأ ختمهما.

{
  "data": [
    { "channel": "whatsapp", "from": "+306912345678", "toNumber": "+302101234567",
      "account": "Support line", "body": "when will it arrive?", "messageType": "text",
      "eventName": "whatsapp.message.received", "timestamp": "2026-08-27T09:41:00Z" }
  ],
  "total": 1
}

يعيد GET /sms/messages رسائل SMS لجهة اتصال (الخط الزمني في الملف الشخصي)، الأحدث أولًا، كمصفوفة JSON. userId إلزامي - وبدونه يعيد المسار []؛ وlimit افتراضيه 50 ومحصور بين 1 و200. direction إما inbound أو outbound. لا توجد حالة تسليم من المشغّل في هذا المسار - التسليم والفشل أحداث في الخط الزمني لجهة الاتصال (GET /users/:id/events).

[
  { "id": "sms_411", "body": "STOP", "phoneNumber": "+306912345678",
    "direction": "inbound", "messageType": "text", "accountId": "acct_7a1",
    "createdAt": "2026-08-26T18:02:00Z" }
]