Skip to main content
Um contato é qualquer pessoa que interage com sua equipe por meio de um canal conectado ao Tivar. O Tivar cria e gerencia contatos de forma automática, mas você também pode criá-los via API ao iniciar uma conversa ativa.

​
Como os contatos são identificados

Contatos são identificados pelo identificador do canal em que interagem:
  • WhatsApp e Telegram: número de telefone normalizado (ex.: 5511999998888)
  • Outros canais: identificador específico do canal
O campo phone no payload do webhook sempre aparece no formato normalizado, sem espaços, traços ou o sinal +.

​
Criação automática de contatos

O Tivar cria um contato automaticamente em duas situações:

Mensagem recebida

Quando uma mensagem chega de um número que ainda não existe na sua base de contatos, o Tivar cria o contato automaticamente antes de criar a conversa.

API send-message

Ao chamar POST /api/v1/send-message com um número ainda não cadastrado, o Tivar cria o contato na hora. A resposta inclui "contactCreated": true para indicar que a criação ocorreu.
{
  "success": true,
  "conversationId": "uuid-da-conversa",
  "contactId": "uuid-do-contato",
  "messageId": "uuid-da-mensagem",
  "contactCreated": true,
  "conversationCreated": true
}

​
Definindo o nome do contato via API

Ao criar um contato via API, você pode informar um nome de exibição usando o campo contactName. Esse nome é salvo apenas no momento da criação — se o contato já existir, o campo é ignorado. 
{
  "phone": "5511999998888",
  "message": "Olá! Seu cadastro foi confirmado.",
  "channel": "whatsapp-official",
  "contactName": "Maria Souza"
}
O campo contactName só tem efeito quando contactCreated retorna true. Para contatos existentes, atualize o nome diretamente pelo painel do Tivar.

​
O contact.id

Cada contato possui um UUID único (contact.id) que aparece nos payloads de webhook. Use esse identificador para correlacionar eventos de diferentes conversas com o mesmo contato em seus sistemas externos.

​
Campos do contato nos webhooks

O objeto contact aparece nos eventos message.received com os seguintes campos:
CampoTipoDescrição
idstring | nullUUID do contato no Tivar
phonestring | nullNúmero normalizado (somente dígitos)
namestring | nullNome de exibição do contato
{
  "contact": {
    "id": "uuid-do-contato",
    "phone": "5511999998888",
    "name": "Maria Souza"
  }
}
Os campos id, phone e name podem ser null em cenários onde o contato ainda não foi totalmente criado ou o canal não fornece essas informações.