المحادثات

اعرض المحادثات في صندوق، استرجع محادثة واحدة، واجلب جميع الرسائل التابعة لمحادثة.

نظرة عامة

تجمع المحادثات الرسائل المرتبطة في حوار. يخصّص AgentSend تلقائياً الرسائل الواردة والصادرة للمحادثات استناداً إلى ترويسات البريد (In-Reply-To، References). كل محادثة تنتمي إلى صندوق واحد فقط.

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

تتطلب جميع طلبات API ترويسة x-api-key. احصل على مفتاحك من لوحة تحكم AgentSend.

كائن Thread

ستتضمن نقاط النهاية التي تُرجع محادثة الحقول التالية.

الحقل النوع الوصف
id string (uuid) المعرّف الفريد للمحادثة.
inboxId string (uuid) معرّف الصندوق الذي تنتمي إليه هذه المحادثة.
subject string سطر موضوع المحادثة، مأخوذ من أول رسالة.
messageCount integer إجمالي عدد الرسائل في المحادثة.
lastMessageAt string (ISO 8601) طابع زمني لأحدث رسالة في المحادثة.
createdAt string (ISO 8601) طابع زمني لوقت إنشاء المحادثة.
GET /inboxes/{id}/threads

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

تُرجع قائمة مقسَّمة للمحادثات في الصندوق المحدد، مرتَّبة بـlastMessageAt تنازلياً.

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

المعاملTypeDescription
id مطلوب string (uuid) معرّف الصندوق الذي تريد عرض محادثاته.

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

ParameterTypeالافتراضيDescription
limit integer 20 الحد الأقصى لعدد المحادثات المرجَعة. القيمة القصوى 100.
offset integer 0 عدد المحادثات المطلوب تخطيها قبل إرجاع النتائج.

الطلب

javascript
const inboxId = "inbox_01hx4z2k9m3p7qr8st5uvwxy";

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 = await res.json();
console.log(data.data); // array of Thread objects

الاستجابة 200

json
{
  "data": [
    {
      "id": "thr_01hx4z2k9m3p7qr8st5uvwxy",
      "inboxId": "inbox_01hx4z2k9m3p7qr8st5uvwxy",
      "subject": "Re: Your order has shipped",
      "messageCount": 4,
      "lastMessageAt": "2024-06-12T14:22:07Z",
      "createdAt": "2024-06-10T09:01:33Z"
    },
    {
      "id": "thr_02hy5a3l0n4q8rs9tu6vwxyz",
      "inboxId": "inbox_01hx4z2k9m3p7qr8st5uvwxy",
      "subject": "Hello from AgentSend",
      "messageCount": 1,
      "lastMessageAt": "2024-06-11T08:44:55Z",
      "createdAt": "2024-06-11T08:44:55Z"
    }
  ],
  "total": 2,
  "limit": 20,
  "offset": 0
}
GET /threads/{id}

الحصول على محادثة

يسترجع محادثة واحدة حسب معرّفها. يُرجع كائن Thread كاملاً.

Path Parameters

ParameterTypeDescription
id مطلوب string (uuid) معرّف المحادثة المطلوب استرجاعها.

Request

javascript
const threadId = "thr_01hx4z2k9m3p7qr8st5uvwxy";

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

const thread = await res.json();
console.log(thread.subject, thread.messageCount);

Response 200

json
{
  "id": "thr_01hx4z2k9m3p7qr8st5uvwxy",
  "inboxId": "inbox_01hx4z2k9m3p7qr8st5uvwxy",
  "subject": "Re: Your order has shipped",
  "messageCount": 4,
  "lastMessageAt": "2024-06-12T14:22:07Z",
  "createdAt": "2024-06-10T09:01:33Z"
}
GET /threads/{id}/messages

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

تُرجع قائمة مقسَّمة للرسائل التابعة للمحادثة المحددة، مرتَّبة بـcreatedAt تصاعدياً (الأقدم أولاً).

Path Parameters

ParameterTypeDescription
id مطلوب string (uuid) معرّف المحادثة التي تريد استرجاع رسائلها.

Query Parameters

ParameterTypeDefaultDescription
limit integer 20 الحد الأقصى لعدد الرسائل المرجَعة. القيمة القصوى 100.
offset integer 0 عدد الرسائل المطلوب تخطيها قبل إرجاع النتائج.

Request

javascript
const threadId = "thr_01hx4z2k9m3p7qr8st5uvwxy";

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

const data = await res.json();

for (const msg of data.data) {
  console.log(msg.fromAddress, msg.subject, msg.createdAt);
}

Response 200

json
{
  "data": [
    {
      "id": "msg_01hx4z2k9m3p7qr8st5uvwxy",
      "threadId": "thr_01hx4z2k9m3p7qr8st5uvwxy",
      "inboxId": "inbox_01hx4z2k9m3p7qr8st5uvwxy",
      "direction": "outbound",
      "fromAddress": "agent@agentsend.io",
      "toAddresses": ["customer@example.com"],
      "subject": "Your order has shipped",
      "bodyText": "Hi! Your order #1234 has shipped and will arrive by Friday.",
      "status": "delivered",
      "createdAt": "2024-06-10T09:01:33Z"
    },
    {
      "id": "msg_02hy5a3l0n4q8rs9tu6vwxyz",
      "threadId": "thr_01hx4z2k9m3p7qr8st5uvwxy",
      "inboxId": "inbox_01hx4z2k9m3p7qr8st5uvwxy",
      "direction": "inbound",
      "fromAddress": "customer@example.com",
      "toAddresses": ["agent@agentsend.io"],
      "subject": "Re: Your order has shipped",
      "bodyText": "Thanks! Can you share the tracking number?",
      "status": "received",
      "createdAt": "2024-06-10T11:17:45Z"
    }
  ],
  "total": 4,
  "limit": 20,
  "offset": 0
}
💡

تحتوي مصفوفة الرسائل على كائنات Message كاملة. راجع مرجع API للرسائل للقائمة الكاملة للحقول.