الإرسال إلى رقم واحد
تحديثات الطلبات والتذكيرات والإيصالات، قالب واحد إلى عميل واحد.
الرسالة الواحدة هي حملة لها مستلم واحد. استخدمها للرسائل التي يطلقها نظامك عند حدث معين: شحن طلب، أو موعد غدًا، أو استلام دفعة.
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 لترى حالة الرسالة وتوقيتاتها، وسبب فشلها إن فشلت.