Dynamic User Context (payload) السياق الديناميكي للمستخدم (payload)

1. Add a payload object to your message request
2. Mugib stores it in Redis for the entire session lifetime
3. On every message, the payload is injected as a [User Context] block at the top of the system prompt
4. The AI reads this context and uses it to personalize its response

Start with a normal session creation:

curl -X POST "https://api.mugib.com/api/v1/sessions" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

# Response:
# { "session_id": "chat_dc3ca9ae" }

Add a payload object to your first message. Any JSON keys are accepted — choose what's meaningful for your use case:

curl -X POST "https://api.mugib.com/api/v1/sessions/chat_dc3ca9ae/messages" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "What is my current plan?",
    "payload": {
      "name": "Ahmed Al-Rashidi",
      "account_id": "NBT-4521",
      "plan": "FTTH 100MB",
      "balance": 15.5,
      "renewal_days": 3
    }
  }'

The bot will use this context in its reply:

// Response JSON
{
  "reply": "Hello Ahmed! Your current plan is FTTH 100MB.
Your balance is 15.5 IQD and your plan renews in 3 days.
Would you like to renew now or upgrade to a higher tier?",
  "kb_sources": [
    { "id": "42", "title": "FTTH Plans Overview", "category": "Plans" }
  ]
}

Once stored, the payload persists for the full session. You don't need to send it again on every message:

curl -X POST "https://api.mugib.com/api/v1/sessions/chat_dc3ca9ae/messages" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "message": "Can I upgrade my plan?" }'
# The bot still knows the user's name, plan, balance, etc.

// Send payload once on the first message
const sendMessage = async (sessionId, message, payload = null) => {
  const body = { message };
  if (payload) body.payload = payload;

  const res = await fetch(
    "https://api.mugib.com/api/v1/sessions/" + sessionId + "/messages",
    {
      method: "POST",
      headers: {
        "X-API-Key": "YOUR_API_KEY",
        "Content-Type": "application/json",
      },
      body: JSON.stringify(body),
    }
  );
  return res.json();
};

// First message — include user context
await sendMessage("chat_dc3ca9ae", "Hello!", {
  name: 'Ahmed Al-Rashidi',
  account_id: 'NBT-4521',
  plan: 'FTTH 100MB',
  balance: 15.5,
});

// Subsequent messages — no payload needed
await sendMessage("chat_dc3ca9ae", "Can I upgrade my plan?");

import requests

BASE = "https://api.mugib.com/api/v1"
HEADERS = {"X-API-Key": "YOUR_API_KEY"}

# Create session
session_id = requests.post(BASE + "/sessions", headers=HEADERS).json()["session_id"]

# First message with payload
url = BASE + "/sessions/" + session_id + "/messages"
res = requests.post(url, headers=HEADERS, json={
    "message": "What is my plan status?",
    "payload": {
        "name": "Ahmed Al-Rashidi",
        "account_id": "NBT-4521",
        "plan": "FTTH 100MB",
        "balance": 15.5,
    },
})
print(res.json()["reply"])

# Follow-up — no payload required
res2 = requests.post(url, headers=HEADERS, json={"message": "How do I renew?"})
print(res2.json()["reply"])

• Optional — omitting payload is perfectly fine. Existing integrations are not affected.
• Persistent — stored in Redis for the session lifetime (same TTL as conversation history).
• Updatable — send a new payload on any message to replace the stored one (e.g. after a plan upgrade).
• Any JSON object — keys and value types are free-form. Use whatever fields your app has.
• Works with streaming — the ?stream=true SSE endpoint supports payload too.

1. أضف كائن payload لطلب الرسالة
2. مجيب يحفظه في Redis طول مدة الجلسة
3. في كل رسالة، يُحقن الـ payload كبلوك [User Context] في بداية الـ System Prompt
4. الذكاء الاصطناعي يقرأ هذا السياق ويستخدمه لتخصيص الرد

ابدأ بإنشاء جلسة عادي:

curl -X POST "https://api.mugib.com/api/v1/sessions" \
  -H "X-API-Key: YOUR_API_KEY"

# الرد:
# { "session_id": "chat_dc3ca9ae" }

أضف كائن payload لأول رسالة. أي مفاتيح JSON مقبولة — اختر ما يناسب تطبيقك:

curl -X POST "https://api.mugib.com/api/v1/sessions/chat_dc3ca9ae/messages" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "شنو باقتي الحالية؟",
    "payload": {
      "name": "أحمد الراشدي",
      "account_id": "NBT-4521",
      "plan": "FTTH 100 ميجا",
      "balance": 15.5,
      "renewal_days": 3
    }
  }'

البوت يستخدم هذا السياق في رده:

// Response JSON
{
  "reply": "مرحباً أحمد! باقتك الحالية FTTH 100 ميجا.
رصيدك 15.5 دينار وتنتهي باقتك بعد 3 أيام.
تريد تجديد الآن أو الترقية لباقة أعلى؟"
}

بعد حفظ الـ payload، يبقى طول الجلسة. ما تحتاج ترسله في كل رسالة:

curl -X POST "https://api.mugib.com/api/v1/sessions/chat_dc3ca9ae/messages" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{ "message": "أقدر أرفّع باقتي؟" }'
# البوت لا يزال يعرف اسم المستخدم وباقته ورصيده

const sendMessage = async (sessionId, message, payload = null) => {
  const body = { message };
  if (payload) body.payload = payload;

  const res = await fetch(
    "https://api.mugib.com/api/v1/sessions/" + sessionId + "/messages",
    {
      method: "POST",
      headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
      body: JSON.stringify(body),
    }
  );
  return res.json();
};

// الرسالة الأولى — أرسل بيانات المستخدم
await sendMessage("chat_dc3ca9ae", "مرحبا!", {
  name: "أحمد الراشدي",
  account_id: "NBT-4521",
  plan: "FTTH 100 ميجا",
  balance: 15.5,
});

// الرسائل التالية — بدون payload
await sendMessage("chat_dc3ca9ae", "أقدر أرفّع باقتي؟");

• اختياري — حذف payload طبيعي تماماً. التكاملات القديمة لا تتأثر.
• دائم — محفوظ في Redis طول مدة الجلسة.
• قابل للتحديث — أرسل payload جديد في أي رسالة لتحديث المحفوظ (مثلاً بعد ترقية الباقة).
• أي JSON — المفاتيح والقيم حرة. استخدم ما يناسب تطبيقك.
• يدعم الـ Streaming — endpoint الـ ?stream=true يدعم payload كذلك.