Crialy Connect API

Introdução

O Crialy Connect é uma API RESTful completa para envio e recebimento de mensagens via WhatsApp Web. A API permite gerenciar sessões WhatsApp, enviar e receber mensagens, e gerenciar grupos programaticamente.

https://api.crialyconnect.com/functions/v1/api

Autenticação

Toda requisição à API deve incluir o header X-API-Key com a chave de API do seu projeto.

Você encontra sua API Key no Dashboard Projeto API Key.

Exemplo

curl -X GET "https://api.crialyconnect.com/functions/v1/api/{project_id}/listPhones" \
  -H "X-API-Key: YOUR_API_KEY"

Endpoints — Projeto

Endpoints — Sessão

Números brasileiros — o problema do 9º dígito

Antes da primeira campanha em produção, leia esta seção. Evita perda de mensagens e — pior — entrega para a pessoa errada.

Contexto

Entre 2012 e 2016 a ANATEL adicionou um "9" ao início de todo celular brasileiro. O WhatsApp grava o JID interno do contato com o formato que ele tinha quando se registrou:

• Registrado pré-migração e nunca re-registrou → 551187654321@c.us (SEM o 9, 8 dígitos depois do DDD)
• Registrado pós-migração ou trocou de chip → 5511987654321@c.us (COM o 9, 9 dígitos depois do DDD)

Mandar pro JID errado resulta em:

• erro "número não está no WhatsApp" (caso comum, fácil de detectar), OU
• mensagem entregue pra outra pessoa caso aquele JID alternativo exista pra outro usuário — risco real de vazamento de informação

Não é uma regra por DDD ou região — é determinística por usuário, e só o WhatsApp sabe a resposta. Por isso a única solução confiável é perguntar via checkPhones.

Workflow recomendado

Passo 1 — na importação de contatos (uma vez por contato):

curl -X POST "https://api.crialyconnect.com/functions/v1/api/{pid}/{sid}/checkPhones" \
  -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"numbers": ["5511987654321", "5521988887777"]}'

Resposta:

{
  "success": true,
  "data": [
    {"number": "5511987654321","exists": true,"jid": "551187654321@c.us"},
    {"number": "5521988887777","exists": true,"jid": "5521988887777@c.us"},
    {"number": "5511000000000","exists": false,"jid": null}
  ]
}

Salve o jid no seu banco, associado ao contato. Note como o primeiro número entrou com 9 mas o JID veio sem (usuário legado), enquanto o segundo manteve o 9 (usuário moderno) — exatamente o tipo de diferença que precisa ser respeitada.

Passo 2 — em todas as mensagens, use o jid:

curl -X POST "https://api.crialyconnect.com/functions/v1/api/{pid}/{sid}/sendMessage" \
  -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"to": "551187654321@c.us", "type": "text", "message": "Olá!"}'

Throughput & manutenção

• checkPhones aceita até 50 números por chamada — bom pra normalizar planilhas em batches.
• Re-validar quando: sendMessage começar a falhar consistentemente pra um contato (provável troca de chip / re-registro do WhatsApp). Rode checkPhones de novo pra esse número e atualize o jid salvo.

FAQ

Endpoints — Grupos

Endpoints — Contatos & Conversas

Novos Endpoints — v1.0

Endpoints adicionados na versão 1.0. Inclui bloqueio de contatos, limpeza de conversas, labels e os endpoints não suportados pelo engine atual (retornam 501).

Implementados

Planejados (retornam 501)

Tipos de Mensagem Avançados

Todos via POST /{project_id}/{session_id}/sendMessage com o type correspondente.

{
  "to": "5541999999999",
  "type": "reaction",
  "message": "BAE5F2A4C988B231",
  "text": "😍"
}

{
  "to": "5541999999999",
  "type": "poll",
  "message": "Qual o melhor horário?",
  "poll_options": ["Manhã", "Tarde", "Noite"],
  "poll_multi_select": false
}

{
  "to": "5541999999999",
  "type": "delete",
  "message": "BAE5F2A4C988B231"
}

{
  "to": "5541999999999",
  "type": "edit",
  "message": "BAE5F2A4C988B231",
  "text": "Texto corrigido"
}

{
  "to": "5541999999999",
  "type": "location",
  "message": {
    "latitude": -23.5505,
    "longitude": -46.6333,
    "name": "Av. Paulista",
    "address": "Av. Paulista, 1000 — São Paulo, SP"
  }
}

{
  "to": "5541999999999",
  "type": "contact",
  "message": "5511988887777"
}

{
  "to": "5541999999999",
  "type": "forward",
  "forward_from": "true_5511999998888@c.us_3EB0A1B2C3D4E5F6"
}

Webhooks

O Crialy Connect envia 3 tipos de webhook para o webhook_url configurado no projeto. O campo type na raiz identifica o tipo:

• type: "message" — mensagem recebida (texto, mídia, reaction, poll, edit, revoke)
• type: "ack" — delivery receipt (sent, delivered, read)
• type: "status" — evento de sessão (connected, disconnected)

Os payloads incluem campos em camelCase (productId, phoneId) e seus aliases em snake_case (product_id, phone_id), além dos campos event e session_id para uso interno.

{
  "type": "message",
  "productId": "c96c07a0-7c5c-4470-9c92-b3eb2a81a36c",
  "product_id": "c96c07a0-7c5c-4470-9c92-b3eb2a81a36c",
  "phoneId": "4455ac83-6429-4b8e-bdbe-d269fd32c271",
  "phone_id": "4455ac83-6429-4b8e-bdbe-d269fd32c271",
  "receiver": "554191499739@c.us",
  "conversation": "5511999998888@c.us",
  "user": { "id": "5511999998888@c.us", "name": "João Silva", "phone": "5511999998888" },
  "reply": "https://api.crialyconnect.com/functions/v1/api/{project_id}/{session_id}/sendMessage",
  "timestamp": 1712764800,
  "event": "message.received",
  "session_id": "4455ac83-6429-4b8e-bdbe-d269fd32c271",
  "message": {
    "id": "3EB0A1B2C3D4E5F6",
    "_serialized": "false_5511999998888@c.us_3EB0A1B2C3D4E5F6",
    "type": "text",
    "text": "Olá, quero agendar uma consulta",
    "content": "Olá, quero agendar uma consulta",
    "chatId": "5511999998888@c.us",
    "fromMe": false,
    "mediaUrl": null,
    "from": "5511999998888@c.us",
    "to": "554191499739@c.us",
    "timestamp": 1712764800,
    "metadata": { "message_id": "3EB0A1B2C3D4E5F6" }
  }
}

{
  "type": "ack",
  "productId": "c96c07a0-7c5c-4470-9c92-b3eb2a81a36c",
  "phoneId": "4455ac83-6429-4b8e-bdbe-d269fd32c271",
  "ack": {
    "id": "3EB0A1B2C3D4E5F8",
    "chatId": "5511999998888@c.us",
    "ack": 2
  },
  "event": "message.delivered",
  "session_id": "4455ac83-6429-4b8e-bdbe-d269fd32c271"
}

{
  "type": "status",
  "productId": "c96c07a0-7c5c-4470-9c92-b3eb2a81a36c",
  "phoneId": "4455ac83-6429-4b8e-bdbe-d269fd32c271",
  "content": {
    "status": "connected",
    "phone": "554191499739"
  },
  "event": "session.connected",
  "session_id": "4455ac83-6429-4b8e-bdbe-d269fd32c271"
}

Mapeamento event → type

Política de Retry

Em caso de falha na entrega, o Crialy Connect realiza até 5 tentativas com backoff exponencial:

• 1ª tentativa: 1 segundo
• 2ª tentativa: 5 segundos
• 3ª tentativa: 30 segundos
• 4ª tentativa: 2 minutos
• 5ª tentativa: 10 minutos

Garantia de Identificação

O Crialy Connect v2 nunca expõe LID bruto em campos de identificação de usuário. Quando um LID não pode ser resolvido para o número de telefone canônico, o sistema sinaliza explicitamente:

• metadata.lidUnresolved = true no webhook de mensagem recebida quando o remetente não pode ser resolvido
• lid_unresolved = true por participante em /getGroups/{group_id} quando o id do participante está em formato LID

Limitações Conhecidas

Códigos de Erro

Formato de Erro

{
  "success": false,
  "message": "Descrição do erro"
}

Erro 503 — Sessão em Recuperação

O endpoint POST /sendMessage retorna 503 Service Unavailable quando a sessão está temporariamente indisponível por estar recuperando de uma falha do subsistema Chromium. Essa é a única exception do /sendMessage — todos os outros erros retornam 422.

Response headers:

HTTP/1.1 503 Service Unavailable
Retry-After: 15
Content-Type: application/json

Response body:

{
  "error": "Session is recovering from Chromium subsystem failure",
  "retry_after_seconds": 15
}

Guia de Integração

Passo a passo para conectar um número WhatsApp via API e começar a enviar/receber mensagens.

POST /functions/v1/api/{project_id}/addPhone
Body: { "name": "WhatsApp do Cliente" }
→ Retorna session_id

POST /functions/v1/api/{project_id}/{session_id}/connect
→ Worker começa a gerar QR Code

GET /functions/v1/api/{project_id}/{session_id}/qrCode
→ Retorna { "data": { "qr_code": "data:image/png;base64,..." } }

GET /functions/v1/api/{project_id}/{session_id}/status
→ Quando retornar "connected", parar polling e exibir sucesso

Recebendo Mensagens

Configure o webhook do projeto para receber mensagens automaticamente:

POST /functions/v1/api/{project_id}/setWebhook
Body: { "webhook_url": "https://seu-site.com/webhook" }

// Toda mensagem recebida será enviada como POST para sua URL
// com o payload documentado na seção de Webhooks.