Números (sessões)

Crie e pareie números de WhatsApp pela API com QR Code ou código de pareamento, acompanhe a conexão, reconecte e exclua.

No Zynzap, cada número de WhatsApp conectado é uma sessão (session_id). Ela é usada em quase todas as operações (de onde a mensagem sai, quais conversas a chave vê).

Listar e consultar

curl -X POST "https://api.zynzap.com.br/v1/rpc/ListSessions" \
  -H "Authorization: Bearer $ZYNZAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "request": {
    "pagination": {
      "page": 1,
      "page_size": 50
    }
  }
}'

Campos importantes de cada número (SessionDevice):

Campo	Significado
`session_id`	Identificador do número.
`name`, `phone`	Nome dado no Zynzap e telefone conectado.
`wa_connected`	Conectado agora.
`wa_status`	`SESSION_WA_STATUS_CONNECTED`, `..._DISCONNECTED`, `..._PAIRING_PENDING` ou `..._TEMP_BANNED`.
`ban_retry_after_unix_ms`	Com banimento temporário, quando tentar de novo.

GetSession consulta um número; ListConnectedDevices lista só os conectados. Mudanças chegam como eventos SessionConnected, SessionDisconnected, SessionFailed e SessionCreated.

Criar e parear pela API

A chave precisa de sessions:manage com Permitir criar e parear números (e vaga no plano). POST /sessions/create cria o número e transmite o pareamento por SSE (até 5 minutos):

curl -N -X POST "https://api.zynzap.com.br/v1/sessions/create" \
  -H "Authorization: Bearer $ZYNZAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "request": {
    "name": "Loja Centro",
    "qr": {}
  }
}'

Cada mensagem chega como event: message com um SessionEvent; o campo event diz qual parte veio preenchida:

event: message
data: {"progress":{"stage":"created","session_id":"8c1f7a52-4d1e-4b8a-9a43-2f6f5d0c9e11"},"event":"progress"}

event: message
data: {"qr":{"data":"2@AbCdEf...=="},"event":"qr"}

event: message
data: {"connected":{"phone":"5511912345678","connected_at_unix_ms":"1760280000000"},"event":"connected"}

event: end
data: {}

`event`	O que fazer
`progress`	Etapa do processo. Em `stage: "created"`, guarde o `session_id`.
`qr`	Gere um QR Code com `qr.data` (qualquer biblioteca de QR) e mostre para a pessoa escanear em WhatsApp → Aparelhos conectados. O QR é renovado de tempos em tempos: mostre sempre o último.
`pair_code`	Código de 8 caracteres para digitar em Aparelhos conectados → Conectar com número de telefone. Expira em `expires_in_secs` (~180 s).
`connected`	Pronto: o número está conectado.
`failed`	Falhou (`failed.error`). Tente de novo.

Código de pareamento em vez de QR

Envie pair_code com o telefone (só dígitos, com DDI) no lugar de qr:

curl -N -X POST "https://api.zynzap.com.br/v1/sessions/create" \
  -H "Authorization: Bearer $ZYNZAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "request": {
    "name": "Loja Centro",
    "pair_code": {
      "phone_digits": "5511912345678"
    }
  }
}'

Envie só um de qr ou pair_code. O código de pareamento e o QR dão acesso à conta de WhatsApp: mostre-os só para o dono do número e nunca os registre em logs.

Reconectar

Se o número caiu (SessionDisconnected), POST /sessions/resume tenta reconectar e transmite o progresso no mesmo formato. Se o WhatsApp pedir novo pareamento, chega um novo qr.

curl -N -X POST "https://api.zynzap.com.br/v1/sessions/resume" \
  -H "Authorization: Bearer $ZYNZAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "request": {
    "session_id": "8c1f7a52-4d1e-4b8a-9a43-2f6f5d0c9e11"
  }
}'

Desconectar e excluir

DisconnectSession encerra a conexão e mantém o número (dá para reconectar).
DeleteSession desconecta e remove o número da conta (não pode ser desfeito).

curl -X POST "https://api.zynzap.com.br/v1/rpc/DisconnectSession" \
  -H "Authorization: Bearer $ZYNZAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "request": {
    "session_id": "8c1f7a52-4d1e-4b8a-9a43-2f6f5d0c9e11"
  }
}'

Banimentos

Números novos ou com comportamento de spam podem ser restringidos pelo WhatsApp (SESSION_WA_STATUS_TEMP_BANNED). Aqueça números novos e siga as boas práticas.