Skip to main content
Uma conversa é o fio de mensagens trocadas entre sua equipe (ou agentes de IA) e um contato específico em um canal conectado. Cada conversa pertence a um único contato e a uma única integração — por exemplo, uma conversa no WhatsApp é diferente de uma conversa no Telegram com o mesmo contato.

​
Como conversas são criadas

As conversas no Tivar surgem de duas formas:

Automaticamente

Quando uma nova mensagem chega de um contato por qualquer canal conectado, o Tivar cria a conversa automaticamente — sem nenhuma ação da sua parte.

Via API

Ao chamar POST /api/v1/send-message com um número que ainda não possui conversa aberta, o Tivar cria o contato e a conversa automaticamente. A resposta inclui "conversationCreated": true quando isso ocorre.

​
Estados de uma conversa

A conversa está ativa e aguardando atendimento ou continuidade. É o estado inicial de toda nova conversa.
A conversa foi direcionada a um responsável — um membro humano da equipe ou um agente de IA. O campo assigned_to_type no payload do webhook indica se o responsável é "human" ou "agent".
A conversa foi marcada como encerrada. O webhook conversation.resolved é disparado nesse momento.

​
Atribuição de conversas

Você pode atribuir uma conversa a um membro humano diretamente pelo painel do Tivar. Para atribuir a um agente de IA via API, passe o parâmetro agentId (UUID) no corpo das requisições POST /api/v1/send-message ou POST /api/v1/send-template: 
{
  "phone": "5511999998888",
  "message": "Olá! Como posso ajudar?",
  "channel": "whatsapp-official",
  "agentId": "uuid-do-agente-de-ia"
}
Quando uma conversa é atribuída ou reatribuída, o Tivar dispara o evento conversation.assigned para seus webhooks configurados.

​
O conversation_id

Cada conversa possui um UUID único chamado conversation_id. Esse identificador é usado em:
  • Respostas da API (conversationId nos endpoints /api/v1/send-message e /api/v1/send-template)
  • O endpoint POST /api/external/messages/send, que exige o conversation_id para enviar uma mensagem em uma conversa já existente
  • Payloads de todos os eventos de webhook
O campo aparece como conversationId (camelCase) nas respostas dos endpoints /api/v1/ e como conversation_id (snake_case) no endpoint /api/external/messages/send e nos payloads de webhook.

​
Eventos de webhook relacionados

EventoQuando dispara
conversation.assignedConversa atribuída, reatribuída ou com atribuição removida
conversation.resolvedConversa marcada como resolvida
Veja o payload completo de cada evento na referência de webhooks.
Para automações com n8n ou Typebot, capture o conversation_id do evento message.received e use-o no endpoint POST /api/external/messages/send para responder na mesma conversa sem precisar criar uma nova.