انتقل إلى المحتوى
مستندات المطورينتجريبي

الإرسال إلى رقم واحد

تحديثات الطلبات والتذكيرات والإيصالات، قالب واحد إلى عميل واحد.

الرسالة الواحدة هي حملة لها مستلم واحد. استخدمها للرسائل التي يطلقها نظامك عند حدث معين: شحن طلب، أو موعد غدًا، أو استلام دفعة.

curl https://api.mawgood.ai/v1/campaigns \
  -H "Authorization: Bearer $MAWGOOD_API_KEY" \
  -H "Idempotency-Key: order-1042-shipped" \
  -H "Content-Type: application/json" \
  -d '{
    "template": { "name": "order_shipped", "language": "ar" },
    "recipients": [
      {
        "phone": "+201001234567",
        "name": "Mona",
        "externalId": "order-1042",
        "variables": { "body": ["Mona", "#1042"], "buttons": { "0": "1042" } }
      }
    ]
  }'

الحقول

الحقلمطلوبملاحظات
templateنعم{ "id": "tpl_…" } أو { "name": "…", "language": "ar" }. يجب أن يكون معتمدًا.
recipients[].phoneنعمبصيغة E.164 (+201001234567). الرقم المصري المحلي (01001234567) يُقرأ على أنه +20.
recipients[].variablesإذا كان للقالب متغيراتراجع متغيرات القوالب.
recipients[].nameلاحتى 80 حرفًا. يُحفظ في بيانات العميل عندما ينشئه موجود.
recipients[].externalIdلامعرّفك الخاص، حتى 255 حرفًا. يعود في المستلمين وفي الـ webhooks.
fromلامعرّف رقم من GET /numbers. مطلوب فقط إذا كان أكثر من رقم يستطيع إرسال القالب.
scheduledAtلاالإرسال لاحقًا (ISO 8601 مع فرق التوقيت، مثل 2026-12-01T09:00:00+02:00). وقت مضى: الآن.
pacingلا{ "mode": "all_at_once" } أو { "mode": "steady", "overHours": 6 }. راجع توزيع الإرسال.
nameلاحتى 80 حرفًا، ويظهر في لوحة التحكم. الافتراضي اسم القالب.

ترويسة Idempotency-Key

الشبكات تتعطل أحيانًا. إذا انتهت مهلة طلبك، فلن تعرف هل استلمه موجود أم لا. لذلك Idempotency-Key مطلوبة (حتى 255 حرفًا، وبدونها يفشل الطلب بـ 422 validation_failed). ابنها على شيء فريد في نظامك (order-1042-shipped) وأعد المحاولة بلا قلق خلال 24 ساعة:

إعادة المحاولة بالمفتاح نفسهالرد
بالمحتوى نفسه202 بالرد الأول مع الترويسة idempotent-replay: true. لا يُرسل شيء مرة أخرى.
بمحتوى مختلف409 idempotency_conflict.
والطلب الأول ما زال يعمل409 idempotency_in_progress: انتظر قليلًا وأعد المحاولة.

الطلب المرفوض (أي خطأ 4xx) يحرر مفتاحه، فتستطيع تصحيحه وإرساله مرة أخرى بالمفتاح نفسه.

ماذا يحدث عند العميل

  • الرقم الذي لم يتعامل معه موجود من قبل يصبح عميلًا بوسم api (باسمه إن أرسلت name).
  • تظهر الرسالة في محادثة العميل داخل صندوق الوارد في موجود.
  • عندما يرد العميل، يرد عليه الموجود الخاص بك بتعليماتك ومعرفتك، ويستطيع فريقك التدخل من صندوق الوارد. وتصلك أيضًا webhook من نوع message.replied.

المتابعة

قيمة id في الاستجابة هي الحملة. استمع إلى الـ webhooks (وهو الأفضل)، أو اقرأ GET /campaigns/{id}/recipients لترى حالة الرسالة وتوقيتاتها، وسبب فشلها إن فشلت.

في هذه الصفحة