app2email API الأسعار

التوثيق

Submit-Info

دليل Submit-Info: ابنِ نموذجًا من قائمة أسئلة، وانشره على WhatsApp وعلى صفحة ويب، وعالج الطلبات المرسلة عبر مراحل في صندوق وارد مشترك بأدوار، وأتمت الردود والاستدعاءات إلى أنظمتك الخاصة، وأعدّ كل شيء عبر API أو وكيل ذكاء اصطناعي.

تكتب النموذج قائمةً بسيطة من الأسئلة. يحوّلها app2email إلى نموذج داخل WhatsApp وإلى صفحة ويب بالخطوات نفسها. يملؤه عميل، أو أحد موظفيك الميدانيين، ويحصل على رقم مرجعي. وتصبح الإجابات والملفات طلبًا مرسلًا (submission) في صندوق وارد مشترك، حيث ينتقل عبر مراحلك ويشغّل أتمتاتك.

فكرة واحدة

نموذج، ثم طلب مرسل، ثم مراحل، ثم أتمتة، ثم اتصالات. طلب عرض سعر، وطلب توظيف، وقراءة عدّاد، وبلاغ عن مشكلة، وعمل منجز، وإثبات تسليم، وإيصال مصروفات: كلها الشيء نفسه بأسئلة مختلفة وأسماء مراحل مختلفة. ويأتي كل منها قالبًا يمكنك تثبيته وتغييره.

ابدأ في خمس دقائق

  1. افتحه: في لوحة التحكم افتح صفحة Submit-Info (/dashboard/app/submit، وتُفتح أيضًا من Integrations). فعّله.
  2. أنشئ نموذجًا: اختر «New form» واختر قالبًا، أو ابدأ فارغًا. أعطه اسمًا واكتب أسئلتك. كل سؤال صف واحد: نصه ونوعه وهل يجب الإجابة عنه.
  3. انشر: «Publish to WhatsApp» يرفع النموذج إلى WhatsApp ويجعله حيًّا. وصفحة الويب بالخطوات نفسها تكون حية فورًا.
  4. شارك: تحت Share تجد الكلمة التي تفتح النموذج في محادثتك، ورابطًا يفتح محادثتك وفيها تلك الكلمة مكتوبة، وعنوان صفحة الويب، ورمز QR، ومقتطفًا لوضع النموذج على موقعك الخاص.
  5. اعمل على صندوق الوارد: تصل الطلبات الجديدة إلى Inbox. افتح أحدها، وغيّر مرحلته، وردّ. وادعُ فريقك عندما تكون جاهزًا.

لا يتغير شيء لرقم لا يفتح Submit-Info أبدًا. والنموذج الذي لم يُنشر بعد على WhatsApp يعمل مع ذلك: تجيب كلمته برابط صفحة الويب.

منشئ النماذج

للنموذج من 1 إلى 12 خطوة، وللخطوة عنوان ومن 1 إلى 12 سؤالًا. لا توجد لوحة رسم ولا شيء ترسمه: القائمة نفسها تقود النموذج على WhatsApp، وصفحة الويب، وفحوص الإجابات، وأعمدة عرض الجدول، والتصدير، وAPI. وتعرض المعاينة بجانب المحرر النموذج كما يراه الشخص.

النوعما يعطيه الشخصما يمكنك ضبطه
textإجابة قصيرةأقصر طول وأطوله، ونمط (pattern)
textareaإجابة أطولأقصر طول وأطوله
numberرقمأدنى قيمة وأعلاها، والكسور العشرية، ووحدة مثل kWh
emailعنوان بريد إلكتروني
phoneرقم هاتف
dateتاريخكم يومًا إلى الوراء أو الأمام يُسمح به
selectاختيار واحدالخيارات (من 2 إلى 200)، أو قائمة من قوائمك
multiselectعدة خياراتالخيارات (من 2 إلى 20)، وأقل عدد وأكثره للتحديد
yesnoنعم أو لا
ratingدرجة من 1 حتى 3-10أعلى درجة
consentجملة يوافق عليهاهل يجب تحديدها
photoصورة واحدة أو أكثركم صورة (من 1 إلى 10)؛ الكاميرا أو المعرض أو أيهما
documentملف واحد أو أكثركم ملفًا (من 1 إلى 10)؛ أي ملف، أو PDF، أو صور، أو ملفات office
locationمكان وجود الشخصعلى WhatsApp طلب الموقع؛ وعلى الويب زر وسطر عنوان
infoنص تعرضهلا يُطلب ولا يُخزَّن شيء
hiddenقيمة تأتي مع الرابطمثل رقم عمل؛ ولا يُعرض شيء
  • نص المساعدة والقيم الافتراضية: يمكن أن يحمل كل سؤال تلميحًا قصيرًا وقيمة افتراضية. ويمكن للقيمة الافتراضية أن تستخدم ما تعرفه أصلًا، مثل {contact.name}.
  • أظهر فقط عندما: يمكن أن تعتمد خطوة أو سؤال على إجابة سابقة («أظهر هذه الخطوة فقط عندما تكون المشكلة Yes»). ويتبع WhatsApp وصفحة الويب القاعدة نفسها.
  • الحقول الداخلية: حقول لا تُسأل أبدًا. يملؤها فريقك أو أتمتة: مبلغ عرض السعر، وسبب القرار، ومعرّف عاد من نظام آخر. وتظهر في صندوق الوارد وفي التصدير فقط.
  • القوائم: يمكن لسؤال الاختيار أن يأخذ خياراته من قائمة من قوائمك (مواقع، وأعمال، ومنتجات بأسعار). غيّر القائمة في لوحة التحكم أو عبر API فيتبعها النموذج، دون حاجة إلى النشر مرة أخرى.
  • القيم المحسوبة: صيغة على الإجابات، لتقدير فوري أو لفحص. راجع الصيغ.
  • بعد الإرسال: شاشة مراجعة قبل الإرسال، والرد مع الرقم المرجعي، وزر «Add more» الذي يلحق الرسائل التالية (نصًا وصورًا وملفات) بالطلب لمدة عشر دقائق، ورابط صفحة حالة الشخص الخاصة به.
  • النشر: يكتب app2email نموذج WhatsApp نيابة عنك، ويقسّم خطوة طويلة على عدة شاشات عندما تتطلب حدود WhatsApp ذلك، ويحتفظ بآخر خمسة إصدارات منشورة حتى تفتح الرسالة الأقدم النموذج الذي أُرسلت به.

صفحة الويب. الخطوات نفسها على /form/your-code/form-key. تطلب الاسم ورقم WhatsApp في النهاية. وبعد الإرسال يرى الشخص الرقم المرجعي ويستطيع الضغط على «Get updates on WhatsApp»، الذي يؤكد رقمه برسالة واحدة؛ ويمكن ضبط نموذج ليشترط ذلك. والرابط الشخصي (الذي ترسله أنت) يعرف أصلًا من هو الشخص. ولوضع النموذج على موقعك الخاص، استخدم المقتطف تحت Share؛ وإذا كان النموذج يطلب موقعًا، فأضف allow="geolocation" إلى iframe. وتُصغَّر الصور في المتصفح قبل رفعها؛ ويمكن أن يصل حجم الملف إلى 10 MB.

كيف يصل الناس إلى نموذج

  • كلمة: لكل نموذج كلماته الخاصة. الكلمات form وforms وreport وsubmit (يمكنك تغييرها) تسرد نماذجك قائمةً عندما يوجد عدة نماذج. ولا تُحتسب الكلمة إلا في رسالة قصيرة: فيها أقل من 10 كلمات أخرى (Settings، «تجاهل الكلمات في الرسائل الطويلة»)، فلا تبدأ شيئًا رسالة طويلة تحتوي عليها مصادفةً.
  • رابط أو رمز QR: رابط يفتح محادثة WhatsApp الخاصة بك مع كلمة النموذج، أو عنوان صفحة الويب.
  • يرسله أنت: «Send form» في صندوق الوارد، أو API، يرسل نموذجًا إلى رقم واحد، مع قيم مملوءة مسبقًا (رقم عمل، أو حساب، أو المستندات التي تريدها).
  • متابعة: تطلب أتمتة أو أحد أعضاء الفريق المزيد بنموذج ثانٍ. وما يعود يُلحق بالطلب الأول.
  • صفحة الويب، وAPI للأنظمة التي تحتفظ أصلًا بالبيانات.

من يستطيع الإرسال. أي شخص (الاختيار المعتاد)، أو الأرقام التي تسردها فقط، أو جهات الاتصال التي لها وسم من وسومك. وهكذا يبقى النموذج لموظفيك الميدانيين. وتجيب الكلمة status الشخص بمرحلة طلباته الأخيرة.

المراحل

تنتمي المراحل إلى النموذج. يبدأ النموذج الجديد بـ New وIn progress وDone؛ أعد تسميتها، وأضف مراحلك (من 2 إلى 12)، واختر لونًا. وكل مرحلة من ثلاثة أنواع: مفتوحة، أو منجزة، أو ملغاة.

  • من يستطيع اختيارها: خصّص مرحلة لأدوار معينة. يجهّز الـ Agent، ولا يوافق إلا الـ Manager.
  • ملاحظة مطلوبة: اطلب سببًا عند نقل طلب إليها (مرفوض، مردود، مستفسَر عنه).
  • رسالة: نص يُرسل إلى الشخص عندما يصل طلبه إلى المرحلة، مع عناصر نائبة.
  • أزرار للشخص: يمكن أن يحمل الرد حتى ثلاثة أزرار (Accept وDecline و«Not fixed yet»)، ويحرّك كل منها المرحلة. هذه القطعة الواحدة تعطيك قبول عرض السعر، وتأكيد الزيارة، و«هل أُصلح؟».

الرد المكتوب خارج مدة الرد في WhatsApp يُحفظ ويُسلَّم عندما يكتب الشخص في المرة القادمة. ويذكر صندوق الوارد ذلك على الرد.

صندوق الوارد والأدوار

يعرض Inbox: Open وMine وUnassigned وDone وAll، إضافة إلى العروض التي تحفظها. ابحث ورشّح حسب النموذج والمرحلة والمكلَّف والوسم والقناة والتاريخ. ثلاثة تخطيطات: قائمة، وجدول (نموذج واحد: كل سؤال عمود)، ولوحة (نموذج واحد: عمود لكل مرحلة). حدّد عدة صفوف لتغيير المرحلة أو التكليف أو الوسم أو التصدير أو الحذف معًا.

يعرض الطلب إجاباته وملفاته ومن أين أُرسل، وسجلًّا واحدًا لكل ما حدث له: تغييرات المرحلة مع من فعلها ولماذا، والملاحظات، والردود في الاتجاهين، والملفات، وكل خطوة أتمتة مع نتيجتها. وفي الأسفل تكتب إما ملاحظة داخلية أو ردًّا على WhatsApp. صدّر أي عرض بصيغة CSV أو Excel أو JSON، وطلبًا واحدًا بصيغة PDF.

فريقك. ادعُ أشخاصًا بالبريد الإلكتروني إلى صندوق الوارد فقط. يحصلون على تطبيق خفيف خاص بهم على /desk ولا يرون بقية حسابك أبدًا. والدور مجموعة قدرات تُبدأ بها، ويمكن تشغيل كل قدرة أو إيقافها لشخص واحد.

الدوريبدأ بـ
Owner وAdminكل شيء، بما فيه النماذج والأتمتة والاتصالات والفريق
Managerالملاحظات والردود وتعديل الإجابات وتغيير المرحلة والتكليف والملفات والتصدير والحذف وتشغيل الإجراءات اليدوية
Agentالملاحظات والردود وتعديل الإجابات وتغيير المرحلة والملفات وتشغيل الإجراءات اليدوية. ويستطيع أن يأخذ طلبًا لنفسه
Viewerيستطيع القراءة، ولا شيء غير ذلك

ويمكنك أيضًا تضييق ما يراه الشخص: بعض النماذج فقط، أو ما كُلِّف به فقط (مع الطلبات غير المكلَّفة لالتقاطها أو بدونها)، وإخفاء بيانات الاتصال. وكل إجراء من عضو في الفريق يُكتب في سجل الطلب.

صفحة الشخص الخاصة. لكل طلب صفحة خاصة على /s/a-long-code، دون تسجيل دخول: المرحلة، والرسائل وتغييرات المرحلة حتى الآن، وسؤالك المفتوح مع أزراره، و«Add information» عندما يسمح النموذج. والملاحظات الداخلية والحقول الداخلية لا تكون عليها أبدًا.

الخصوصية. محو جهة اتصال يمحو طلباتها وملفاتها. ويمكن أن يكون للنموذج مدة احتفاظ، تُمحى بعدها الطلبات المغلقة.

الأتمتة

تُقرأ الأتمتة جملةً: عندما يحدث شيء، إذا تحققت أشياء، افعل هذه الأشياء بالترتيب. «عندما يُرسل Quote request، إذا كانت الكمية 20 أو أكثر، كلّفه للـ Managers وأرسل بريدًا إلى المالك.»

عندماتعمل حين
submittedيكتمل طلب وتصل ملفاته
status_changedتتغير المرحلة (اختياريًا: إلى مراحل معينة أو منها)
assignedيتغير الشخص المكلَّف
updatedعُدّلت الإجابات أو الحقول الداخلية
note_addedكتب عضو في الفريق ملاحظة
file_addedأُضيف ملف لاحقًا
customer_repliedأضاف من أرسله نصًا أو ملفات
buttonضغط الشخص زرًّا من أزرار أحد ردودك
overdueبقي في المرحلة نفسها بعد عدد من الدقائق
dueمضى موعد استحقاقه وهو مفتوح
manualيضغط عضو في الفريق زر الإجراء على الطلب

إذا: قواعد على الإجابات والقيم المحسوبة والمرحلة والقناة والوسوم والمكلَّف. القاعدة حقل ومعامل وقيمة: equals وnot_equals وin وnot_in وcontains وempty وnot_empty وgt وgte وlt وlte. اربط القواعد بـ all (و) أو any (أو).

افعلما يفعله
set_statusينقله إلى مرحلة، مع ملاحظة
assignإلى عضو، أو بالتناوب على دور، أو إلى الأقل انشغالًا في دور، أو إلى لا أحد
set_field, calculateيكتب حقلًا داخليًا، أو يحسب واحدًا بصيغة
tag, set_priority, set_dueالوسوم والأولوية وموعد الاستحقاق
replyرسالة WhatsApp إلى الشخص، مع حتى 3 أزرار يحرّك كل منها المرحلة، أو ملف، أو رابط صفحة حالته
ask_locationيطلب من الشخص مشاركة مكان وجوده
send_formيرسل نموذج متابعة؛ وما يعود يُلحق بهذا الطلب
emailإلى المالك أو المكلَّف أو الشخص أو أي عنوان، مع إرفاق الملفات
notifyبريد إلكتروني إلى المكلَّف أو دور أو كل أعضاء الفريق
http, openapi, mcpيستدعي اتصالًا ويحتفظ بأجزاء من الجواب في حقول
waitيتابع لاحقًا، فقط إذا بقيت الشروط قائمة
stopينتهي هنا

يُسجَّل كل تشغيل خطوة بخطوة: ما أُرسل، وما عاد، وكم استغرق. يشغّل «Try with a submission» أتمتة على طلب حقيقي دون تغيير أو إرسال أي شيء. والاستدعاء الفاشل إلى نظام خارجي يُعاد بعد دقيقة واحدة وبعد 10 دقائق وبعد ساعة؛ وبعد ذلك تُعلَّم الأتمتة فاشلة وتتلقى webhooks الخاصة بك submit.automation_failed. والأتمتات التي تشغّل بعضها بعضًا تتوقف بعد ثلاثة مستويات.

الوصفة 1: عروض الأسعار الكبيرة تذهب إلى مدير

{
  "name": "Large quotes go to a manager",
  "form": "quote_request",
  "enabled": true,
  "trigger": "submitted",
  "options": {},
  "conditions": {
    "all": [
      {
        "field": "quantity",
        "gte": 20
      }
    ]
  },
  "actions": [
    {
      "type": "assign",
      "to": "role:manager"
    },
    {
      "type": "set_priority",
      "priority": "high"
    },
    {
      "type": "email",
      "to": [
        "owner"
      ],
      "subject": "Large quote {reference}",
      "body": "{contact.name} asked for a quote.\n\n{answers}\n\n{desk_link}",
      "attach_files": true
    }
  ]
}

الوصفة 2: أرسل عرض السعر، واطلب جوابًا، وذكّر بعد ثلاثة أيام

quote_amount حقل داخلي يملؤه فريقك قبل نقل الطلب إلى Quoted. ولا يُرسل التذكير إلا إذا بقي الطلب في Quoted.

{
  "name": "Send the quote and ask for an answer",
  "form": "quote_request",
  "enabled": true,
  "trigger": "status_changed",
  "options": {
    "to": [
      "quoted"
    ],
    "from": []
  },
  "conditions": {
    "field": "status",
    "equals": "quoted"
  },
  "actions": [
    {
      "type": "reply",
      "text": "Your quote {reference}: {quote_amount}. Would you like to go ahead?",
      "link": true,
      "buttons": [
        {
          "id": "accept",
          "title": "Accept",
          "set_status": "accepted"
        },
        {
          "id": "decline",
          "title": "Decline",
          "set_status": "declined"
        }
      ]
    },
    {
      "type": "wait",
      "minutes": 4320
    },
    {
      "type": "reply",
      "text": "A reminder about your quote {reference}. Tap Accept or Decline, or write to us with any question."
    }
  ]
}

الوصفة 3: اعزل قراءة عدّاد تبدو خاطئة

usage قيمة محسوبة: reading - previous('reading').

{
  "name": "Query a reading that looks wrong",
  "form": "meter_reading",
  "enabled": true,
  "trigger": "submitted",
  "options": {},
  "conditions": {
    "any": [
      {
        "field": "usage",
        "lt": 0
      },
      {
        "field": "usage",
        "gt": 2000
      }
    ]
  },
  "actions": [
    {
      "type": "set_status",
      "status": "queried",
      "note": "Usage {usage} kWh is outside the usual range."
    },
    {
      "type": "notify",
      "to": "role:manager",
      "text": "Reading {reference} for meter {meter_no} needs a check: usage {usage} kWh."
    }
  ]
}

الاتصالات

الاتصال هو نظام خارجي يمكن لأتمتة أن تستدعيه. لا تحتاج webhooks حسابك إلى أي منها: فهي تستقبل كل حدث للطلبات فور وقوعه (راجع الأحداث). ولكل ما عدا ذلك ثلاثة أنواع. يعرض «Test» على اتصال، و«Try with a submission» على إجراء، الطلب الحقيقي والجواب الحقيقي قبل تشغيل أي شيء.

طلب HTTP

عنوان أساسي وطريقة لتسجيل الدخول (لا شيء، أو bearer token، أو ترويسة، أو اسم مستخدم وكلمة مرور، أو مفتاح في العنوان). ويحدد الإجراء الطريقة (method) والمسار وجسم JSON. ويحتفظ save بأجزاء من الجواب في حقول الطلب.

{
  "key": "billing",
  "name": "Billing",
  "kind": "http",
  "base_url": "https://billing.example.com/api",
  "auth": {
    "type": "bearer",
    "secret": "YOUR_BILLING_TOKEN"
  },
  "enabled": true
}
{
  "type": "http",
  "connection": "billing",
  "method": "POST",
  "path": "/readings",
  "body": {
    "meter": "{meter_no}",
    "reading": "{reading}",
    "usage": "{usage}",
    "reference": "{reference}",
    "photo": "{files.photo}"
  },
  "save": {
    "billing_id": "$.id"
  },
  "on_fail": "retry"
}

مستند OpenAPI

أعطِ عنوان مستند OpenAPI 3 بصيغة JSON، أو الصقه. يقرأ app2email عملياته؛ ويختار الإجراء واحدة بمعرّفها ويملأ معاملاتها. ولا تُقرأ مستندات YAML وSwagger 2.

{
  "key": "helpdesk",
  "name": "Helpdesk",
  "kind": "openapi",
  "base_url": "https://helpdesk.example.com/api",
  "spec_url": "https://helpdesk.example.com/openapi.json",
  "auth": {
    "type": "header",
    "name": "X-Api-Token",
    "secret": "YOUR_HELPDESK_TOKEN"
  },
  "enabled": true
}
{
  "type": "openapi",
  "connection": "helpdesk",
  "operation": "createTicket",
  "params": {
    "title": "Problem {reference}: {category}",
    "description": "{description}",
    "reporter": "{contact.phone}"
  },
  "save": {
    "ticket_id": "$.id"
  },
  "on_fail": "retry"
}

خادم MCP

أعطِ عنوان خادم MCP (streamable HTTP) ورمزه المميز. يسرد app2email أدوات الخادم؛ ويختار الإجراء واحدة منها ويملأ وسائطها. ويحتفظ $text بجواب الأداة كاملًا نصًّا.

{
  "key": "dispatch",
  "name": "Dispatch",
  "kind": "mcp",
  "base_url": "https://dispatch.example.com/mcp",
  "auth": {
    "type": "bearer",
    "secret": "YOUR_DISPATCH_TOKEN"
  },
  "enabled": true
}
{
  "type": "mcp",
  "connection": "dispatch",
  "tool": "close_job",
  "arguments": {
    "job_id": "{job}",
    "summary": "{work_done}",
    "minutes": "{time_spent}",
    "photos": "{files.photos}"
  },
  "save": {
    "dispatch_answer": "$text"
  },
  "on_fail": "continue"
}

من المفيد أن تعرف. القيمة التي هي عنصر نائب واحد بالضبط تحتفظ بنوعها (الرقم يبقى رقمًا، والقائمة تبقى قائمة). تُخزَّن الأسرار مشفّرة، ولا تُعرض مرة أخرى، ولا يُرجعها API أبدًا. ويجب أن تكون العناوين https وعامة: العناوين الخاصة والمحلية والداخلية تُرفض، ولا تُتبع عمليات إعادة التوجيه. وقد يستغرق الاستدعاء 15 ثانية، وقد يبلغ جوابه 256 KB. وفي save، المسار هو $ (الجواب كله) أو مسار عادي مثل $.data.items[0].id.

العناصر النائبة

يمكن لكل نص ولكل معامل في إجراء أن يستخدم عناصر نائبة بين أقواس معقوفة. والاسم غير المعروف يبقى كما كتبته.

العنصر النائبيصبح
{<field key>}الإجابة عن ذلك السؤال (وكذلك الحقول الداخلية والقيم المحسوبة والقيم التي حفظتها أتمتة)
{reference}الرقم المرجعي، مثلًا MR-7Q3M2A
{form} {form_key}اسم النموذج ومفتاحه
{status} {status_name}مفتاح المرحلة واسمها
{channel}whatsapp أو web أو api أو staff
{priority} {tags}الأولوية والوسوم
{created} {updated} {due}الأوقات
{contact.name} {contact.phone} {contact.email}من أرسله
{assignee.name} {assignee.email}عضو الفريق المكلَّف به
{link}صفحة حالة الشخص الخاصة
{desk_link}الطلب في صندوق وارد فريقك
{answers}كل الإجابات في أسطر «Label: value»
{files} {files.<field key>}روابط كل الملفات، أو ملفات سؤال واحد؛ ويستطيع نظام آخر جلبها لمدة 7 أيام
{note}ملاحظة تغيير المرحلة، أو الملاحظة التي شغّلت الأتمتة
{button}الزر الذي ضغطه الشخص
{business}اسم نشاطك التجاري
{submission}في جسم JSON: الطلب كله ككائن
{= formula }صيغة تُحسب في مكانها، مثلًا {= round(qty * 1.1, 2) }

الصيغ

تستخدمها القيم المحسوبة، والإجراء calculate، وما بداخل {= ... } في أي نص. تعمل الصيغة مع الأرقام والنصوص بين علامتي اقتباس مفردتين ومفاتيح أسئلتك. ويمكن أن يبلغ طولها 500 حرف. والقسمة على صفر، أو رقم مفقود، يعطيان قيمة فارغة بدل خطأ.

ما تكتبهالمعنى
+ - * / %عمليات حسابية على الأرقام والإجابات
== != > >= < <=مقارنات
and or not ( )منطق وأقواس
if(condition, a, b)a عندما يتحقق الشرط، وإلا b
min(a, b, ...) max(a, b, ...)الأصغر والأكبر
round(x, n) abs(x)التقريب إلى n منازل عشرية، وحجم الرقم دون إشارته
num(x) len(x)نص كرقم؛ وطول نص أو قائمة
coalesce(a, b)a، أو b عندما تكون a فارغة
lower(x) upper(x) concat(a, b, ...)نصوص
lookup('list', id, 'column')عمود من صف في إحدى قوائمك، مثلًا سعر
previous('field')آخر إجابة للشخص نفسه عن ذلك السؤال
count_files('field')كم ملفًا يحمل سؤال
days_since(date)الأيام من تاريخ حتى اليوم

أمثلة: qty * lookup('prices', product, 'price') لتقدير فوري؛ وreading - previous('reading') للاستهلاك؛ وif(amount > 500, 'manager', 'agent') لتحديد من يوافق.

للمطورين ووكلاء الذكاء الاصطناعي

كل ما سبق موجود في REST API تحت /v1/{number}/submit، حيث {number} هو رقم WhatsApp الخاص بك مع رمز الدولة، وأرقام فقط. أرسل مفتاح API الخاص بك بصيغة Authorization: Bearer YOUR_API_KEY (وتُقبل أيضًا الترويسة X-API-KEY). يحتاج المفتاح إلى الصلاحية submissions:manage؛ والمفاتيح ذات الوصول الكامل تملكها، والمفتاح الافتراضي (Default) لا يملكها. ولا تستطيع مفاتيح sandbox الكتابة.

  1. GET /submit/guide: مستند JSON واحد فيه المفردات كلها: أنواع الأسئلة مع خياراتها وحدودها، وقواعد المراحل، والمشغّلات، والمعاملات (operators)، والإجراءات مع معاملاتها، والعناصر النائبة، ودوال الصيغ، والقوالب، وأمثلة عملية.
  2. POST /submit/setup مع "dry_run": true: لا يُكتب شيء؛ وتعود كل مشكلة مع مسارها وجملة تقول كيف تصلحها.
  3. POST /submit/setup دون dry_run: تُطبَّق القوائم والاتصالات والنماذج والأتمتات معًا. ومع أي مشكلة لا يُكتب شيء.
  4. POST /submit/forms/{key}/publish، أو سمِّ النماذج في "publish" من مستند الإعداد.
  5. شارك روابط النموذج (يعيدها GET /submit/forms/{key})، ثم اقرأ GET /submit/submissions أو استمع إلى أحداث webhook.

استدعاء إعداد كامل

احفظ المستند أدناه باسم setup.json وأرسله بـ post. استبدل 61400000000 برقمك. يفحص حلًّا لقراءة العدّادات: قائمة مواقع، واتصالًا بنظام فوترة، ونموذجًا واحدًا بثلاث مراحل واستهلاكًا محسوبًا، وأتمتتين. أزل "dry_run": true لتطبيقه. تُستبدل النماذج والقوائم والاتصالات الموجودة التي لها المفتاح نفسه؛ وتُطابَق الأتمتات بالاسم داخل النموذج. و"preset": "..." بدل الأجزاء يثبّت أحد القوالب (يسردها GET /submit/presets).

curl -X POST "https://api.app2email.com/v1/61400000000/submit/setup" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d @setup.json
{
  "dry_run": true,
  "settings": {
    "enabled": true,
    "config": {
      "business_name": "Northside Energy",
      "default_prefix": "NE"
    }
  },
  "lists": [
    {
      "key": "sites",
      "name": "Sites",
      "items": [
        {
          "id": "north",
          "title": "North depot"
        },
        {
          "id": "south",
          "title": "South depot"
        }
      ]
    }
  ],
  "connections": [
    {
      "key": "billing",
      "name": "Billing",
      "kind": "http",
      "base_url": "https://billing.example.com/api",
      "auth": {
        "type": "bearer",
        "secret": "YOUR_BILLING_TOKEN"
      },
      "enabled": true
    }
  ],
  "forms": [
    {
      "key": "meter_reading",
      "name": "Meter reading",
      "definition": {
        "title": "Meter reading",
        "description": "Send us your reading. It takes about a minute.",
        "prefix": "MR",
        "steps": [
          {
            "key": "reading",
            "title": "Your reading",
            "text": "",
            "show_if": null,
            "fields": [
              {
                "key": "site",
                "type": "select",
                "label": "Site",
                "required": true,
                "list": "sites"
              },
              {
                "key": "meter_no",
                "type": "text",
                "label": "Meter number",
                "help": "Printed on the front of the meter",
                "required": true,
                "max_length": 30
              },
              {
                "key": "reading",
                "type": "number",
                "label": "Reading",
                "required": true,
                "min": 0,
                "decimals": 0,
                "unit": "kWh"
              },
              {
                "key": "photo",
                "type": "photo",
                "label": "Photo of the meter",
                "required": false,
                "max_files": 1,
                "source": "any"
              },
              {
                "key": "billing_id",
                "type": "text",
                "label": "Billing record",
                "internal": true
              }
            ]
          }
        ],
        "stages": [
          {
            "key": "received",
            "name": "Received",
            "kind": "open",
            "color": "blue",
            "set_by": [],
            "require_note": false,
            "message": ""
          },
          {
            "key": "queried",
            "name": "Queried",
            "kind": "open",
            "color": "amber",
            "set_by": [],
            "require_note": true,
            "message": "We have a question about your reading {reference}. We will be in touch."
          },
          {
            "key": "checked",
            "name": "Checked",
            "kind": "done",
            "color": "green",
            "set_by": [],
            "require_note": false,
            "message": ""
          }
        ],
        "who": {
          "mode": "anyone",
          "numbers": [],
          "tag": ""
        },
        "trigger": {
          "words": [
            "meter",
            "reading"
          ],
          "header": "",
          "body": "Tap the button to send your reading.",
          "button": "Open form",
          "footer": ""
        },
        "after": {
          "review_step": true,
          "reply": "Thanks {contact.name}. We have your reading - reference {reference}.",
          "allow_additions": false,
          "status_page": true
        },
        "web": {
          "enabled": true,
          "verify": "optional",
          "ask_email": false,
          "success_text": "Thank you. We have your reading."
        },
        "notify": {
          "email": true,
          "to": [],
          "attach_files": true
        },
        "calculated": [
          {
            "key": "usage",
            "label": "Usage",
            "formula": "reading - previous('reading')",
            "unit": "kWh",
            "decimals": 0
          }
        ],
        "retention_days": 0
      }
    }
  ],
  "automations": [
    {
      "name": "Query a reading that looks wrong",
      "form": "meter_reading",
      "enabled": true,
      "trigger": "submitted",
      "options": {},
      "conditions": {
        "any": [
          {
            "field": "usage",
            "lt": 0
          },
          {
            "field": "usage",
            "gt": 2000
          }
        ]
      },
      "actions": [
        {
          "type": "set_status",
          "status": "queried",
          "note": "Usage {usage} kWh is outside the usual range."
        },
        {
          "type": "notify",
          "to": "role:manager",
          "text": "Reading {reference} for meter {meter_no} needs a check: usage {usage} kWh."
        }
      ]
    },
    {
      "name": "Send good readings to billing",
      "form": "meter_reading",
      "enabled": true,
      "trigger": "submitted",
      "options": {},
      "conditions": {
        "all": [
          {
            "field": "usage",
            "gte": 0
          },
          {
            "field": "usage",
            "lte": 2000
          }
        ]
      },
      "actions": [
        {
          "type": "http",
          "connection": "billing",
          "method": "POST",
          "path": "/readings",
          "body": {
            "meter": "{meter_no}",
            "reading": "{reading}",
            "usage": "{usage}",
            "reference": "{reference}",
            "photo": "{files.photo}"
          },
          "save": {
            "billing_id": "$.id"
          },
          "on_fail": "retry"
        },
        {
          "type": "set_status",
          "status": "checked",
          "note": "Sent to billing as {billing_id}."
        }
      ]
    }
  ],
  "publish": [
    "meter_reading"
  ]
}

جواب الاستدعاء الحقيقي (دون dry_run):

{
  "success": true,
  "request_id": "req_...",
  "applied": {
    "lists": [
      "sites"
    ],
    "connections": [
      "billing"
    ],
    "forms": [
      "meter_reading"
    ],
    "automations": [
      "Query a reading that looks wrong",
      "Send good readings to billing"
    ],
    "published": [
      "meter_reading"
    ]
  },
  "problems": []
}

المسارات الأخرى

  • الإعدادات: GET / PUT /submit/settings.
  • النماذج: السرد، والإنشاء (من تعريف أو من قالب)، والقراءة، والتحديث، والحذف، والنشر، وPOST /submit/forms/{key}/send لإرسال نموذج إلى رقم مع قيم مملوءة.
  • القوائم: PUT /submit/lists/{key} يستبدل صفوف قائمة.
  • الطلبات المرسلة: السرد (رشّح حسب النموذج والمرحلة والمكلَّف والوسم والقناة وجهة الاتصال والنص والتواريخ؛ وupdated_after للمزامنة؛ وCSV مع ?format=csv)، والإنشاء، والقراءة بالمعرّف أو بالرقم المرجعي، والتحديث (المرحلة، والملاحظة، والأولوية، والمكلَّف، وموعد الاستحقاق، والوسوم، والإجابات، والحقول الداخلية)، وإضافة ملاحظة، والرد بأزرار، وإضافة ملف، والحذف.
  • الأتمتات والتشغيلات: السرد والإنشاء والقراءة والتحديث والحذف، وPOST /submit/automations/try، وسجل التشغيل.
  • الاتصالات: السرد والضبط والحذف والاختبار والتحديث، والدوال التي يستطيع الإجراء استدعاءها.
  • الفريق والتقرير: دعوة الأعضاء وتحديثهم وإزالتهم؛ والأعداد حسب النموذج والمرحلة واليوم والمكلَّف.

أحداث webhook

كل webhook في حسابك يتلقى كل حدث. ويحمل كل حدث الطلب كما هو في تلك اللحظة؛ وتعمل روابط الملفات فيه 7 أيام.

الحدثمتى
submission.createdوُجد طلب (وقد تكون ملفاته ما زالت تصل)
submission.files_readyخُزّنت ملفاته
submission.updatedتغيّرت الإجابات أو القيم الداخلية أو الأولوية أو الوسوم أو موعد الاستحقاق
submission.status_changedتغيرت المرحلة
submission.assignedتغيّر المكلَّف
submission.note_addedكُتبت ملاحظة
submission.customer_repliedأضاف الشخص نصًا أو ملفات أو متابعة، أو ضغط زرًّا
submission.deletedحُذف أو مُحي
submit.automation_failedاستسلمت أتمتة بعد محاولاتها المتكررة

أدوات MCP

كل مسار هو أيضًا أداة على خادم MCP المستضاف لدى app2email، فيستطيع مساعد أن ينجز الإعداد كله في محادثة: get_submit_guide وapply_submit_setup وlist_submit_presets وcreate_form وpublish_form وsend_form وlist_submissions وget_submission وupdate_submission وreply_to_submission وcreate_automation وtry_automation وset_connection وtest_connection وغيرها. وهذه رسالة أولى جيدة للمساعد: «اقرأ دليل Submit-Info، ثم أعدّ نموذج بلاغ عن مشكلة مع صور وموقع، وأبلغ مديريّ بالمستعجلة منها.»

claude mcp add --transport http app2email https://api.app2email.com/mcp --header "Authorization: Bearer YOUR_API_KEY"

المزيد عن ربط المساعدين وأدوات الأتمتة: أدوات الأتمتة والوكلاء.

الحدود

الحدالقيمة
النماذج لكل رقم100
الخطوات في نموذج، والأسئلة في خطوة12 و12 (60 سؤالًا في نموذج، وسؤال موقع واحد)
القوائم50، في كل منها حتى 1,000 صف
الأتمتات والاتصالات وأعضاء الفريق200 و30 و200
الملفات في طلب واحد60
حجم الملف25 MB من WhatsApp، و10 MB من صفحة الويب أو API
ملاحظة أو رد4,000 حرف
الوسوم على طلب20
الاستدعاءات إلى أنظمة خارجية60 في الدقيقة و2,000 في اليوم لكل رقم؛ و15 ثانية و256 KB لكل استدعاء
سجل التشغيليُحفظ 30 يومًا

غير متاح بعد

  • قبول دفعة على طلب مرسل (يُقبل عرض السعر ولا يُدفع).
  • إرسال نموذج على شكل نموذج WhatsApp إلى شخص لم يكتب إليك خلال آخر 24 ساعة: تحصل بدلًا من ذلك على رابط الويب الشخصي الخاص به، لترسله بأي قالب معتمد.
  • التوقيعات.
  • المجموعات المتكررة («أضف عنصرًا آخر»).
  • القفز إلى نموذج مختلف في منتصف الطريق.
  • ملء نموذج دون اتصال.
  • لغات أخرى في النصوص الثابتة لصفحة الويب (كل نص في نموذجك أنت من يكتبه).
  • مستندات OpenAPI بصيغة YAML أو Swagger 2، وخوادم MCP التي لا تتحدث إلا بنقل SSE الأقدم.
  • قراءة القيم من الصور.

كل ما سبق يُضبط في صفحة Submit-Info في لوحة التحكم (/dashboard/app/submit). للاستفسار: support@app2email.com.