Documentacao da API WhatsApp ConnectyHub
Use a ConnectyHub como ponte de WhatsApp para suas empresas, com chaves proprias, instancias controladas, envio de mensagens, webhooks assinados e catalogo completo de recursos avancados.
const baseUrl = "https://www.connectyhub.com.br/api/v1";
const apiKey = process.env.CONNECTYHUB_API_KEY;Referencia completa
Tudo organizado por recurso
A documentacao agora combina as rotas nativas da ConnectyHub com o catalogo avancado permitido. O cliente usa a nossa chave, o nosso endpoint e o instanceId publico; a ConnectyHub faz a ponte e registra a auditoria.
Chave ConnectyHub
O cliente nunca usa credencial interna de instancia. Toda chamada entra por Authorization ou x-connectyhub-api-key.
Instancia controlada
O instanceId publico define qual WhatsApp sera usado, respeitando empresa, scopes e status no painel admin.
Eventos assinados
Webhooks entregues ao cliente recebem headers ConnectyHub e assinatura HMAC quando houver secret.
QR lido, mas WhatsApp pediu chave de acesso
Algumas contas exigem uma verificacao extra por passkey depois da leitura do QR inicial. Isso nao e erro de token, webhook ou renderizacao do QR. O integrador deve detectar esse estado e mostrar uma mensagem amigavel no proprio painel.
const attempt = response.connectionDiagnostics?.latestAttempt;
const passkeyBlocked =
attempt?.finalStatus === "passkey_blocked" ||
response.lastDisconnectReason
?.toLowerCase()
.includes("passkey pairing not supported");{
"lastDisconnectReason": "Passkey pairing not supported",
"connectionDiagnostics": {
"latestAttempt": {
"finalStatus": "passkey_blocked",
"scanDetected": true
}
}
}Mensagem recomendada: Esta conta pediu uma verificacao extra por chave de acesso. Esse tipo de verificacao ainda nao pode ser concluido diretamente pelo QR Code do painel.
Primeiros passos
Listar instancias
Confirme quais instancias pertencem ao cliente autenticado.
curl "https://www.connectyhub.com.br/api/v1/instances" \
-H "Authorization: Bearer ch_live_SEU_TOKEN"{
"ok": true,
"instances": [
{
"id": "ea36f5db-c8dd-48ca-9e28-73ca3f015d78",
"provider": "connectyhub",
"phoneNumber": "5511915834033",
"displayName": "Atendimento",
"profileImageUrl": "https://pps.whatsapp.net/...",
"status": "connected"
}
]
}Enviar mensagem
Use o id publico da instancia para enviar texto com controle de idempotencia.
curl "https://www.connectyhub.com.br/api/v1/messages/text" \
-X POST \
-H "Authorization: Bearer ch_live_SEU_TOKEN" \
-H "Idempotency-Key: pedido-123" \
-H "Content-Type: application/json" \
-d '{
"instanceId": "ea36f5db-c8dd-48ca-9e28-73ca3f015d78",
"number": "5511999999999",
"text": "Ola! Mensagem enviada pela ConnectyHub API."
}'{
"ok": true,
"messageId": "msg_...",
"status": "sent",
"provider": "connectyhub"
}Usar recurso avancado
Para rotas avancadas, coloque o corpo real dentro de payload.
curl "https://www.connectyhub.com.br/api/v1/provider/chat/details" \
-X POST \
-H "Authorization: Bearer ch_live_SEU_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"instanceId": "ea36f5db-c8dd-48ca-9e28-73ca3f015d78",
"payload": {
"number": "5511999999999",
"preview": true
}
}'{
"id": "5511999999999@s.whatsapp.net",
"name": "Cliente",
"profileImageUrl": "https://pps.whatsapp.net/..."
}Detectar passkey no pareamento
Quando o WhatsApp ler o QR inicial mas exigir chave de acesso, o painel do integrador deve detectar passkey_blocked e orientar o usuario sem tratar como erro de QR ou webhook.
curl "https://www.connectyhub.com.br/api/v1/instances/ea36f5db-c8dd-48ca-9e28-73ca3f015d78/status" \
-H "Authorization: Bearer ch_live_SEU_TOKEN"{
"ok": true,
"instance": {
"id": "ea36f5db-c8dd-48ca-9e28-73ca3f015d78",
"status": "disconnected",
"lastDisconnectReason": "Passkey pairing not supported",
"connectionDiagnostics": {
"latestAttempt": {
"finalStatus": "passkey_blocked",
"scanDetected": true
}
}
}
}