Conversas

As conversas agrupam mensagens relacionadas. O AgentSend agrupa automaticamente as mensagens com base em cabeçalhos de email padrão para que seus agentes sempre tenham o contexto completo de uma conversa.

Visão Geral

Toda conversa de email no AgentSend é organizada em uma conversa. Uma conversa coleta todas as mensagens relacionadas — o email original, cada resposta e cada resposta de resposta — em um único objeto de conversa ordenado. Isso facilita para os agentes lerem o histórico completo antes de compor uma resposta.

As conversas são criadas automaticamente. Quando o AgentSend recebe ou envia uma mensagem que inicia uma nova conversa, uma conversa é criada. Quando uma resposta chega, o AgentSend a associa à conversa existente e adiciona a nova mensagem.

Como o Agrupamento Funciona

O AgentSend segue o modelo padrão de agrupamento de emails usado por todos os principais clientes de email. Quando uma resposta chega, o AgentSend inspeciona os cabeçalhos In-Reply-To and References para identificar a qual conversa existente a mensagem pertence. Se uma correspondência for encontrada, a mensagem é adicionada a essa conversa. Se nenhuma correspondência for encontrada, uma nova conversa é criada.

Você também pode associar explicitamente uma mensagem a uma conversa incluindo o campo threadId ao enviar. Isso é útil quando você está iniciando um acompanhamento do lado do seu agente e quer mantê-lo agrupado com uma conversa anterior, mesmo que o destinatário inicie uma nova cadeia de respostas.

Algoritmo de correspondência

1. Check the In-Reply-To contra todos os IDs de mensagem conhecidos na caixa de entrada.
2. Se não houver correspondência, analise a lista do cabeçalho References da direita (mais recente) para a esquerda.
3. Se ainda não houver correspondência, crie uma nova conversa para esta mensagem.

Propriedades da Conversa

Cada objeto de conversa possui os seguintes campos:

Listando Conversas

Recupere todas as conversas de uma caixa de entrada usando uma requisição GET . Os resultados são ordenados por lastMessageAt decrescente para que as conversas mais ativas apareçam primeiro.

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

Parâmetros de consulta

Obtendo Mensagens da Conversa

Busque todas as mensagens em uma conversa em ordem cronológica. Isso fornece ao seu agente o histórico completo da conversa que ele precisa para compor uma resposta contextualizada.

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

Respondendo em uma Conversa

Para continuar uma conversa existente, inclua o threadId ao enviar uma mensagem. O AgentSend definirá automaticamente os cabeçalhos In-Reply-To and References corretos para que a resposta apareça no cliente de email do destinatário como parte da mesma conversa.

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

Casos de Uso

As conversas desbloqueiam um conjunto de fluxos de trabalho que requerem memória em múltiplas trocas de email.

• Suporte ao cliente — Carregue a conversa completa antes de gerar uma resposta para que seu agente de suporte tenha todo o contexto anterior. Atribua conversas a agentes humanos apenas quando necessário.
• Acompanhamento de vendas — Acompanhe sequências de prospecção multi-toque. Saiba quando um prospect respondeu pela última vez e quantas mensagens estão em uma cadeia antes de escalar.
• Agendamento e coordenação — Execute negociações de ida e volta (horários de reunião, termos de contrato) dentro de uma única conversa para que o histórico da conversa esteja sempre acessível.
• Coleta de pesquisa — Envie uma consulta inicial, colete respostas e acompanhe com perguntas esclarecedoras — tudo dentro de uma conversa organizada por contato.