Beranda › Dokumentasi › Utas

Utas

Utas mengelompokkan pesan terkait ke dalam percakapan. AgentSend secara otomatis menyusun utas pesan berdasarkan header email standar sehingga agen Anda selalu memiliki konteks penuh percakapan.

Ikhtisar

Setiap percakapan email di AgentSend diatur ke dalam utas. Utas mengumpulkan semua pesan terkait — email asli, setiap balasan, dan setiap balasan-ke-balasan — ke dalam satu objek percakapan yang terurut. Ini memudahkan agen membaca riwayat lengkap sebelum menyusun respons.

Utas dibuat secara otomatis. Saat AgentSend menerima atau mengirim pesan yang memulai percakapan baru, utas dibuat. Saat balasan tiba, AgentSend mencocokkannya dengan utas yang ada dan menambahkan pesan baru.

ℹ

Utas dicakup ke kotak masuk. Rantai email yang sama yang diterima oleh dua kotak masuk berbeda akan menghasilkan dua objek utas terpisah.

Cara Kerja Threading

AgentSend mengikuti model threading email standar yang digunakan oleh setiap klien email utama. Saat balasan tiba, AgentSend memeriksa header In-Reply-To dan References untuk mengidentifikasi utas yang ada tempat pesan berada. Jika ditemukan kecocokan, pesan ditambahkan ke utas tersebut. Jika tidak ditemukan kecocokan, utas baru dibuat.

Anda juga dapat secara eksplisit mengaitkan pesan dengan utas dengan menyertakan field threadId saat mengirim. Ini berguna saat Anda memulai tindak lanjut dari sisi agen Anda dan ingin tetap dikelompokkan dengan percakapan sebelumnya, meskipun penerima memulai rantai balasan baru.

💡

Selalu baca threadId dari payload webhook masuk dan teruskan kembali saat membalas. Ini menjamin pengelompokan yang benar bahkan saat penerima mengubah baris subjek mereka.

Algoritma pencocokan

  1. Periksa header In-Reply-To terhadap semua ID pesan yang diketahui di kotak masuk.
  2. Jika tidak cocok, pindai daftar header References dari kanan (paling baru) ke kiri.
  3. Jika masih tidak cocok, buat utas baru untuk pesan ini.

Properti Utas

Setiap objek utas memiliki field berikut:

Properti Tipe Deskripsi
id string Pengenal unik untuk utas.
inboxId string Kotak masuk tempat utas ini berada.
subject string Baris subjek pesan pertama di utas.
messageCount integer Jumlah total pesan di utas ini.
lastMessageAt string (ISO 8601) Timestamp pesan terbaru.
createdAt string (ISO 8601) Timestamp saat utas pertama kali dibuat.

Daftar Utas

Ambil semua utas untuk kotak masuk menggunakan request GET. Hasil diurutkan berdasarkan lastMessageAt menurun sehingga percakapan paling aktif muncul lebih dulu.

javascript 
// 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);
}

Parameter query

Parameter Tipe Default Deskripsi
limit integer 20 Jumlah maksimum utas yang dikembalikan. Maks 100.
offset integer 0 Jumlah utas yang dilewati untuk paginasi.

Mendapatkan Pesan Utas

Ambil setiap pesan di utas dalam urutan kronologis. Ini memberi agen Anda riwayat percakapan lengkap yang dibutuhkan untuk menyusun balasan yang sadar konteks.

javascript 
// 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`);
ℹ

Pesan dalam utas dikembalikan dalam urutan kronologis menaik (sentAt terlama dulu). Ini cocok dengan urutan alami yang diharapkan oleh sebagian besar API percakapan LLM.

Membalas di Utas

Untuk melanjutkan percakapan yang ada, sertakan threadId saat mengirim pesan. AgentSend akan secara otomatis menetapkan header In-Reply-To dan References yang benar sehingga balasan muncul di klien email penerima sebagai bagian dari percakapan yang sama.

javascript 
// 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
  }),
});
⚠

Jika Anda menghilangkan threadId, pesan keluar akan memulai utas baru meskipun Anda menggunakan baris subjek yang sama. Selalu teruskan threadId saat melanjutkan percakapan.

Kasus Penggunaan

Utas membuka serangkaian alur kerja yang membutuhkan memori di beberapa pertukaran email.

← Sebelumnya Pesan