Conectar os números dos seus clientes

8 min de leituraAtualizado em 29 out. 2026

Se você tem um software (um sistema de agendamento, um CRM, um ERP) e quer que os seus clientes conectem os números de WhatsApp deles, use o modo Integrar e oferecer aos meus clientes. A Atalia entrega uma página com a sua marca onde cada cliente conecta os próprios canais, sem você precisar falar com a Meta nem pedir senha a ninguém.

Tudo continua chegando no seu sistema: as mensagens dos clientes dos seus clientes chegam no seu webhook, e você envia pela sua chave de API.

Está montando o sistema com uma IA?

Este fluxo também está descrito no llms.txt, na seção "Revenda". Peça para a IA gerar o link de cada cliente por POST /api/v1/clients, tratar os eventos client.connected e client.no_slot e guardar o client_id de cada cliente. Veja Integrar usando uma IA.

Como funciona

1. Você configura a Página de conexão com a sua marca.
2. O seu cliente abre o link da página (geral, de convite ou gerado pela API), informa os dados da empresa, aceita os termos e conecta os canais.
3. Cada cliente vira uma conta separada na Atalia, ligada à sua. Os canais dele ocupam vagas do seu pacote, e quem paga é você.
4. O seu sistema recebe o evento client.connected e passa a receber as mensagens daquele cliente, identificadas pelo client_id. Se você cadastrou um endereço de retorno, o navegador do cliente volta para o seu sistema.

O cliente não ganha acesso ao painel da Atalia: quem atende, pelo seu sistema, é você.

1. Ative o modo e configure a página

1. Em Configurações › Conta, clique em Alterar e escolha Integrar e oferecer aos meus clientes. O menu ganha Clientes e Página de conexão.
2. Em Página de conexão, preencha:
   • Sua marca: logo (PNG, JPG ou WebP, até 1 MB), nome e cor. É o que o cliente vê no topo da página e nos botões.
   • Canais que o cliente pode conectar: o WhatsApp está sempre disponível; Instagram e Messenger são opcionais.
   • Link para enviar: o endereço da sua página. Use o nome do seu produto, sem espaço nem acento.
   • Seus termos de uso (opcional): com o link, o cliente aceita os seus termos junto com os da Atalia.
   • Voltar para o seu sistema (opcional): o endereço para onde o cliente volta ao concluir. Veja Voltar para o seu sistema.
3. Clique em Salvar. A prévia do lado direito mostra cada etapa que o cliente vai ver.

2. Leve o cliente até a página

Há três jeitos:

Jeito	Quando usar	Como
Link geral	Você quer pôr o link no seu sistema, num e-mail ou no onboarding do seu produto	Copie em Página de conexão › Link para enviar. Cada cliente preenche os próprios dados. Acrescente ?ref=<id do usuário no seu sistema> para saber quem conectou.
Convite pelo painel	Você já sabe quem é o cliente	Em Clientes, clique em Convidar cliente e informe nome e e-mail. O cliente recebe um e-mail com a sua marca e o link já com os dados preenchidos.
Convite pela API	O seu sistema gera o link na hora, para cada usuário	POST /api/v1/clients com a sua chave (veja abaixo). A resposta traz o connect_url para você abrir ou enviar.

O link de convite vale por 7 dias. Pelo menu ⋯ do cliente (ou por POST /api/v1/clients/{id}/invite) dá para gerar um link novo; o anterior deixa de valer.

Pela API

curl -X POST https://chat.atalia.com.br/api/v1/clients \
  -H "x-api-key: $ATALIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Clínica Bem-Estar","email":"contato@clinicabemestar.com.br","tax_id":"11222333000181","ref":"usuario-8812"}'

{ "data": {
  "client": { "id": "c21a7f0e-2b4d-4e8a-9f1c-0d2e3f4a5b6c", "name": "Clínica Bem-Estar", "email": "contato@clinicabemestar.com.br",
              "tax_id": "11222333000181", "ref": "usuario-8812", "status": "invited", "channels": [], "created_at": "2026-10-29 10:00:00" },
  "connect_url": "https://conectar.atalia.ai/medagenda?i=3f9c...",
  "email_sent": false } }

• tax_id e ref são opcionais. ref aceita até 200 caracteres: letras, números e . _ : @ -.
• "send_email": true também manda o convite por e-mail, com a sua marca.
• GET /api/v1/clients lista os seus clientes, com a situação e os canais de cada um.
• Só funciona no modo Integrar e oferecer aos meus clientes, com a Página de conexão salva.

3. O que o cliente vê

1. Sobre a sua empresa: nome, CNPJ e e-mail, e o aceite dos termos da Atalia e dos seus, se você cadastrou. Os termos vêm antes de qualquer conexão, e o aceite fica registrado.
2. Uma etapa por canal liberado. A página mostra a sua marca, a Atalia (parceira da Meta) e o canal, e o cliente entra com a conta do Facebook. No WhatsApp ele escolhe entre Número novo e Coexistência, que é o número que já está no app do WhatsApp Business: o número continua funcionando no celular e as mensagens também passam pela integração. Dá para pular um canal e conectar depois.
3. Concluir: a página mostra os canais conectados. Com endereço de retorno, o cliente volta para o seu sistema; sem ele, pode fechar a página.

A página tem o rodapé "Conexão segura por atalia".

4. Acompanhe em Clientes

Situação	O que quer dizer
Convite enviado	O cliente ainda não preencheu a página.
Em andamento	Preencheu os dados e aceitou os termos, mas ainda não conectou nenhum canal.
Conectado	Conectou pelo menos um canal.
Sem vaga no pacote	Tentou conectar e o seu pacote estava cheio.

Sem vaga no pacote

Quando todas as vagas do seu pacote estão em uso, o cliente vê uma mensagem pedindo para falar com você, e o seu sistema recebe o evento client.no_slot. Para liberar, compre um canal avulso ou troque de pacote em Plano e cobrança e mande o link de novo para o cliente.

Conectar mais canais depois

Por segurança, um CNPJ que já tem canais conectados não reabre a conta pelo link geral: senão qualquer pessoa que soubesse o CNPJ entraria na conta do seu cliente. Para o cliente conectar mais um número, use Clientes › ⋯ › Link para conectar mais canais e mande o link para ele.

Voltar para o seu sistema

Com o campo Voltar para o seu sistema preenchido, o navegador do cliente volta para o seu endereço:

• ao concluir, com status=connected;
• ao clicar em Voltar para a sua marca antes de concluir, com status=cancelled;
• quando o seu pacote está cheio, com status=no_slot.

https://seusistema.com/atalia/retorno?status=connected&client_id=c21a7f0e-...&ref=usuario-8812&channels=whatsapp&t=1793206931&sig=5c8f...

Parâmetro	O que é
status	connected, cancelled ou no_slot.
client_id	O cliente na Atalia (o mesmo do client.connected). Pode faltar em cancelled, se a pessoa saiu antes de preencher os dados.
ref	O ref do link ou do convite, se houver.
channels	Os canais conectados, separados por vírgula. Só em connected.
t	Quando o retorno foi gerado (epoch, em segundos).
sig	A assinatura: HMAC-SHA256 de "<t>.<status>.<client_id>.<ref>.<channels>" (campo ausente = vazio) com o mesmo segredo do webhook (whsec_...).

Confira a assinatura antes de confiar nos dados, e recuse t com mais de 5 minutos:

import crypto from 'node:crypto';

function verifyAtaliaReturn(query, secret) {
  const { t = '', status = '', client_id = '', ref = '', channels = '', sig = '' } = query;
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;
  const expected = crypto.createHmac('sha256', secret).update(`${t}.${status}.${client_id}.${ref}.${channels}`).digest('hex');
  return sig.length === expected.length && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(sig));
}

import hashlib, hmac, time

def verify_atalia_return(q: dict, secret: str) -> bool:
    if abs(time.time() - int(q.get("t", 0))) > 300:
        return False
    base = f"{q.get('t','')}.{q.get('status','')}.{q.get('client_id','')}.{q.get('ref','')}.{q.get('channels','')}"
    expected = hmac.new(secret.encode(), base.encode(), hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, q.get("sig", ""))

O retorno é conveniência, o webhook é a fonte

O retorno serve para levar o usuário de volta à tela certa do seu sistema. O dado oficial continua chegando pelo webhook (client.connected), mesmo se a pessoa fechar a página antes de voltar.

O endereço de retorno exige um webhook cadastrado, porque a assinatura usa o segredo dele.

O projeto de exemplo já traz essa rota pronta (/retorno), com a conferência da assinatura e a geração dos links.

5. No seu sistema

Os canais dos seus clientes funcionam como os seus. A diferença é o client_id, que diz de qual cliente é cada canal e cada evento.

Eventos no seu webhook:

Evento	Quando	O que vem em data
client.connected	O cliente conectou o primeiro canal (uma vez por cliente)	client: { id, name, email, tax_id }, channels: ["whatsapp", ...] e ref
client.no_slot	O cliente tentou conectar e o pacote estava cheio	client: { id, name, email, tax_id } e ref
channel.connected	Cada canal conectado (também os dos clientes)	Dados do canal
message.received, message.status, message.echo	Mensagens nos canais do cliente	Iguais aos seus, com o client_id no envelope

Em todo evento de um cliente, o envelope traz client_id (o mesmo client.id). Nos seus próprios canais, client_id é null.

{ "id": "evt_9f2c4b1a7e3d5c6b8a0f1e2d", "type": "client.connected", "created_at": "2026-10-28T17:02:11.000Z",
  "company_id": "c0a8...", "client_id": "7d3e...",
  "channel": null,
  "data": { "client": { "id": "7d3e...", "name": "Clínica Bem Viver", "email": "contato@bemviver.com.br", "tax_id": "11222333000181" },
            "channels": ["whatsapp"], "ref": "usuario-8812" } }

O formato completo de todos os eventos está em Eventos do webhook.

Para enviar em nome de um cliente, use o channel_id do canal dele. GET /api/v1/channels lista os seus canais e os dos seus clientes, cada um com o client_id.

Guarde o client_id

Quando chegar o client.connected, ligue o client.id ao cadastro do cliente no seu sistema. É por ele que você sabe de quem é cada mensagem recebida. Para achar o cadastro, use o ref (se você mandou no link ou no convite), o CNPJ (tax_id, só números) ou o e-mail que o cliente informou na página.

Para desconectar um canal de um cliente (por exemplo, quando ele cancela o seu serviço), use DELETE /api/v1/channels/{id} ou Caixas de Entrada › ⋯ › Desconectar. O número deixa de estar ligado à Atalia na Meta e pode ser conectado em outro lugar.

Cobrança

Cada número de WhatsApp, perfil do Instagram ou página do Messenger conectado por um cliente ocupa uma vaga do seu pacote, igual aos seus canais. Os clientes não recebem fatura da Atalia.