Quickstart

0. Configure e valide seu webhook

Antes de cadastrar o primeiro cliente ou criar instâncias, siga a Configuração inicial do webhook. No Portal, abra Endpoints → Cadastrar e validar webhook (ou Configurar / revalidar webhook), copie o Meta Verify Token para o backend do seu sistema, publique o GET/POST no mesmo caminho e use Testar GET → Validar e salvar.

Se usar a API, validate-partner-webhook-endpoint apenas testa; update-partner-webhook-endpoint salva. Confira o destino com get-partner-webhook-endpoint. Há um endpoint global por parceiro, compartilhado pelos clientes.

1. Configure as variáveis

Os exemplos usam a API de produção. Para testes isolados, escolha o ambiente de homologação e suas credenciais próprias.

HOOKCLOUD_API_URL=https://api.hookcloud.app/functions/v1/swift-worker
HOOKCLOUD_PUBLISHABLE_KEY=SUA_PUBLISHABLE_KEY
HOOKCLOUD_PARTNER_API_KEY=hc_partner_live_SUA_CHAVE
PARTNER_WEBHOOK_URL=https://api.seusistema.com/webhooks/whatsapp
META_GRAPH_VERSION=v26.0

2. Crie ou atualize o cliente

curl --request POST 'https://api.hookcloud.app/functions/v1/swift-worker' \
  --header 'apikey: SUA_PUBLISHABLE_KEY' \
  --header 'Authorization: Bearer hc_partner_live_SUA_CHAVE' \
  --header 'Content-Type: application/json' \
  --data '{
    "route": "upsert-partner-customer",
    "external_customer_id": "cliente_56790",
    "customer_name": "Clínica Mais Vida",
    "customer_email": "contato@maisvida.com",
    "customer_phone": "5511999999999"
  }'

3. Crie a instância e gere o Connect Flow

curl --request POST 'https://api.hookcloud.app/functions/v1/swift-worker' \
  --header 'apikey: SUA_PUBLISHABLE_KEY' \
  --header 'Authorization: Bearer hc_partner_live_SUA_CHAVE' \
  --header 'Content-Type: application/json' \
  --data '{
    "route": "create-customer-instance",
    "external_customer_id": "cliente_56790",
    "instance_name": "Atendimento principal",
    "create_connect_session": true,
    "return_url": "https://app.seusistema.com/integracoes/whatsapp",
    "cancel_url": "https://app.seusistema.com/integracoes/whatsapp",
    "success_url": "https://partner-connect.hookcloud.app/connect/success",
    "error_url": "https://partner-connect.hookcloud.app/connect/error"
  }'

{
  "ok": true,
  "instance_id": "UUID_DA_INSTANCIA",
  "connect_session_id": "UUID_DA_SESSAO",
  "connect_url": "https://partner-connect.hookcloud.app/connect?token=..."
}

4. Abra o Connect Flow

Abra connect_url em popup ou nova aba. O cliente final conclui o Embedded Signup da Meta; a HookCloud salva WABA, Phone Number ID, nome verificado, qualidade, token criptografado e callback remoto.

const popup = window.open(connectUrl, 'hookcloudConnect', 'popup,width=860,height=760');
window.addEventListener('message', (event) => {
  if (event.origin !== 'https://partner-connect.hookcloud.app') return;
  if (event.data?.type === 'hookcloud_connect_close') popup?.close();
});

Referência Meta: Embedded Signup oficial↗

5. Consulte o status

curl --request GET \
  --url 'https://api.hookcloud.app/functions/v1/swift-worker?route=get-partner-instance&instance_id=UUID_DA_INSTANCIA' \
  --header 'apikey: SUA_PUBLISHABLE_KEY' \
  --header 'Authorization: Bearer hc_partner_live_SUA_CHAVE'

6. Receba e processe os eventos POST

O GET já validado prepara a URL; agora confirme o recebimento de um evento real no mesmo caminho via POST. Verifique a autenticidade pelo mecanismo adequado à origem, persista ou enfileire o evento antes de responder 2xx e deduplique as repetições.

Percorra todos os itens de entry[], changes[], mensagens e status presentes. O metadata.phone_number_id identifica o número comercial; eventos de WABA podem não possuir esse campo. BSUID identifica o destinatário, não a instância conectada.

Preparação do receptor POST e distinção dos segredos · Contratos, assinaturas e exemplos dos eventos · Reportar Saúde de Entregas

7. Responda pela Graph API

curl --request POST 'https://graph.facebook.com/v26.0/PHONE_NUMBER_ID/messages' \
  --header 'Authorization: Bearer META_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "messaging_product": "whatsapp",
    "recipient": "BR.BSUID_RECEBIDO_NO_WEBHOOK",
    "type": "text",
    "text": { "body": "Olá! Como podemos ajudar?" }
  }'

Referência Meta: Mensagens da Cloud API↗

Checklist de conclusão

• Endpoint global validado e salvo; não apenas testado
• POST preparado e evento persistido antes do 2xx
• Cliente salvo com ID externo estável
• Instância salva com UUID e instance_key
• Connect Flow concluído
• status=connected
• remote_callback_status=active
• Webhook recebe mensagens
• Backend envia resposta pela Graph API

Primeiro teste: conexão em três chamadas do seu backend

Pré-requisito: endpoint global configurado, validado e salvo.

1. Cadastre o cliente com upsert-partner-customer e um external_customer_id estável.
2. Use create-customer-instance, guarde instance_id e a instance_key gerada pela HookCloud, e abra o connect_url no navegador do cliente.
3. Após a autorização, consulte get-partner-instance. Leia a saúde, os dados Meta, a data de sincronização e o risco do cliente. Depois atualize seu cache pelos eventos.

As rotas da própria página Connect são referência opcional: a página já executa essas etapas. health é apenas monitoramento técnico opcional da API e não prova que o número está pronto para enviar.

Catálogo completo: finalidade, campos, exemplos e referências Meta de cada endpoint.