API Pública do Tivar

Documentação dos endpoints públicos e webhooks outbound do Tivar.

Base URL: https://<seu-dominio>
Autenticação: todos os endpoints exigem Authorization: Bearer <workspace_api_key>
Rate limit: 60 requisições por minuto por workspace (exceto /api/external/messages/send — sem rate limit próprio)

Obtenha sua API Key em: Configurações → Workspace → API Key

---

Endpoints

1. POST /api/v1/send-message

Envia uma mensagem de texto para um número de telefone. Cria o contato e a conversa automaticamente se ainda não existirem.

Canais suportados: WhatsApp Oficial (Meta Cloud API), WhatsApp Lite e WhatsApp via UAZAPI.

Headers

Body

Boa prática para automações: sempre passe contactName com o nome real do lead/cliente. Sem ele, o contato é criado sem nome e fica difícil de identificar no painel.

Exemplo de requisição

curl -X POST https://<seu-dominio>/api/v1/send-message \
  -H "Authorization: Bearer sk_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "5511999998888",
    "message": "Olá! Seu pedido foi confirmado.",
    "channel": "whatsapp-official",
    "contactName": "João Silva"
  }'

Resposta de sucesso — 200 OK

{
  "success": true,
  "conversationId": "uuid-da-conversa",
  "contactId": "uuid-do-contato",
  "messageId": "uuid-da-mensagem",
  "waMessageId": "wamid.xxxxx",
  "contactCreated": false,
  "conversationCreated": false,
  "sent_at": "2026-04-23T10:00:00.000Z"
}

Erros possíveis

---

2. POST /api/v1/send-template

Envia um template HSM (mensagem estruturada pré-aprovada pela Meta) via WhatsApp Oficial. Único método válido para iniciar contato com números que não interagiram nas últimas 24 horas.

Canal suportado: WhatsApp Oficial (whatsapp-official) apenas.

Headers

Body

Boa prática para automações (n8n, Make, etc.): sempre passe contactName. Este campo é o que define o nome exibido na conversa dentro do Tivar. Se não for enviado, o painel exibirá apenas o número de telefone no lugar do nome.

Exemplo de requisição

curl -X POST https://<seu-dominio>/api/v1/send-template \
  -H "Authorization: Bearer sk_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "5511999998888",
    "channel": "whatsapp-official",
    "templateName": "confirmacao_pedido",
    "language": "pt_BR",
    "variables": ["João", "Pedido #1234", "R$ 150,00"],
    "contactName": "João Silva"
  }'

As variáveis substituem {{1}}, {{2}}, {{3}} na ordem em que aparecem no array.

Template com header de mídia (imagem/vídeo/documento)

Se o template aprovado tiver um header de mídia, informe headerMedia — sem isso, o envio falha (Meta exige o header preenchido quando o template foi aprovado com ele).

{
  "phone": "5511999998888",
  "channel": "whatsapp-official",
  "templateName": "confirmacao_com_video",
  "language": "pt_BR",
  "variables": ["João"],
  "headerMedia": {
    "type": "video",
    "link": "https://exemplo.com/video-institucional.mp4"
  },
  "contactName": "João Silva"
}

Template com botão dinâmico (URL com sufixo variável, ou quick reply com payload variável)

Só é necessário declarar buttons se o botão tiver parte dinâmica (ex.: link de rastreio único por pedido). Botão totalmente estático (telefone, ou quick reply fixo) já funciona sozinho, sem precisar disso.

{
  "phone": "5511999998888",
  "channel": "whatsapp-official",
  "templateName": "pedido_confirmado",
  "language": "pt_BR",
  "variables": ["João", "Pedido #1234"],
  "buttons": [
    { "index": 0, "type": "url", "text": "pedido-1234" }
  ],
  "contactName": "João Silva"
}

Resposta de sucesso — 200 OK

{
  "success": true,
  "conversationId": "uuid-da-conversa",
  "contactId": "uuid-do-contato",
  "messageId": "uuid-da-mensagem",
  "waMessageId": "wamid.xxxxx",
  "contactCreated": false,
  "conversationCreated": true,
  "template": {
    "name": "confirmacao_pedido",
    "language": "pt_BR",
    "variables": ["João", "Pedido #1234", "R$ 150,00"],
    "headerMedia": null,
    "buttons": null
  },
  "sent_at": "2026-04-23T10:00:00.000Z"
}

Erros possíveis

---

3. POST /api/external/messages/send

Envia uma mensagem em uma conversa já existente no Tivar. Ideal para integrações como n8n, Typebot e Voiceflow que recebem o conversation_id via webhook e querem responder na mesma conversa.

Canais suportados: WhatsApp Oficial, WhatsApp (UAZAPI), WhatsApp Lite, Telegram, Live Chat.

Diferença em relação ao /api/v1/send-message: este endpoint não cria contato nem conversa — a conversa deve existir previamente. Use quando já tem o conversation_id (por exemplo, recebido num webhook message.received).

Headers

Body

Exemplo de requisição

curl -X POST https://<seu-dominio>/api/external/messages/send \
  -H "Authorization: Bearer sk_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation_id": "uuid-da-conversa",
    "text": "Olá! Em que posso ajudar?",
    "sender_type": "agent",
    "sender_name": "Bot Atendimento"
  }'

Resposta de sucesso — 200 OK

{
  "success": true,
  "message_id": "uuid-da-mensagem",
  "conversation_id": "uuid-da-conversa",
  "workspace_id": "uuid-do-workspace",
  "sent_at": "2026-04-23T10:00:00.000Z"
}

Erros possíveis

---

4. PATCH /api/v1/leads/{id}

Move um contato para outra etapa de um funil (Kanban) sem passar pelo agente de IA. Pensado para integrações externas (n8n, Make) que já decidem o roteamento sozinhas e não devem depender de um agente de IA do Tivar rodando na mesma conversa — evita dois sistemas respondendo o mesmo lead.

Diferença em relação a mover pelo agente de IA: o agente de IA (move_funnel_stage) analisa a conversa e decide sozinho a etapa. Este endpoint espera que você já saiba pipeline_id e stage e só quer aplicar a mudança.

Headers

Parâmetro de URL

Body

Exemplo de requisição

curl -X PATCH https://<seu-dominio>/api/v1/leads/uuid-do-contato \
  -H "Authorization: Bearer sk_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "pipeline_id": "uuid-do-funil",
    "stage": "Qualificado",
    "conversation_id": "uuid-da-conversa"
  }'

Resposta de sucesso — 200 OK

{
  "success": true,
  "contact_id": "uuid-do-contato",
  "pipeline_id": "uuid-do-funil",
  "stage": "Qualificado"
}

Erros possíveis

---

Webhooks Outbound

O Tivar dispara eventos para URLs externas configuradas no painel, permitindo integração com n8n, Typebot, Zapier e outros.

Não confundir com o webhook de um agente de IA. Se você já tem um agente externo (aba "Webhook" dentro do agente) respondendo pelas conversas, não cadastre a mesma URL aqui também — os dois disparam de forma independente, e a mesma mensagem chegaria 2x no seu sistema. Use o webhook genérico só pra eventos que não são sobre "responder o cliente" (log de mensagens, integrações de CRM/BI, notificações internas).

Como configurar

1. Acesse Configurações → Webhooks.
2. Clique em Novo webhook.
3. Informe a URL de destino (deve aceitar POST com JSON).
4. Selecione os eventos desejados.
5. Recomendado: informe um segredo para validar a autenticidade dos payloads via HMAC.

Por que configurar o segredo. A URL do seu webhook é um endpoint aberto na internet: sem segredo, qualquer pessoa que descubra esse endereço pode enviar um POST fingindo ser o Tivar, e seu fluxo não tem como diferenciar. Dependendo do que ele faz — criar pedido, disparar cobrança, responder cliente — o estrago é real. Com o segredo configurado, todo payload chega assinado e você rejeita o que não bater.

Headers enviados em todo webhook

Compatibilidade. Cada um desses três também é enviado com o prefixo antigo — X-Tivar-Event, X-Tivar-Timestamp e X-Tivar-Signature — com exatamente o mesmo valor. Integrações existentes continuam funcionando sem alteração; em integrações novas, prefira os nomes X-Webhook-*.

Validando a assinatura

Com o segredo configurado, valide assim — e rejeite a requisição quando a assinatura não bater ou o header não vier:

const crypto = require('crypto')

function isValidSignature(body, secret, signatureHeader) {
  // Header ausente = requisição não confiável. Nunca deixe passar.
  if (!signatureHeader) return false

  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(body)
    .digest('hex')

  const a = Buffer.from(expected)
  const b = Buffer.from(signatureHeader)

  // timingSafeEqual lança exceção se os buffers tiverem tamanhos diferentes —
  // compare o tamanho antes, senão uma assinatura torta derruba seu endpoint.
  return a.length === b.length && crypto.timingSafeEqual(a, b)
}

body = string JSON raw do payload recebido (antes de parsear). signatureHeader = valor do header X-Webhook-Signature.

n8n: cuidado com "raw body". O node Webhook do n8n já entrega o payload PARSEADO (objeto JS) pro node seguinte — se um Code node faz JSON.stringify() nesse objeto pra calcular o HMAC, a string quase nunca bate byte a byte com a que o Tivar assinou (ordem de chave, espaçamento, escape) e a assinatura nunca vai validar, mesmo com o segredo certo. Achado real (parceiro white label, 2026-08-24). Fix: no node Webhook, aba Options → Raw Body, ative — aí o Code node recebe a string exata ($input.item.binary.data ou o campo que o n8n expõe pra raw body, dependendo da versão) pra assinar/comparar antes de qualquer parse.

---

Eventos disponíveis

Ao configurar o webhook você pode selecionar eventos individuais ou * para receber todos.

---

message.received

Disparado quando uma nova mensagem chega de um contato externo.

{
  "event": "message.received",
  "workspace_id": "uuid-do-workspace",
  "conversation_id": "uuid-da-conversa",
  "contact": {
    "id": "uuid-do-contato",
    "phone": "5511999998888",
    "name": "João Silva"
  },
  "message": {
    "id": "uuid-da-mensagem",
    "text": "Oi, quero saber sobre meu pedido.",
    "type": "text"
  },
  "status": {
    "assigned_to_type": "agent",
    "assigned_to_id": "uuid-do-agente"
  },
  "integration": {
    "id": "uuid-da-integracao",
    "provider": "whatsapp-official"
  }
}

---

message.sent

Disparado quando o Tivar envia uma mensagem para um contato (via painel, API ou agente de IA).

{
  "event": "message.sent",
  "workspace_id": "uuid-do-workspace",
  "conversation_id": "uuid-da-conversa",
  "message": {
    "id": "uuid-da-mensagem",
    "text": "Seu pedido foi confirmado!",
    "type": "text"
  },
  "status": {
    "sender_type": "human"
  },
  "integration": {
    "id": "uuid-da-integracao",
    "provider": "whatsapp-official"
  }
}

---

conversation.assigned

Disparado quando uma conversa é atribuída ou reatribuída a um membro humano ou agente de IA. Também disparado ao remover a atribuição (assigned_to_id: null).

{
  "event": "conversation.assigned",
  "workspace_id": "uuid-do-workspace",
  "conversation_id": "uuid-da-conversa",
  "status": {
    "assigned_to_type": "agent",
    "assigned_to_id": "uuid-do-agente"
  }
}

---

conversation.resolved

Disparado quando uma conversa é marcada como resolvida.

{
  "event": "conversation.resolved",
  "workspace_id": "uuid-do-workspace",
  "conversation_id": "uuid-da-conversa",
  "status": {
    "value": "resolved"
  }
}

---

Fluxo recomendado para automações (n8n / Typebot)

1. Configure um webhook "message.received" no Tivar apontando para seu fluxo n8n.
2. O n8n recebe o payload e processa a mensagem (contact.phone, message.text).
3. Para responder na mesma conversa, use POST /api/external/messages/send
   com o conversation_id recebido no payload.
4. Para iniciar uma conversa nova (disparo ativo), use POST /api/v1/send-message.
5. Para disparar fora da janela 24h do WhatsApp Oficial, use POST /api/v1/send-template.

---

Resumo rápido