Documentação

Visão geral

O Comflow conecta números de WhatsApp comuns ou Business por QR Code e entrega uma API REST por instância. Você fala sempre com o gateway https://comflow.com.br/api/v1: ele autentica pelo token, aplica os limites do plano, protege o número quando você quiser e registra tudo no painel. Cada instância é um número; uma conta pode ter várias.

1. Crie sua conta

Use o botão Teste grátis no site: sem cartão, com 2 dias para testar. Ou contrate direto um plano: a conta e a primeira instância são criadas na hora e a instância é liberada com a confirmação do pagamento. Veio por um link de parceiro (?ref=codigo)? Os benefícios dele (dias grátis, desconto, Proteção do número inclusa) aparecem no cadastro e são aplicados automaticamente.

2. Conecte o número

No painel, abra a instância. Na primeira conexão a página mostra o QR e renova sozinha: no celular vá em WhatsApp › Aparelhos conectados › Conectar aparelho e leia o código. A página detecta a conexão e mostra o número.

• Trocar de número: clique em Desconectar e leia o QR com o outro aparelho. Nome, token, webhook, histórico e faturas continuam os mesmos; só o número muda, e a "idade do número" recomeça para a saúde e a proteção.
• QR recusado ("não foi possível conectar"): use Trocar número / sessão limpa: a sessão antiga é apagada na engine e um QR limpo é gerado, sem mexer em nada no painel.
• Um mesmo número não pode estar conectado a duas instâncias.

3. Pegue a URL, o token e o nome

Na instância, o card Acesso à API mostra a URL base do gateway, o token (header apikey) e o nome da instância. Clique em qualquer um para copiar. O token identifica a instância, então o nome não vai no caminho das chamadas.

4. Envie a primeira mensagem

curl -X POST "https://comflow.com.br/api/v1/message/sendText" \
  -H "apikey: SEU_TOKEN" -H "Content-Type: application/json" \
  -d '{"number": "5511999999999", "text": "Olá! Mensagem enviada pelo Comflow."}'

Números sempre com DDI e DDD, só dígitos. A resposta traz key.id (id da mensagem no WhatsApp) e os headers X-Plan-Used e X-Plan-Limit com o consumo do mês. Mídia, áudio, documento, localização, enquetes, grupos e etiquetas seguem os mesmos caminhos da Evolution API, listados na Referência da API.

5. Receba mensagens e eventos (webhook)

Informe a URL do seu sistema no card Webhook do cliente da instância. Você recebe um POST em JSON para cada evento: mensagem recebida, mensagem enviada, mudança de conexão e QR atualizado. Responda 200 rápido e processe depois. O gateway reenvia o evento original da engine, com o nome da instância em instance.

6. Proteção do número (recomendado)

Ative no card Proteção do número da instância. Com ela, os envios pelo gateway seguem ritmo humano (intervalo aleatório entre mensagens, pausa a cada lote), respeitam uma janela de horário e um teto diário que cresce com a idade do número: novo, estabilizando, maduro. O que cabe nas regras sai na hora (200). O que passa entra em fila e a API responde 202 com id, scheduled_at e position; consulte em GET /messages/{id} ou cancele com DELETE. Mensagens urgentes (código, resposta que alguém espera) vão com "priority": "high" e saem na hora, dentro de uma cota por hora.

Horários que valem para todos: a janela de envio vai das 8h às 21h. Envio normal fora dela espera o início da próxima janela. Das 22h às 7h é o horário de silêncio: nada normal sai e a saúde do número penaliza quem envia nessa faixa. Prioridade alta sai a qualquer hora, com cota menor no silêncio (10 por hora).

Fila acumulada: se o que está esperando não cabe em um dia de janela, o painel avisa e o seu webhook recebe queue.backlog uma vez por dia. Nessa hora o certo é reduzir o volume ou dividir em mais números, não forçar o envio.

Na sua integração: trate 202 como sucesso e guarde o id. Só isso muda.

7. Saúde do número

Cada instância tem uma nota de 0 a 100 no painel, calculada por quedas de conexão, rajadas por minuto, envios no horário de silêncio (22h–7h), proporção de respostas, crescimento brusco de volume e idade do número. O card mostra os sinais, o mapa de calor das últimas 24 h e o volume diário sugerido. Dicas: aqueça números novos, mantenha ritmo, envie em horário comercial, personalize (spintax) e prefira conversas a disparos.

8. Limites do plano

Cada plano tem um limite mensal de envios (recebidas não contam). Você recebe avisos em 75%, 85% e 95% e, ao chegar a 100%, os envios pausam até o próximo ciclo ou até um upgrade em Meu plano. O gateway responde 429 plan_limit_reached nesse estado. Há também um limite de requisições por minuto (429 rate_limited, com retry_after).

9. Cobrança, adicionais e cancelamento

Faturas mensais por instância no dia do vencimento, com pagamento por Pix, boleto ou cartão quando disponível; a liberação após o pagamento é automática. Serviços adicionais (como a Proteção do número, quando vendida à parte) entram na fatura seguinte à contratação. Cancelamento pelo painel: a instância segue ativa até o fim do período pago, sem nova fatura e sem reembolso.

10. Parceiros e revenda

Agências, softwares e integradores podem revender o Comflow. O parceiro recebe um link de indicação com dias grátis, desconto e adicional gratuito para os clientes dele, um painel com todas as instâncias sob o seu guarda-chuva e, se quiser, uma API de parceiro para criar contas direto do próprio sistema, com fatura consolidada mensal. Veja a seção "API de parceiro" na referência e peça sua parceria pelo site.

11. Exemplos

// PHP
$ch = curl_init("https://comflow.com.br/api/v1/message/sendText");
curl_setopt_array($ch, [CURLOPT_RETURNTRANSFER => true, CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => ['apikey: SEU_TOKEN', 'Content-Type: application/json'],
  CURLOPT_POSTFIELDS => json_encode(['number' => '5511999999999', 'text' => 'Olá'])]);
$res = json_decode(curl_exec($ch), true); $http = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($http === 202) { /* enfileirado pela proteção: guarde $res['id'] */ }
if ($http === 429) { /* limite: veja $res['message'] e $res['retry_after'] */ }

// Node.js
const r = await fetch("https://comflow.com.br/api/v1/message/sendText", { method: "POST",
  headers: { apikey: "SEU_TOKEN", "Content-Type": "application/json" },
  body: JSON.stringify({ number: "5511999999999", text: "Olá" }) });
const j = await r.json();
if (r.status === 202) console.log("na fila:", j.id, j.scheduled_at);