المحادثات

تجمع المحادثات الرسائل ذات الصلة في حوارات. يصنّف AgentSend الرسائل تلقائياً استناداً إلى ترويسات البريد القياسية ليمتلك وكلاؤك دوماً السياق الكامل للمحادثة.

نظرة عامة

كل حوار بريدي في AgentSend منظَّم في محادثة. تجمع المحادثة كل الرسائل المتعلقة — الرسالة الأصلية، وكل رد، وكل رد على رد — في كائن محادثة واحد مُرتَّب. يسهّل ذلك على الوكلاء قراءة السجل الكامل قبل كتابة الرد.

تُنشأ المحادثات تلقائياً. عندما يستقبل AgentSend أو يرسل رسالة تبدأ حواراً جديداً، تُنشأ محادثة. وعند وصول رد، يطابقه AgentSend مع المحادثة القائمة ويُلحق الرسالة الجديدة بها.

كيف تعمل المحادثات

يتبع AgentSend النموذج القياسي للمحادثات البريدية المستخدَم في كل عميل بريد رئيسي. عند وصول رد، يفحص AgentSend ترويستَي In-Reply-To وReferences لتحديد المحادثة التي تنتمي إليها الرسالة. إذا وُجد تطابق، تُلحق الرسالة بتلك المحادثة. إذا لم يُوجد، تُنشأ محادثة جديدة.

يمكنك أيضاً ربط رسالة بمحادثة صراحةً بتضمين حقل threadId عند الإرسال. يفيد ذلك عندما تبدأ متابعة من جانب وكيلك وتريد إبقاءها مجموعة مع حوار سابق، حتى لو بدأ المستلم سلسلة ردود جديدة.

خوارزمية المطابقة

1. تحقق من ترويسة In-Reply-To مقابل جميع معرّفات الرسائل المعروفة في الصندوق.
2. إذا لم يُوجد تطابق، امسح قائمة ترويسة References من اليمين (الأحدث) إلى اليسار.
3. إذا لم يوجد تطابق بعد ذلك، أنشئ محادثة جديدة لهذه الرسالة.

خصائص المحادثة

يحتوي كل كائن محادثة على الحقول التالية:

قائمة المحادثات

احصل على جميع المحادثات لصندوق بريد باستخدام طلب GET. النتائج مرتَّبة بـlastMessageAt تنازلياً بحيث تظهر أكثر الحوارات نشاطاً أولاً.

// GET /inboxes/{id}/threads?limit=20&offset=0
const res = await fetch(
  `https://api.agentsend.io/inboxes/${inboxId}/threads?limit=20&offset=0`,
  { headers: { "x-api-key": process.env.AGENTSEND_API_KEY } }
);

const { data, total } = await res.json();

for (const thread of data) {
  console.log(thread.id, thread.subject, thread.messageCount);
}

معاملات الاستعلام

الحصول على رسائل المحادثة

اجلب كل رسالة في المحادثة بالترتيب الزمني. يمنح ذلك وكيلك السجل الكامل للحوار اللازم لصياغة رد واعٍ بالسياق.

// GET /threads/{id}/messages
const res = await fetch(
  `https://api.agentsend.io/threads/${threadId}/messages`,
  { headers: { "x-api-key": process.env.AGENTSEND_API_KEY } }
);

const { data } = await res.json();

// Build a conversation history for your LLM
const history = data.map(msg => ({
  role: msg.direction === "outbound" ? "assistant" : "user",
  content: msg.bodyText,
}));

console.log(`Loaded ${history.length} messages from thread`);

الرد في محادثة

لمواصلة حوار قائم، ضمّن threadId عند إرسال الرسالة. سيضبط AgentSend تلقائياً ترويستَي In-Reply-To وReferences الصحيحتين ليظهر الرد في عميل بريد المستلم كجزء من نفس الحوار.

// POST /inboxes/{id}/messages — reply within an existing thread
await fetch(`https://api.agentsend.io/inboxes/${inboxId}/messages`, {
  method: "POST",
  headers: {
    "x-api-key": process.env.AGENTSEND_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    to: ["customer@example.com"],
    subject: "Re: Your support request",
    bodyText: "Thanks for reaching out! Here is the information you requested...",
    threadId: "thrd_abc123", // ties this message to the existing conversation
  }),
});

حالات الاستخدام

تفتح المحادثات مجموعة من تدفقات العمل التي تتطلب ذاكرة عبر تبادلات بريدية متعددة.

• دعم العملاء — حمّل المحادثة الكاملة قبل توليد الرد ليمتلك وكيل الدعم كامل السياق السابق. خصّص المحادثات لوكلاء بشر فقط عند الحاجة.
• متابعات المبيعات — تتبَّع سلاسل التواصل متعدد اللمسات. اعرف متى رد العميل المحتمل آخر مرة وكم رسالة في السلسلة قبل التصعيد.
• الجدولة والتنسيق — أدِر مفاوضات ذهاباً وإياباً (مواعيد الاجتماعات، شروط العقود) داخل محادثة واحدة ليظل سجل الحوار متاحاً دائماً.
• جمع الأبحاث — أرسل استفساراً أولياً، اجمع الردود، ثم تابع بأسئلة توضيحية — كل ذلك ضمن محادثة منظمة واحدة لكل جهة اتصال.