Conversas

O que você vai aprender: Esta página explica como funcionam as conversas no ZappWay, como listá-las e gerenciá-las, como atualizar seus status em massa, como exportá-las e como usar o recurso de resumo por IA.

🔢 Sumário

Visão Geral
Referência de Endpoints
Listando Conversas
Gerenciando uma Conversa
Atualização de Status em Massa
Exportar Conversas
Avaliando Respostas
Formato de Resposta
Boas Práticas
Troubleshooting

1. Visão Geral

O que é uma Conversa?

Uma Conversa no ZappWay é um thread completo de mensagens entre um contato e sua organização — mediado por um Funcionário IA, um agente humano, ou ambos. Conversas podem originar de:

💬 WhatsApp (Business API)
📧 Caixa de Entrada de Email
🌐 Widget (chat do site)
📱 DMs do TikTok
🔌 Qualquer integração conectada

Cada conversa possui:

Um contato — com quem a conversa está acontecendo
Um canal — onde a conversa está ocorrendo
Um status — open, resolved ou snoozed
Uma atribuição de Funcionário IA (opcional)
Um thread de mensagens completo com timestamps

Colaboração IA e Humano

As conversas suportam um modelo híbrido: o Funcionário IA pode lidar com as mensagens automaticamente, e um agente humano pode assumir a qualquer momento. As mensagens da IA e as mensagens humanas aparecem no mesmo thread.

2. Referência de Endpoints

Método	Endpoint	Descrição	Auth
`GET`	`/api/conversations`	Listar conversas com filtros	Auth opcional (suporte a widget)
`HEAD`	`/api/conversations`	Preflight CORS	Nenhuma
`GET`	`/api/conversations/[conversationId]`	Obter uma conversa específica	Sessão org
`PATCH`	`/api/conversations/[conversationId]`	Atualizar conversa (atribuir agente, definir status)	Sessão org
`DELETE`	`/api/conversations/[conversationId]`	Excluir uma conversa	Sessão org
`POST`	`/api/conversations/update-status`	Atualizar status de conversas em massa	Sessão org
`POST`	`/api/conversations/bulk-unread`	Marcar conversas como não lidas em massa	Sessão org
`GET`	`/api/conversations/export`	Exportar conversas para arquivo	Sessão org
`POST`	`/api/conversations/[conversationId]/eval-answer`	Avaliar qualidade de resposta da IA	Sessão org

3. Listando Conversas

Listar Conversas

GET /api/conversations

Suporta autenticação opcional — requisições autenticadas retornam conversas da organização; requisições não autenticadas podem retornar conversas públicas do widget. Parâmetros de Query:

Parâmetro	Tipo	Descrição
`status`	`"open" \| "resolved" \| "snoozed"`	Filtrar por status da conversa
`agentId`	`string`	Filtrar por Funcionário IA atribuído
`contactId`	`string`	Filtrar por contato
`channel`	`string`	Filtrar por canal (ex: `whatsapp`, `email`, `widget`)
`page`	`number`	Número da página para paginação
`limit`	`number`	Número de resultados por página
`search`	`string`	Busca full-text no conteúdo das conversas
`dateFrom`	`ISO 8601`	Filtrar conversas após esta data
`dateTo`	`ISO 8601`	Filtrar conversas antes desta data

Exemplo:

GET /api/conversations?status=open&channel=whatsapp&page=1&limit=20

TypeScript:

const params = new URLSearchParams({
  status: 'open',
  channel: 'whatsapp',
  page: '1',
  limit: '20',
});

const response = await fetch(`/api/conversations?${params}`);
const data = await response.json();

4. Gerenciando uma Conversa

Obter uma Conversa

GET /api/conversations/{conversationId}

Atualizar uma Conversa

PATCH /api/conversations/{conversationId}
Content-Type: application/json

Corpo da Requisição:

Campo	Tipo	Descrição
`status`	`"open" \| "resolved" \| "snoozed"`	Atualizar status da conversa
`agentId`	`string \| null`	Atribuir ou desatribuir um Funcionário IA
`assignedUserId`	`string \| null`	Atribuir a um membro humano da equipe
`note`	`string`	Adicionar uma nota interna
`snoozeUntil`	`ISO 8601`	Adiar até um datetime específico

Exemplo — Resolver uma conversa:

{
  "status": "resolved"
}

Exemplo — Atribuir ao Funcionário IA:

{
  "agentId": "agent_456"
}

Exemplo — Adiar:

{
  "status": "snoozed",
  "snoozeUntil": "2025-01-20T09:00:00.000Z"
}

Excluir uma Conversa

DELETE /api/conversations/{conversationId}

⚠️ Excluir uma conversa remove permanentemente todas as mensagens associadas. Esta ação é irreversível.

5. Atualização de Status em Massa

Atualize o status de várias conversas ao mesmo tempo.

POST /api/conversations/update-status
Content-Type: application/json

Corpo da Requisição:

Campo	Tipo	Obrigatório	Descrição
`conversationIds`	`string[]`	✅	Array de IDs de conversas a atualizar
`status`	`"open" \| "resolved" \| "snoozed"`	✅	Novo status para todas as conversas especificadas

Exemplo — Resolver múltiplas conversas:

{
  "conversationIds": ["conv_abc123", "conv_def456", "conv_ghi789"],
  "status": "resolved"
}

Marcar como Não Lidas em Massa

POST /api/conversations/bulk-unread
Content-Type: application/json

Corpo da Requisição:

{
  "conversationIds": ["conv_abc123", "conv_def456"]
}

6. Exportar Conversas

Baixe conversas como arquivo para relatórios, conformidade ou análise.

GET /api/conversations/export

Parâmetros de Query:

Parâmetro	Tipo	Descrição
`status`	`string`	Filtrar por status antes de exportar
`dateFrom`	`ISO 8601`	Exportar conversas a partir desta data
`dateTo`	`ISO 8601`	Exportar conversas até esta data
`format`	`"csv" \| "json"`	Formato de exportação (padrão: `csv`)

7. Avaliando Respostas

Use o endpoint de avaliação para classificar a qualidade das respostas geradas pela IA. Este feedback é usado para melhorar o desempenho da IA ao longo do tempo.

POST /api/conversations/{conversationId}/eval-answer
Content-Type: application/json

Corpo da Requisição:

Campo	Tipo	Obrigatório	Descrição
`messageId`	`string`	✅	ID da mensagem da IA a avaliar
`rating`	`"positive" \| "negative"`	✅	Sua classificação de qualidade
`feedback`	`string`	❌	Feedback escrito opcional

Exemplo:

{
  "messageId": "msg_abc123",
  "rating": "positive",
  "feedback": "Resposta perfeita — precisa e concisa"
}

8. Formato de Resposta

Status Codes

Status	Significado
`200`	Requisição bem-sucedida
`204`	Excluído com sucesso
`400`	Corpo inválido da requisição ou parâmetros inválidos
`401`	Não autenticado
`403`	Permissões insuficientes
`404`	Conversa não encontrada
`500`	Erro interno do servidor

9. Boas Práticas

Gerenciamento de Status

Status	Use Quando
`open`	Conversa ativa e requer atenção
`resolved`	Problema totalmente resolvido — conversa concluída
`snoozed`	Conversa precisa de acompanhamento posterior — reabre automaticamente em `snoozeUntil`

Dicas:

Use a atualização de status em massa para gerenciamento da fila ao final do dia
Defina snoozeUntil para o próximo dia útil para conversas de baixa prioridade
Resolva conversas prontamente para manter a fila limpa

Filtragem e Pesquisa

Combine filtros (ex: status=open&channel=whatsapp&agentId=agent_123) para resultados precisos
Use search para busca por palavra-chave quando lembrar do conteúdo mas não do contato
Exporte subconjuntos filtrados para necessidades específicas de relatório

Avaliação de Respostas da IA

Avalie as respostas da IA regularmente para melhorar o desempenho do modelo
Forneça feedback escrito para avaliações negativas — isso ajuda a identificar padrões
Foque em avaliar respostas onde a IA cometeu um erro factual ou não capturou a intenção

10. Troubleshooting

Problema	Causa Possível	Solução
Conversa não aparece na lista	Filtro errado aplicado	Tente remover os filtros e buscar por contato ou palavra-chave
Atualização de status em massa falha parcialmente	Alguns IDs não pertencem à sua organização	Verifique se todos os IDs de conversa estão corretos
Exportação retorna arquivo vazio	Nenhuma conversa corresponde ao filtro de data/status	Amplie o intervalo de datas ou remova o filtro de status
Não é possível excluir uma conversa	Conversa vinculada a uma sessão ativa do widget	Aguarde a sessão terminar ou contate o suporte
Avaliação de resposta rejeitada	`messageId` não é uma mensagem gerada por IA	Apenas mensagens geradas por IA podem ser avaliadas

Agent Skills

Agent Cortex

Livia - 360 Assistant

Conversations

Access Groups

🔢 Sumário

1. Visão Geral

O que é uma Conversa?

Colaboração IA e Humano

2. Referência de Endpoints

3. Listando Conversas

Listar Conversas

4. Gerenciando uma Conversa

Obter uma Conversa

Atualizar uma Conversa

Excluir uma Conversa

5. Atualização de Status em Massa

Marcar como Não Lidas em Massa

6. Exportar Conversas

7. Avaliando Respostas

8. Formato de Resposta

Status Codes

9. Boas Práticas

Gerenciamento de Status

Filtragem e Pesquisa

Avaliação de Respostas da IA

10. Troubleshooting

​🔢 Sumário

​1. Visão Geral

​O que é uma Conversa?

​Colaboração IA e Humano

​2. Referência de Endpoints

​3. Listando Conversas

​Listar Conversas

​4. Gerenciando uma Conversa

​Obter uma Conversa

​Atualizar uma Conversa

​Excluir uma Conversa

​5. Atualização de Status em Massa

​Marcar como Não Lidas em Massa

​6. Exportar Conversas

​7. Avaliando Respostas

​8. Formato de Resposta

​Status Codes

​9. Boas Práticas

​Gerenciamento de Status

​Filtragem e Pesquisa

​Avaliação de Respostas da IA

​10. Troubleshooting

🔢 Sumário

1. Visão Geral

O que é uma Conversa?

Colaboração IA e Humano

2. Referência de Endpoints

3. Listando Conversas

Listar Conversas

4. Gerenciando uma Conversa

Obter uma Conversa

Atualizar uma Conversa

Excluir uma Conversa

5. Atualização de Status em Massa

Marcar como Não Lidas em Massa

6. Exportar Conversas

7. Avaliando Respostas

8. Formato de Resposta

Status Codes

9. Boas Práticas

Gerenciamento de Status

Filtragem e Pesquisa

Avaliação de Respostas da IA

10. Troubleshooting