홈 › 문서 › API 레퍼런스 › 스레드

스레드

수신함의 스레드 나열, 단일 스레드 조회, 스레드에 속한 모든 메시지 가져오기.

개요

스레드는 대화의 관련 메시지를 그룹화합니다. AgentSend는 이메일 헤더(In-Reply-To, References)를 기반으로 수신 및 발신 메시지를 자동으로 스레드에 할당합니다. 모든 스레드는 정확히 하나의 수신함에 속합니다.

Thread 엔드포인트를 사용해 대화 기록을 읽거나, 에이전트 UI에 스레드 뷰를 표시하거나, 새 수신 메시지를 라우팅할 스레드를 결정하세요.

ℹ

모든 API 요청에는 x-api-key 헤더가 필요합니다. AgentSend 대시보드에서 키를 받으세요.

Thread 객체

스레드를 반환하는 엔드포인트는 다음 필드를 포함합니다.

필드 타입 설명
id string (uuid) 스레드의 고유 식별자.
inboxId string (uuid) 이 스레드가 속한 수신함의 ID.
subject string 첫 메시지에서 가져온 스레드 제목.
messageCount integer 스레드의 총 메시지 수.
lastMessageAt string (ISO 8601) 스레드의 가장 최근 메시지의 시각.
createdAt string (ISO 8601) 스레드가 생성된 시각.
GET /inboxes/{id}/threads

스레드 목록

지정된 수신함의 스레드를 lastMessageAt 내림차순으로 페이지네이션된 목록으로 반환합니다.

경로 파라미터

파라미터타입설명
id 필수 string (uuid) 스레드를 나열할 수신함의 ID.

쿼리 파라미터

파라미터타입기본값설명
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

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}

스레드 조회

ID로 단일 스레드를 가져옵니다. 전체 Thread 객체를 반환합니다.

경로 파라미터

파라미터타입설명
id 필수 string (uuid) 가져올 스레드의 ID.

요청

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 오름차순(오래된 것부터)으로 페이지네이션된 목록으로 반환합니다.

경로 파라미터

파라미터타입설명
id 필수 string (uuid) 메시지를 가져올 스레드의 ID.

쿼리 파라미터

파라미터타입기본값설명
limit integer 20 반환할 최대 메시지 수. 최대값 100.
offset integer 0 결과를 반환하기 전에 건너뛸 메시지 수.

요청

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

messages 배열에는 전체 Message 객체가 포함됩니다. 전체 필드 목록은 메시지 API 레퍼런스를 참고하세요.

← 이전 API: 메시지