المحادثات
اعرض المحادثات في صندوق، استرجع محادثة واحدة، واجلب جميع الرسائل التابعة لمحادثة.
نظرة عامة
تجمع المحادثات الرسائل المرتبطة في حوار. يخصّص 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) | طابع زمني لوقت إنشاء المحادثة. |
قائمة المحادثات
تُرجع قائمة مقسَّمة للمحادثات في الصندوق المحدد، مرتَّبة بـlastMessageAt تنازلياً.
معاملات المسار
| المعامل | Type | Description |
|---|---|---|
id مطلوب |
string (uuid) | معرّف الصندوق الذي تريد عرض محادثاته. |
معاملات الاستعلام
| Parameter | Type | الافتراضي | Description |
|---|---|---|---|
limit |
integer | 20 |
الحد الأقصى لعدد المحادثات المرجَعة. القيمة القصوى 100. |
offset |
integer | 0 |
عدد المحادثات المطلوب تخطيها قبل إرجاع النتائج. |
الطلب
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
{
"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
}الحصول على محادثة
يسترجع محادثة واحدة حسب معرّفها. يُرجع كائن Thread كاملاً.
Path Parameters
| Parameter | Type | Description |
|---|---|---|
id مطلوب |
string (uuid) | معرّف المحادثة المطلوب استرجاعها. |
Request
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
{
"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"
}الحصول على رسائل المحادثة
تُرجع قائمة مقسَّمة للرسائل التابعة للمحادثة المحددة، مرتَّبة بـcreatedAt تصاعدياً (الأقدم أولاً).
Path Parameters
| Parameter | Type | Description |
|---|---|---|
id مطلوب |
string (uuid) | معرّف المحادثة التي تريد استرجاع رسائلها. |
Query Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
limit |
integer | 20 |
الحد الأقصى لعدد الرسائل المرجَعة. القيمة القصوى 100. |
offset |
integer | 0 |
عدد الرسائل المطلوب تخطيها قبل إرجاع النتائج. |
Request
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
{
"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 للرسائل للقائمة الكاملة للحقول.