Referência da API

Cria uma sessão de conexão para o cliente autentificar seu WhatsApp Business.

Autenticação

Request

Response 201

{
  "connect_session_id": "550e8400-e29b-41d4-a716-446655440000",
  "connect_url": "https://app.vzdapplication.com/connect?session=...",
  "expires_at": "2024-01-15T14:00:00.000Z"
}

Erros

Consulta o status de uma sessão de conexão.

Response 200

{
  "connect_session_id": "550e8400-e29b-41d4-a716-446655440000",
  "client_reference": "seu-id-interno",
  "status": "CONNECTED|FAILED|EXPIRED",
  "failure_reason": null,
  "channel": {
    "channel_id": "ch_xxx",
    "waba_id": "100234567890",
    "phone_number_id": "5511999887766",
    "phone_number": "+55 (11) 99988-7766",
    "display_name": "Beleza ABC",
    "status": "CONNECTED"
  }
}

Revoga uma sessão antes da conclusão. Útil para timeout.

Response

204 (sem conteúdo)

Registra origem de retorno (webhook). Precisa fazer isso antes de conectar qualquer cliente.

Request

Response 201

{
  "id": "org_550e8400-e29b-41d4-a716-446655440000",
  "origin": "https://seu-dominio.com.br",
  "label": "Produção",
  "created_at": "2024-01-15T10:00:00.000Z"
}

Lista origens registradas.

Response 200

{
  "origins": [
    {
      "id": "org_xxx",
      "origin": "https://seu-dominio.com.br",
      "label": "Produção",
      "created_at": "2024-01-15T10:00:00.000Z"
    }
  ]
}

Revoga uma origem de retorno registrada. Deixa de receber webhooks nesse endpoint.

Response

204 (sem conteúdo)

Lista canais WhatsApp conectados da sua conta.

Response 200

{
  "data": [
    {
      "id": "ch_xxx",
      "wabaId": "100234567890",
      "phoneNumberId": "5511999887766",
      "phoneNumber": "+55 (11) 99988-7766",
      "displayName": "Beleza ABC",
      "status": "CONNECTED|DEGRADED|REVOKED",
      "onboardingMode": "COEXISTENCE",
      "webhookSubscribedAt": "2024-01-15T10:00:00.000Z",
      "lastErrorMessage": null,
      "createdAt": "2024-01-15T09:55:00.000Z"
    }
  ]
}

Lista mensagens recebidas e echoes (respostas pelo celular). Até 30 por padrão, ordenadas por recência.

Query Parameters

Response 200

{
  "data": [
    {
      "wamid": "wamid.HhBmRGVmAUH7...",
      "from": "5511987654321",
      "direction": "INBOUND|OUTBOUND",
      "origin": "CLOUD_API|BUSINESS_APP_ECHO",
      "type": "text|image|document|audio|video|location|interactive",
      "text": "Olá! Qual é o horário?",
      "mediaUrl": "https://...",
      "timestamp": "2024-01-15T10:00:00.000Z",
      "sentAt": "2024-01-15T10:00:00.000Z"
    }
  ]
}

Importante: BUSINESS_APP_ECHO = cliente respondeu pelo celular. Certifique-se de filtrar antes de entregar a uma IA, senão ela responderá a si mesma.

Status de entrega das mensagens enviadas (enviada, entregue, lida, falha).

Response 200

{
  "data": [
    {
      "wamid": "wamid.HhBmRGVmAUH7...",
      "status": "SENT|DELIVERED|READ|FAILED",
      "timestamp": "2024-01-15T10:00:05.000Z",
      "occurredAt": "2024-01-15T10:00:05.000Z",
      "failureReason": null
    }
  ]
}

Envia mensagem de texto livre. Só funciona dentro da janela de 24 horas desde a última mensagem do cliente.

Request

Response 202 (async padrão)

{
  "status": "queued",
  "job_id": "job_550e8400-e29b-41d4-a716-446655440000"
}

Response 201 (sync=true, primeira vez)

{
  "status": "sent",
  "wamid": "wamid.HhBmRGVmAUH7AglMkZGVzQ==",
  "message_id": "msg_2024_001",
  "recipient_wa_id": "5511987654321"
}

Erros

Envia mensagem template. Funciona em qualquer momento — templates são pré-aprovados.

Request

Response

Idêntico a /messages/text

Cria novo template na conta do cliente. Fica em revisão na Meta por minutos até horas.

Request

Response 201

{
  "name": "confirmacao_v2",
  "language": "pt_BR",
  "status": "PENDING_REVIEW",
  "id": "123456789",
  "category": "UTILITY"
}

Armadilha: Template apagado bloqueia o nome por 30 dias. Use nome versionado (v1, v2…) desde o início.

Lista templates da conta.

Query Parameters

Response 200

{
  "data": [
    {
      "name": "confirmacao_v2",
      "language": "pt_BR",
      "status": "APPROVED",
      "id": "123456789",
      "category": "UTILITY"
    }
  ],
  "paging": { "next_cursor": "xxx" }
}

Apaga template. Nome fica bloqueado por 30 dias.

Query Parameters

Response 200

{
  "deleted": true,
  "name": "confirmacao_v2",
  "name_reuse_blocked_days": 30
}

Registra URL de webhook. Você recebe POST assinado com cada evento.

Request

Response 200

{
  "webhook_url": "https://seu-dominio.com.br/webhooks/whatsapp",
  "webhook_secret": "sk_whk_abc123..."
}

O segredo aparece uma única vez. Guarde com segurança — não há rota para ler de volta.

Remove webhook. Você volta a depender de polling.

Response

204 (sem conteúdo)