Bem-vindo ao YaClin

O que é o YaClin

O YaClin é um CRM feito exclusivamente para clínicas médicas, odontológicas e estéticas. Ele centraliza toda a comunicação com pacientes (WhatsApp, Instagram, Messenger, Email), gerencia leads em funis Kanban, automatiza tarefas repetitivas e oferece relatórios completos para você tomar decisões com dados.

Criando sua conta

1. Acesse app.yaclin.com/registro
   Preencha seu nome, email, telefone e crie uma senha.
2. Confirme seu email
   Verifique sua caixa de entrada e clique no link de confirmação.
3. Configure sua empresa
   Insira o nome da clínica, CNPJ (opcional), especialidade e endereço.
4. Comece a usar
   Você será redirecionado ao dashboard principal. O teste gratuito de 14 dias já está ativo.

Visão geral do Dashboard

O dashboard principal mostra em tempo real:

• Leads novos — quantidade de leads captados hoje, na semana e no mês
• Conversas ativas — mensagens pendentes e tempo médio de resposta
• Funil de vendas — resumo visual das etapas do funil
• Tarefas — tarefas vencendo hoje e atrasadas
• Métricas de campanhas — investimento, leads e custo por lead (se integrações ativas)
• Ranking da equipe — gamificação com pontos, streaks e conquistas

Primeiros Passos

Configurando sua empresa

Acesse Configurações > Empresa para preencher os dados da sua clínica:

• Nome da empresa e CNPJ
• Endereço completo
• Logo (recomendado: 256x256px, PNG ou JPG)
• Especialidades oferecidas
• Fuso horário

Adicionando membros da equipe

Em Configurações > Equipe, você pode convidar membros:

1. Clique em "Convidar Membro"
   Insira o email do colaborador.
2. Selecione a função
   

   Função	Permissões
   ADMIN	Acesso total: configurações, financeiro, equipe, todas as funcionalidades
   MANAGER	Gerencia leads, chat, funis, relatórios. Sem acesso a cobrança e equipe
   AGENT	Atende chat, gerencia leads atribuídos, cria tarefas
   VIEWER	Somente visualização de dashboards e relatórios

3. O membro recebe um convite por email
   Ele cria a senha e já acessa o sistema.

Configurando horário comercial

Em Configurações > Atendimento, defina os horários de funcionamento da clínica para cada dia da semana. Mensagens recebidas fora do horário comercial ativam a resposta automática configurada.

Configurando feriados

Na mesma área de Atendimento, você pode:

• Feriados nacionais — ative os feriados brasileiros pré-cadastrados
• Feriados personalizados — adicione datas específicas da sua cidade ou clínica (ex: aniversário da cidade, recesso)

Nos feriados, o sistema se comporta como fora do horário comercial — envia resposta automática e não atribui leads automaticamente.

WhatsApp

O YaClin suporta 5 provedores de WhatsApp. Os dois principais são a Evolution API (não-oficial, via QR Code) e a API Oficial do Meta (Cloud API). Você pode ter múltiplas conexões ativas simultaneamente.

Evolution API

A Evolution API é a forma mais rápida de conectar seu WhatsApp ao YaClin. Funciona escaneando um QR Code, similar ao WhatsApp Web. É uma solução open-source e self-hosted.

Requisitos

Opção 1 — Conexão rápida (servidor YaClin)

1. Acesse Conexões WhatsApp
   No menu lateral, clique em "Conexões WhatsApp".
2. Clique em "Conectar Número"
   Selecione o provedor Evolution API.
3. Preencha nome e telefone
   O nome é apenas para identificação interna (ex: "Comercial", "Recepção"). Os campos URL, API Key e Nome da Instância serão preenchidos automaticamente.
4. Clique em "Conectar"
   A instância será criada automaticamente no servidor.
5. Escaneie o QR Code
   Abra o WhatsApp no celular > Dispositivos conectados > Conectar dispositivo > Escaneie o QR exibido.

Opção 2 — Sua própria instância (self-hosted)

Se você já possui uma instância Evolution API rodando no seu servidor, pode conectá-la diretamente ao YaClin.

1. Acesse Conexões WhatsApp
   No menu lateral, clique em "Conexões WhatsApp".
2. Clique em "Conectar Número"
   Selecione o provedor Evolution API.
3. Preencha os campos
   Informe a URL da sua instância, a API Key e um nome para a instância.
4. Clique em "Conectar"
   O YaClin detecta automaticamente se sua instância é v1 ou v2 e configura tudo.
5. Escaneie o QR Code
   Abra o WhatsApp no celular > Dispositivos conectados > Conectar dispositivo > Escaneie o QR exibido.

Campos do formulário

Testando a conexão

Após escanear o QR Code, o status da conexão deve mudar para CONNECTED. A versão detectada da Evolution API (v1 ou v2) será exibida nos detalhes da conexão. Envie uma mensagem de teste para confirmar que o sistema está recebendo e enviando mensagens.

Versões suportadas — v1 vs v2

Perguntas frequentes

Limites e boas práticas

• Limite diário: Envie no máximo 200 a 300 mensagens por dia por número.
• Sem disparos em massa: Não use a Evolution API para campanhas de marketing ou envios em larga escala. Para isso, use a API Oficial do Meta.
• Intervalo entre mensagens: O YaClin já aplica delays automáticos entre envios para simular comportamento humano.
• Número novo: Se for um número recém-criado no WhatsApp, comece com volume baixo (20-50 msgs/dia) e aumente gradualmente ao longo de 2 semanas.
• Conteúdo repetitivo: Evite enviar a mesma mensagem para muitos contatos em sequência — varie o conteúdo.

API Oficial (Meta Cloud API)

A API Oficial do WhatsApp Business é fornecida diretamente pelo Meta. Oferece estabilidade total, coexistência com o app do celular e suporte a templates oficiais aprovados.

Diferenças entre Evolution e API Oficial

Coexistência

Com a API Oficial, você pode usar o WhatsApp no celular ao mesmo tempo que o CRM envia e recebe mensagens. Isso não é possível com a Evolution API.

Criando o App no Meta Developers

1. Acesse developers.facebook.com
   Faça login com sua conta do Facebook.
2. Crie um novo App
   Tipo: "Business" > Selecione "WhatsApp" como produto.
3. Acesse WhatsApp > API Setup
   Aqui você encontra o Phone Number ID, WABA ID e Access Token.
4. Gere um token permanente
   O token temporário expira em 24h. Para gerar um permanente, acesse Business Settings > System Users > Gere token com permissões whatsapp_business_messaging e whatsapp_business_management.

Campos necessários

Configurando o Webhook

Para receber mensagens no YaClin, você precisa configurar o webhook no painel do Meta:

1. URL do Webhook:
   https://app.yaclin.com/api/webhooks/whatsapp/meta
2. Verify Token:
   Gerado automaticamente pelo sistema (visível nas configurações da conexão).
3. Campos assinados:
   Marque messages e message_status.

Templates oficiais

A API Oficial exige que mensagens iniciadas pela empresa (fora da janela de 24h) usem templates aprovados pelo Meta.

• Criar template: No painel do Meta Business > WhatsApp > Message Templates.
• Enviar para aprovação: O Meta revisa em até 24h.
• Usar no YaClin: Templates aprovados aparecem automaticamente na tela de disparos.

Embedded Signup

O Embedded Signup permite conectar a API Oficial do WhatsApp com 1 clique, sem precisar configurar manualmente no Meta Developers.

1. Clique no botão "Conectar com 1 clique"
   Você será redirecionado para o Meta para autorizar.
2. Selecione seu perfil do Facebook Business
   Se não tiver, crie um durante o processo.
3. Escolha o número de telefone
   Pode ser um novo ou migrar um existente.
4. Pronto!
   O YaClin configura automaticamente Phone Number ID, WABA ID e Access Token.

Roteamento de Conversas por Número

Uma das funcionalidades mais importantes do YaClin é poder ter dois números de WhatsApp diferentes, cada um com uma função específica dentro da sua clínica. Isso organiza o atendimento e evita confusão entre leads novos (vindos de anúncios) e clientes já cadastrados.

Como funciona

Cada conexão de WhatsApp que você cadastra no YaClin pode ter um dos 3 propósitos abaixo:

• Leads (campanhas) — Número que está cadastrado nos seus anúncios do Meta Ads, Google Ads, Instagram e Facebook. Todo contato novo que chegar por este número é automaticamente cadastrado como lead e direcionado para a atendente comercial.
• Recepção (clientes) — Número que é usado para atendimento geral aos clientes já cadastrados. Contatos recebidos aqui não viram leads automaticamente e só aparecem para o usuário com cargo de Recepcionista. Ideal para quem só recebe ligações e mensagens de pacientes já cadastrados.
• Geral — Comportamento padrão, sem filtragem. Todas as conversas aparecem para todos os usuários (exceto atendentes, que sempre veem só o que é atribuído a elas).

Passo a passo para configurar

1. Acesse Conexões WhatsApp
   No menu lateral, clique em Conexões WhatsApp.
2. Cadastre os dois números
   Se você ainda não tem dois números conectados, clique em Nova Conexão e siga o processo para cada um. Um número será o dos anúncios, o outro o da recepção.
3. Defina o propósito de cada conexão
   No card de cada conexão cadastrada, no rodapé, você verá um seletor chamado Propósito da Conexão. Escolha:
   • Para o número dos anúncios → Leads (campanhas)
   • Para o número da recepção → Recepção (clientes)
4. Salva automático
   A escolha é salva imediatamente. A partir deste momento, todo contato novo que chegar por aquele número seguirá a regra definida.

Cadastrando a Recepcionista

Para que o número de recepção funcione corretamente, você precisa cadastrar um usuário específico com o cargo de Recepcionista. Este usuário terá acesso apenas às conversas do número de recepção e não verá leads de campanhas.

Passo a passo

1. Acesse Configurações > Usuários e Equipe
2. Clique em "Convidar Membro"
3. Preencha os dados do cadastro
   • Nome: nome da pessoa que vai atender a recepção
   • E-mail: recepcionista@suaclinica.com.br (o e-mail que ela vai usar para fazer login)
   • Cargo (Role): selecione Recepcionista
4. Envie o convite
   Ela vai receber um e-mail com o link para criar a senha e acessar o sistema.
5. Pronto!
   A partir do primeiro login, ela só vai ver as conversas vindas do número de Recepção. Não vai ter acesso a leads de campanha, relatórios sensíveis ou configurações do sistema.

Lembretes Automáticos de Consulta

O YaClin envia lembretes automáticos por WhatsApp para seus pacientes antes da consulta. Você configura as mensagens uma vez e o sistema dispara na data certa, sem precisar da sua intervenção.

Como funciona

• O sistema verifica os agendamentos a cada hora
• Envia um lembrete prévio (por exemplo, 1 dia antes da consulta)
• Envia um lembrete no dia da consulta (por exemplo, às 8h da manhã)
• As mensagens são enviadas pelo mesmo número de WhatsApp que você tem conectado ao sistema
• Você pode personalizar totalmente o texto usando variáveis dinâmicas

Passo a passo para configurar

1. Acesse Configurações > Lembretes de Consulta
   No menu de configurações do sistema.
2. Ative a função
   Ligue o botão Ativar lembretes.
3. Escolha quantos dias antes enviar o primeiro lembrete
   Pode ser de 1 até 7 dias antes da consulta. O mais comum é 1 dia.
4. Ative o lembrete do dia da consulta
   Ligue também o botão Enviar no dia e escolha o horário (ex: 08:00). Esse lembrete vai cair no WhatsApp do paciente logo cedo para ele não esquecer.
5. Personalize os textos das mensagens
   Use as variáveis abaixo para deixar cada mensagem personalizada:
   • {{nome}} — nome do paciente
   • {{procedimento}} — procedimento ou título da consulta
   • {{profissional}} — nome do profissional
   • {{data}} — data da consulta (DD/MM/AAAA)
   • {{horario}} — horário da consulta (HH:MM)
   • {{clinica}} — nome da sua clínica
6. Clique em Salvar

Exemplo de mensagens

Lembrete prévio (1 dia antes):

Olá {{nome}}! Lembramos que você tem um agendamento
de {{procedimento}} com {{profissional}}
no dia {{data}} às {{horario}} na {{clinica}}.
Por favor, confirme sua presença respondendo esta mensagem.

Lembrete do dia da consulta (08:00):

Bom dia, {{nome}}! Hoje você tem um agendamento
de {{procedimento}} com {{profissional}}
às {{horario}} na {{clinica}}. Te esperamos!

Integrações

O YaClin se conecta com as principais plataformas para centralizar seus dados de marketing, agenda e comunicação.

Meta Ads (Facebook / Instagram Ads)

Conecte sua conta de anúncios do Meta para ver métricas de campanhas dentro do CRM e criar públicos personalizados automaticamente.

Conectando via OAuth

1. Acesse Integrações > Meta Ads
2. Clique em "Conectar"
   Você será redirecionado ao Facebook para autorizar.
3. Selecione as contas de anúncio
   Escolha quais contas o YaClin pode acessar.
4. Pronto!
   Métricas de campanhas aparecem no dashboard automaticamente.

Públicos personalizados (Audiências)

O YaClin pode criar automaticamente audiências no Meta Ads a partir de segmentos de leads:

• Leads que agendaram consulta
• Leads que não responderam em 7 dias
• Pacientes ativos (para remarketing)

Acesse Audiências no menu lateral para gerenciar.

Google Ads + Calendar

Google Ads

Conecte sua conta do Google Ads para visualizar métricas de campanhas de pesquisa e display dentro do YaClin.

Google Calendar

Sincronize sua agenda do Google com as tarefas do YaClin:

• Tarefas criadas no YaClin aparecem no Google Calendar
• Eventos do Calendar com tags específicas viram tarefas no CRM
• Sincronização bidirecional automática

Como conectar

1. Acesse Integrações > Google
2. Clique em "Conectar com Google"
   Autorize o acesso ao Google Ads e Calendar.
3. Selecione a conta de anúncios (se aplicável)
4. Selecione o calendário para sincronizar tarefas.

Gmail / Outlook

Conecte seu email para enviar e receber mensagens diretamente pelo CRM, com tracking de aberturas e cliques.

• Gmail: Autorização via OAuth (Google)
• Outlook: Autorização via OAuth (Microsoft)

Após conectar, você pode enviar emails pelo chat do lead e ver o histórico completo de comunicação.

Instagram DM

Receba e responda mensagens do Instagram Direct dentro do YaClin.

1. Acesse Integrações > Instagram
2. Conecte sua conta do Instagram Business
   É necessário ter uma conta Business ou Creator vinculada a uma Página do Facebook.
3. Autorize as permissões de mensagens

Mensagens recebidas no DM aparecem no Chat do YaClin no canal "Instagram".

Facebook Messenger

Similar ao Instagram DM, o Messenger permite receber e enviar mensagens pela Página do Facebook.

1. Acesse Integrações > Messenger
2. Selecione a Página do Facebook
3. Autorize as permissões

TikTok Ads

Em breve

A integração com o TikTok Ads está em desenvolvimento. Permitirá visualizar métricas de campanhas e criar audiências personalizadas a partir do CRM.

Chat

O chat é o coração do YaClin. Todas as conversas de todos os canais (WhatsApp, Instagram, Messenger, Email) são centralizadas aqui.

Interface do chat (3 painéis)

Filtros

• Não lidas — mostra apenas conversas com mensagens não lidas
• Fila — conversas aguardando atribuição (sem responsável)
• IA — conversas sendo atendidas pelo agente de IA
• Tags — filtre por tags aplicadas ao lead
• Canal — WhatsApp, Instagram, Messenger, Email

Encerrar e reabrir conversas

Ao encerrar uma conversa, você seleciona um motivo de encerramento (agendou, não tem interesse, respondeu errado, etc). Isso alimenta os relatórios de atendimento.

Conversas encerradas podem ser reabertas a qualquer momento se o paciente enviar uma nova mensagem ou manualmente pelo operador.

Respostas rápidas

Configure textos prontos em Respostas Rápidas para agilizar o atendimento. No chat, digite / seguido da palavra-chave para inserir a resposta.

Exemplo: /preco pode inserir automaticamente a tabela de preços da clínica.

Transferir conversa

Clique no botão de transferir para atribuir a conversa a outro membro da equipe. O histórico completo é mantido.

Leads e Funis

Criando leads

Leads podem ser criados de 3 formas:

• Automaticamente — quando um contato envia mensagem por qualquer canal
• Manualmente — pelo botão "Novo Lead" ou atalho Ctrl+K > "Novo Lead"
• Via API / Webhook — integração com formulários externos, landing pages, etc

Importando leads (CSV/XLSX)

Acesse Leads > Importar para importar uma planilha:

1. Faça upload do arquivo
   Formatos aceitos: .csv, .xlsx. Máximo 10.000 linhas por importação.
2. Mapeie as colunas
   O sistema detecta automaticamente nome, telefone e email. Revise e ajuste se necessário.
3. Selecione o funil e etapa de destino
4. Confirme a importação
   Leads duplicados (mesmo telefone) são detectados e marcados.

Funil Kanban

O funil exibe leads em colunas (etapas) que você pode personalizar. Arraste e solte cards entre as etapas para atualizar o status.

• Cada card mostra: nome, telefone, tags, responsável, tempo na etapa
• Clique no card para abrir o sidebar com todos os detalhes
• Filtros por responsável, tag, fonte e data

Editando etapas do funil

Em Funis > Editar Funil, você pode:

• Adicionar, remover e renomear etapas
• Reordenar etapas arrastando
• Definir cores para cada etapa
• Criar múltiplos funis (ex: "Estética", "Odontologia", "Geral")

Tags e filtros

Tags são etiquetas coloridas aplicadas aos leads para segmentação. Você pode:

• Criar tags personalizadas (ex: "VIP", "Retorno", "Botox")
• Aplicar múltiplas tags por lead
• Filtrar o funil por tags
• Usar tags em automações (ex: ao adicionar tag "Agendou", mover para etapa X)

Scoring de leads

O YaClin calcula automaticamente um score para cada lead baseado em:

O score ajuda a priorizar o atendimento — leads quentes aparecem primeiro.

Automações

Automações executam ações automaticamente quando determinadas condições são atendidas, eliminando trabalho repetitivo.

Tipos de automação

Triggers disponíveis

• Novo lead criado — qualquer canal
• Lead mudou de etapa — no funil
• Mensagem recebida — por canal ou palavra-chave
• Tag adicionada/removida
• Tempo sem resposta — ex: 2h sem resposta
• Agendamento criado
• Data específica — aniversário, retorno

Criando um fluxo

1. Acesse Automações > Novo Fluxo
2. Selecione o trigger
   O que inicia a automação.
3. Adicione as ações
   O que acontece quando o trigger é ativado. Você pode encadear múltiplas ações com delays entre elas.
4. Defina condições (opcional)
   Ex: "Somente se o lead veio do Meta Ads" ou "Somente se não tem responsável".
5. Ative o fluxo

Templates de automação

O YaClin oferece templates prontos para os cenários mais comuns:

• Boas-vindas + coleta de dados
• Follow-up pós-consulta
• Lembrete de retorno (30, 60, 90 dias)
• Pesquisa de satisfação (NPS)
• Reativação de leads inativos

Relatórios

Dashboard principal

O dashboard exibe KPIs em tempo real:

• Total de leads (hoje, semana, mês)
• Taxa de conversão por funil
• Receita estimada
• Leads por fonte (Meta, Google, Orgânico, etc)

Métricas de atendimento

Relatórios por operador

Visualize o desempenho individual de cada membro da equipe:

• Conversas atendidas
• Tempo médio de resposta
• Leads convertidos
• Pontuação de gamificação

Relatórios por canal

Compare o desempenho de cada canal de comunicação:

• WhatsApp vs Instagram vs Messenger vs Email
• Volume de mensagens
• Taxa de resposta
• Conversão por canal

Exportando dados

Todos os relatórios podem ser exportados em .csv ou .xlsx para análise externa. Clique no botão "Exportar" no canto superior direito de cada relatório.

API e Webhooks

O YaClin expõe dois canais para integradores externos: o Webhook de Entrada (criação rápida de leads, sem liberação prévia) e a API V1 (leitura/escrita programática, liberada caso a caso). Além disso, você pode receber notificações em tempo real via Webhooks de Saída.

Visão geral dos canais

Webhook de Entrada — receber leads

Use este endpoint para enviar leads de qualquer ferramenta externa (formulários WordPress, Elementor, RD Station, Leadlovers, Zapier, Make, n8n, Typeform, Google Forms via Apps Script). É o canal mais usado e não exige liberação prévia — basta usar sua API Key.

Endpoint

POST https://app.yaclin.com/api/webhooks/lead

Headers obrigatórios

Content-Type: application/json
X-API-Key: SUA_API_KEY

Exemplo completo

curl -X POST https://app.yaclin.com/api/webhooks/lead \
  -H "Content-Type: application/json" \
  -H "X-API-Key: SUA_API_KEY" \
  -d '{
    "name": "Maria Silva",
    "phone": "(11) 99999-0000",
    "email": "maria@email.com",
    "source": "facebook",
    "company": "Clínica Exemplo",
    "value": 2500,
    "tags": ["estetica", "botox"],
    "metadata": { "interesse": "Harmonização facial" },
    "utm_source": "facebook",
    "utm_medium": "cpc",
    "utm_campaign": "harmonizacao-2026",
    "utm_content": "anuncio-video-1",
    "utm_term": "harmonizacao+rolim"
  }'

Campos aceitos

Resposta

// 200 OK
{ "data": { "id": "clx1234567890", "name": "Maria Silva", "source": "facebook" } }

// 401 — API Key ausente ou inválida
{ "error": "API key required (X-API-Key header)" }

// 429 — limite de requisições excedido
{ "error": "Limite de requisições excedido. Aguarde um momento." }

API V1 — leitura e escrita programática

A API V1 é o canal para integrações que precisam ler dados do CRM (listar leads, conversas) ou que exigem controle de qualidade na criação. Requer liberação prévia pelo suporte (flag apiAccessEnabled).

Solicitar acesso

Envie ao suporte (WhatsApp ou suporte@yaclin.com): nome da organização + caso de uso. A liberação é manual.

Autenticação

Authorization: Bearer SUA_API_KEY

Endpoints disponíveis

GET /api/v1/leads

Query params: limit (1-200, default 50), offset (default 0), status (ACTIVE / WON / LOST / ARCHIVED), source.

curl "https://app.yaclin.com/api/v1/leads?limit=20&status=ACTIVE" \
  -H "Authorization: Bearer SUA_API_KEY"

{
  "data": [
    {
      "id": "clx1234567890",
      "name": "Maria Silva",
      "phone": "11999990000",
      "email": "maria@email.com",
      "source": "META_ADS",
      "status": "ACTIVE",
      "value": 2500,
      "score": 78,
      "createdAt": "2026-05-15T10:30:00Z",
      "updatedAt": "2026-05-15T11:42:00Z"
    }
  ],
  "pagination": { "total": 142, "limit": 20, "offset": 0, "hasMore": true }
}

POST /api/v1/leads

Body JSON. O campo source deve ser um dos valores do enum abaixo (validação estrita).

curl -X POST https://app.yaclin.com/api/v1/leads \
  -H "Authorization: Bearer SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Maria Silva",
    "phone": "11999990000",
    "email": "maria@email.com",
    "source": "API",
    "value": 2500,
    "notes": "Veio do funil do n8n"
  }'

GET /api/v1/conversations

Query params: limit, offset, status (OPEN / CLOSED / WAITING), channel (WHATSAPP / MESSENGER / INSTAGRAM).

{
  "data": [
    {
      "id": "conv_xyz789",
      "contactName": "Maria Silva",
      "contactPhone": "11999990000",
      "lastMessage": "Quero saber sobre harmonização",
      "lastMessageAt": "2026-05-15T11:42:00Z",
      "unreadCount": 2,
      "status": "OPEN",
      "channel": "WHATSAPP",
      "leadId": "clx1234567890",
      "assigneeId": "usr_abc123"
    }
  ],
  "pagination": { "total": 38, "limit": 50, "offset": 0, "hasMore": false }
}

Códigos de erro

Webhooks de Saída — receber eventos do YaClin

Configure URLs do seu sistema que serão notificadas em tempo real quando algo acontecer no CRM. Útil para sincronizar com BI, automatizar fluxos no n8n/Make, alimentar uma IA com eventos de pipeline, etc.

Como cadastrar

1. Acesse Dashboard > API e Webhooks
2. Clique em "Adicionar Webhook" na seção de Webhooks de Saída
3. Cole a URL de destino (ex: https://n8n.suaempresa.com/webhook/yaclin)
4. Selecione os eventos que quer receber (deixe em branco para receber todos)
5. Salve — o YaClin gera um secret único (formato whsec_...) para assinatura HMAC. Guarde com cuidado.

Eventos disponíveis

Payload enviado

POST <sua-url>
Content-Type: application/json
X-Yaclin-Signature: <hmac-sha256-do-body>
X-Yaclin-Event: lead.created

{
  "event": "lead.created",
  "timestamp": "2026-05-15T10:30:00Z",
  "organizationId": "org_abc",
  "data": {
    "id": "clx1234567890",
    "name": "Maria Silva",
    "phone": "11999990000",
    "email": "maria@email.com",
    "source": "META_ADS",
    "status": "ACTIVE",
    "value": 2500
  }
}

Verificação da assinatura (recomendado)

O YaClin assina cada payload com HMAC SHA-256 usando o secret do seu webhook. Compare a assinatura recebida no header X-Yaclin-Signature com o que você calcular do body bruto:

// Node.js
const crypto = require('crypto');
const expected = crypto
  .createHmac('sha256', WEBHOOK_SECRET)
  .update(rawBody) // body como string, antes de fazer JSON.parse
  .digest('hex');
const ok = expected === req.headers['x-yaclin-signature'];

Tempo de resposta e retentativas

• Timeout de 5 segundos por requisição
• Falhas (timeout, 5xx, erro de rede) entram na fila de retry
• Sua URL deve responder com 2xx rápido — processe assincronamente do lado de cá

n8n + Agente IA no WhatsApp

Guia completo para conectar um agente de IA (n8n + Claude/GPT) ao WhatsApp da sua empresa, com os leads e conversas centralizados no YaClin. Este é o caso de uso mais procurado para clínicas, advocacia, e-commerce e serviços que querem atendimento automatizado 24/7 sem perder a visão centralizada do CRM.

Visão geral da arquitetura

Existem três padrões viáveis. O padrão A (recomendado) é o que entrega melhor performance e desacopla a IA do CRM. Os outros são variações para casos específicos.

Padrão A — n8n recebe direto da Evolution (recomendado)

WhatsApp do cliente
        ↓
Evolution API (sua instância)
        ↓
   ┌────┴────┐
   ↓         ↓
YaClin      n8n
(salva     (IA processa
chat,      e responde)
cria lead)     ↓
            Evolution API
                ↓
         WhatsApp do cliente
                ↓
         YaClin recebe o eco
         da mensagem enviada

Por que esse é o recomendado:

• Baixa latência — a IA responde sem passar pelo CRM
• YaClin não vira gargalo — se o CRM cair, a IA continua atendendo
• Tudo aparece no chat do YaClin (mensagens recebidas e enviadas), porque a Evolution ecoa as mensagens enviadas via API de volta no webhook
• Você mantém a visão única do paciente/cliente no YaClin (lead + histórico + funil)

Padrão B — n8n consome eventos do YaClin (pipeline reativo)

Quando você quer que o n8n reaja a eventos do CRM (não a cada mensagem). Ex: novo lead chegou → IA qualifica → cria tarefa no Asana → envia mensagem de boas-vindas via Evolution.

YaClin (lead.created) → Outbound Webhook → n8n → IA decide → ações

Padrão C — n8n só envia leads PARA o YaClin (mais simples)

Para integrar formulários, ferramentas externas, planilhas, ou outro CRM. A IA do n8n qualifica e enriquece o lead antes de mandar.

Form / Planilha / IA → n8n → POST /api/webhooks/lead → YaClin

Padrão A — Setup completo passo a passo

Passo 1 — Configure a Evolution API com webhook duplo

A Evolution API permite enviar o webhook de mensagens para múltiplas URLs. Você precisa configurar duas:

1. Acesse o painel da sua Evolution API (ex: https://evolution.suaempresa.com/manager)
2. Selecione a instância conectada ao número da empresa
3. Configure dois webhooks de saída (em alguns painéis, "Webhook URLs" aceita lista; em outros, você precisa usar um broker tipo n8n na frente):
   • URL 1 (YaClin): https://app.yaclin.com/api/webhooks/whatsapp
   • URL 2 (n8n): https://n8n.suaempresa.com/webhook/whatsapp-ia (use o nó "Webhook" do n8n para gerar essa URL)
4. Marque o evento messages.upsert em ambos (é o evento de mensagem nova)
5. Salve e teste mandando uma mensagem WhatsApp para o número da empresa — ambos endpoints devem receber

Passo 2 — Monte o fluxo no n8n

Fluxo mínimo viável para um agente de IA respondendo no WhatsApp:

[Webhook trigger]
   ↓ (recebe payload da Evolution)
[Filter: fromMe = false]   ← ignora mensagens enviadas pela própria empresa
   ↓
[Set: extrair telefone, nome, texto da mensagem]
   ↓
[Memory: buscar histórico do contato]   ← Redis, Postgres ou n8n Data Tables
   ↓
[AI Agent (Claude/GPT)]
   ↓ (gera resposta com base no system prompt + histórico)
[HTTP Request: enviar resposta via Evolution]
   POST https://evolution.suaempresa.com/message/sendText/{instance}
   ↓
[Memory: salvar mensagem do bot no histórico]

Passo 3 — Configure o nó AI Agent

System prompt sugerido (adapte ao seu negócio):

Você é a recepcionista virtual da Clínica Exemplo.
Sua função: qualificar o lead (entender o que ele quer),
agendar consulta quando possível, e transferir para humano
quando o lead pedir ou quando a conversa sair do escopo.

Tom: profissional, empático, brasileiro, sem emojis em excesso.
Nunca prometa preços específicos sem confirmar com o humano.
Sempre confirme nome e melhor horário antes de finalizar.

Quando o lead pedir agendamento, retorne JSON estruturado:
{ "action": "agendar", "nome": "...", "telefone": "...",
  "procedimento": "...", "preferencia_horario": "..." }

Quando o lead pedir humano, retorne:
{ "action": "transferir", "motivo": "..." }

Passo 4 — Envie a resposta de volta pelo WhatsApp

Nó HTTP Request no n8n, configurado para a Evolution API:

POST https://evolution.suaempresa.com/message/sendText/INSTANCE_NAME

Headers:
  apikey: SUA_EVOLUTION_API_KEY
  Content-Type: application/json

Body:
{
  "number": "{{$json.telefone}}",
  "text": "{{$json.resposta_ia}}"
}

A Evolution envia a mensagem para o cliente e, por causa do webhook duplo configurado no Passo 1, o YaClin também recebe a confirmação — a mensagem enviada pela IA aparece automaticamente no chat do YaClin com o lead correspondente.

Passo 5 — Memória de conversa

A IA precisa lembrar do que já foi conversado. Opções:

• n8n Data Tables — armazena histórico por número de telefone, simples e nativo do n8n
• Redis — performance máxima, ideal para alto volume
• Postgres / Supabase — quando quiser fazer análise posterior do histórico
• Buscar via API do YaClin — GET /api/v1/conversations?channel=WHATSAPP retorna a conversa, mas só metadados (não as mensagens completas). Esta opção é mais lenta — prefira armazenar localmente no n8n.

Padrão B — Reagir a eventos do YaClin

Cenário: quando um lead novo é criado no YaClin (por qualquer fonte), você quer que a IA do n8n:

1. Avalie a qualidade do lead (score)
2. Enriqueça com dados externos (busca em redes sociais, validação de telefone, etc.)
3. Crie tarefa no Asana/ClickUp
4. Mande mensagem de boas-vindas personalizada pelo WhatsApp via Evolution

Setup

1. No YaClin: acesse Dashboard > API e Webhooks > Adicionar Webhook de Saída
2. URL: cole a URL do webhook do n8n (gere no n8n criando um nó Webhook)
3. Eventos: selecione lead.created (e outros conforme necessidade)
4. Salve e copie o secret (formato whsec_...)
5. No n8n: no primeiro nó após o Webhook, valide a assinatura HMAC SHA-256 usando o secret (ver código de exemplo na seção anterior)
6. Continue o fluxo com a IA processando o payload

Padrão C — Enviar leads externos para o YaClin

Cenário mais simples e mais comum: você tem um formulário, uma planilha sendo monitorada, um Typeform, ou um e-mail que chega — e quer que tudo isso vire lead no YaClin com qualificação prévia da IA.

Fluxo no n8n

[Trigger: Form / Sheets / Gmail / Typeform]
   ↓
[AI Agent: qualificar o lead]
   ↓ (extrai nome, intenção, urgência, ticket potencial)
[HTTP Request]
   POST https://app.yaclin.com/api/webhooks/lead
   Header: X-API-Key: SUA_API_KEY
   Body: {
     "name": "{{$json.nome}}",
     "phone": "{{$json.telefone}}",
     "email": "{{$json.email}}",
     "source": "{{$json.origem}}",
     "value": {{$json.ticket_estimado}},
     "tags": {{$json.tags_da_ia}},
     "metadata": {
       "score_ia": {{$json.score}},
       "intencao": "{{$json.intencao}}",
       "urgencia": "{{$json.urgencia}}"
     }
   }

Boas práticas para o agente IA no WhatsApp

• Limite o escopo da IA — defina claramente no system prompt o que ela pode e não pode fazer. IA solta vende coisa errada, promete preço errado, marca horário inexistente.
• Sempre tenha um "fallback humano" — quando o lead pedir falar com pessoa, transfira imediatamente. No YaClin, isso é feito pela função "Transferir conversa".
• Não responda fora do horário comercial sem avisar — configure o n8n para identificar fora de hora e mandar mensagem de "voltamos amanhã às 8h, sua mensagem já está registrada".
• Filtre mensagens da própria empresa — o webhook da Evolution traz mensagens enviadas pelo número (fromMe: true). Se você não filtrar, a IA vai tentar responder mensagens da própria recepcionista humana, criando loop.
• Anti-loop: nunca faça a IA responder mensagens de outros bots. Adicione uma whitelist de números humanos no n8n.
• Logs detalhados — guarde no n8n cada decisão da IA (input, output, score) para auditoria e para retreinar o prompt.
• Custo da IA — Claude Haiku 4.5 ou GPT-4o-mini são suficientes para 90% dos casos e custam centavos por conversa. Reserve modelos maiores (Claude Sonnet/Opus, GPT-4o) para qualificação complexa ou casos sensíveis.
• Teste com seu próprio número antes de liberar para clientes reais. Sempre.

Resolução de problemas comuns