app2email API الأثمنة

التوثيق

Submit-Info

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

كتكتب الاستمارة كلائحة بسيطة ديال الأسئلة. app2email كيحولها لاستمارة فـ WhatsApp وصفحة ويب بنفس الخطوات. الزبون، ولا عضو من الفريق ديالك اللي خدام ميدان، كيعمرها وكياخد مرجع. الأجوبة والملفات كيولّيو إرسالية فصندوق وارد مشترك، فين كتمشي فالمراحل ديالك وكتشغل الأتمتة ديالك.

فكرة وحدة

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

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

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

ماكاين والو تبدّل لرقم ما حلّ Submit-Info عمرو. استمارة ما منشورة على WhatsApp بعد كتخدم: الكلمة ديالها كتجاوب برابط صفحة الويب.

منشئ الاستمارة

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

النوعشنو كيعطي الشخصشنو تقدر تحدد
textجواب قصيرأقصر وأطول طول، نمط
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}.
  • يبان غير ملي: خطوة ولا سؤال يقدر يتعلق بجواب سابق ("بيّن هاد الخطوة غير ملي Problem يكون Yes"). WhatsApp وصفحة الويب كيتبعو نفس القاعدة.
  • حقول داخلية: حقول ما كتتسولش أبدا. فريقك ولا أتمتة كيعمرهم: مبلغ عرض الثمن، سبب القرار، رقم جا من نظام آخر. كيبانو غير فـ Inbox وفالتصدير.
  • اللوائح: سؤال الاختيار يقدر ياخد اختياراته من لائحة ديالك (مواقع، خدمات، منتجات بالأثمان). بدّل اللائحة فلوحة التحكم ولا عبر API والاستمارة كتتبعها، بلا ما تحتاج تنشرها من جديد.
  • الحسابات: صيغة على الأجوبة، لتقدير فالحال ولا لفحص. شوف formulas.
  • بعد الإرسال: شاشة مراجعة قبل الإرسال، الرد برقم المرجع، زر "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، "Ignore the words in long messages")، باش ميساج طويل يصادف فيه الكلمة ما يبداش والو.
  • رابط ولا QR code: رابط كيحل دردشة WhatsApp ديالك مع كلمة الاستمارة، ولا عنوان صفحة الويب.
  • تصيفطها إنت: "Send form" فصندوق الوارد، ولا API، كيصيفط استمارة لرقم وحدة، مع قيم معمرة مسبقا (رقم خدمة، حساب، الوثائق اللي بغيتي).
  • متابعة: أتمتة ولا عضو من الفريق كيطلب زيادة بـ استمارة تانية. اللي كيرجع كيتزاد للإرسالية الأولى.
  • صفحة الويب، وAPI للأنظمة اللي عندها المعطيات أصلا.

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

المراحل

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

  • من يقدر يختارها: خلي مرحلة لأدوار معينة. الوكيل يجهز، والمسؤول غير هو اللي يوافق.
  • الملاحظة خاصها: اطلب سبب ملي تنقل إرسالية لهاد المرحلة (مرفوضة، مرفوضة، مستفسر عليها).
  • الرسالة: نص كيتصيفط للشخص ملي إرساليتو توصل لهاد المرحلة، مع متغيرات.
  • أزرار للشخص: الرد يقدر يكون فيه حتى ثلاث أزرار (Accept، Decline، "Not fixed yet")، وكل زر كينقل المرحلة. هاد الشي وحدو كيعطيك قبول عرض الثمن، تأكيد زيارة، و"واش تصلحات؟".

الرد اللي يكتب برا وقت الرد ديال WhatsApp كيتحفظ وكيتصيفط ملي الشخص يكتب من جديد. Inbox كيقول ليك هادشي على الرد.

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

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

الإرسالية كتبيّن أجوبتها وملفاتها، فين صيفطات منها، وتاريخ وحدة فيه كاع اللي وقع ليها: تبديلات المراحل مع شكون ولماذا، الملاحظات، الردود فالجوج اتجاهات، الملفات، وكل خطوة أتمتة مع نتيجتها. فالآخر كتكتب ملاحظة داخلية ولا رد WhatsApp. صدّر أي عرض بـ CSV أو Excel أو JSON، ولإرسالية وحدة بـ PDF.

الفريق ديالك. دعي الناس بالإيميل للـ inbox بوحدو. كيخدمو بتطبيق خفيف ديالهم فـ /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

عنوان أساسي وطريقة للدخول (والو، token ديال bearer، header، اسم المستخدم وكلمة السر، ولا key فالعنوان). الإجراء كيسمّي الطريقة، المسار، وجسم 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 كيقرا العمليات ديالها؛ الإجراء كيختار وحدة بـ id ديالها ويعمّر المتغيرات ديالها. وثائق 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) والـ token ديالو. 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 وعامة: العناوين الخاصة والمحلية والداخلية مرفوضة، وما كيتبعوش الـ redirects. الطلب ممكن ياخد 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: الإرسالية كاملة كـ object
{= 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') باش تقرر شكون يوافق.

للمطورين ولوكلاء AI

كل شي فوق كاين فـ REST API تحت /v1/{number}/submit، فين {number} هو رقم WhatsApp ديالك بكود البلاد، غير أرقام. صيفط الـ API key ديالك كـ Authorization: Bearer YOUR_API_KEY (header X-API-KEY مقبول كذلك). الـ key خاصو scope submissions:manage؛ الـ keys بـ Full access عندهم، والـ Default key ما عندوش. الـ sandbox keys ما يقدروش يكتبو.

  1. GET /submit/guide: وثيقة JSON وحدة فيها كاع المفردات: أنواع الأسئلة بالاختيارات والحدود ديالها، قواعد المراحل، المحفزات، العوامل، الإجراءات بمتغيراتها، المتغيرات، دوال الصيغ، القوالب، وأمثلة كاملة.
  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 وصيفطها. بدّل 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)، الخلق، القراءة بالـ id ولا المرجع، التعديل (المرحلة، الملاحظة، الأولوية، المعيّن، وقت الاستحقاق، العلامات، الأجوبة، الحقول الداخلية)، زيادة ملاحظة، الرد بأزرار، زيادة ملف، المسح.
  • الأتمتة وسجلات التشغيل: اللائحة، الخلق، القراءة، التعديل، المسح، 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 وزيد. أول ميساج مزيان للمساعد: "Read the Submit-Info guide, then set up a problem report form with photos and a location, and tell my managers about urgent ones."

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

زيد على ربط المساعدين وأدوات الأتمتة: Automation tools and agents.

الحدود

الحدالقيمة
استمارات فكل رقم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 يوم

ماشي متوفر دابا

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

كاع اللي فوق كيتحدد فصفحة Submit-Info فلوحة التحكم (/dashboard/app/submit). الأسئلة: support@app2email.com.