Trang Chủ › Tài Liệu › Tài Liệu API › Chuỗi Hội Thoại

Chuỗi Hội Thoại

Liệt kê chuỗi trong một hộp thư, lấy một chuỗi, và lấy tất cả tin nhắn thuộc một chuỗi.

Tổng Quan

Chuỗi hội thoại nhóm các tin nhắn liên quan trong một cuộc hội thoại. AgentSend tự động gán tin nhắn đến và đi vào chuỗi dựa trên header email (In-Reply-To, References). Mỗi chuỗi thuộc đúng một hộp thư.

Sử dụng các endpoint Chuỗi để đọc lịch sử hội thoại, hiển thị chế độ xem chuỗi trong UI của agent, hoặc xác định chuỗi nào cho tin nhắn đến mới.

ℹ

Tất cả yêu cầu API cần header x-api-key. Lấy key của bạn từ bảng điều khiển AgentSend.

Đối Tượng Chuỗi

Các endpoint trả về chuỗi sẽ bao gồm các trường sau.

Trường Kiểu Mô tả
id string (uuid) Định danh duy nhất của thread.
inboxId string (uuid) ID of the inbox this thread belongs to.
subject string Subject line of the thread, taken from the first message.
messageCount integer Total number of messages in the thread.
lastMessageAt string (ISO 8601) Timestamp of the most recent message in the thread.
createdAt string (ISO 8601) Timestamp when the thread được tạo.
GET /inboxes/{id}/threads

List Threads

Trả về danh sách có phân trang of threads for the specified inbox, ordered by lastMessageAt descending.

Path Parameters

ParameterTypeDescription
id bắt buộc string (uuid) The ID of the inbox whose threads you want to list.

Query Parameters

ParameterTypeDefaultDescription
limit integer 20 Số lượng tối đa threads to return. Max value is 100.
offset integer 0 Số lượng threads to skip before returning results.

Request

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

Response 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}

Get Thread

Retrieves a single thread by its ID. Returns the full Thread object.

Path Parameters

ParameterTypeDescription
id bắt buộc string (uuid) The ID of the thread to retrieve.

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

Get Thread Messages

Trả về danh sách có phân trang of messages belonging to the specified thread, ordered by createdAt ascending (oldest first).

Path Parameters

ParameterTypeDescription
id bắt buộc string (uuid) The ID of the thread whose messages you want to retrieve.

Query Parameters

ParameterTypeDefaultDescription
limit integer 20 Số lượng tối đa messages to return. Max value is 100.
offset integer 0 Số lượng messages to skip before returning results.

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
}
💡

The messages array contains full Message objects. See the Messages API reference for the complete field list.

← Trước API: Tin Nhắn