Instâncias

Uma instância representa um número de WhatsApp conectado à WS API. Cada instância tem instanceId, token próprio e estado de conexão independente. Você pode criar quantas precisar — a cobrança é por instância ativa.

Criar instância

terminal

curl -X POST https://api.wsapi.app/v1/instance \
  -H "Authorization: Bearer $ACCOUNT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "atendimento-sp" }'

# resposta
{
  "instanceId": "INST-RMQJHC-7CKZH3",
  "token": "a1b2c3...32hex",
  "name": "atendimento-sp",
  "state": "disconnected"
}

A criação retorna o token em texto claro uma única vez. Guarde de imediato.

Status

Antes de cada envio, idealmente, valide o estado da conexão:

terminal

curl https://api.wsapi.app/v1/instance/status?instanceId=$INSTANCE_ID \
  -H "Authorization: Bearer $TOKEN"

# resposta
{
  "state": "open",      // open | qr | disconnected | connecting
  "since": "2026-05-04T12:31:08Z",
  "phone": "554799****8263"
}

Estados possíveis

open — conectado, pode enviar mensagens.
qr — aguardando escaneamento de QR Code.
connecting — handshake em andamento, aguarde alguns segundos.
disconnected — sessão expirou ou foi removida no celular. Precisa reconectar.

QR Code

terminal

curl https://api.wsapi.app/v1/instance/qrcode?instanceId=$INSTANCE_ID \
  -H "Authorization: Bearer $TOKEN"

# resposta
{
  "state": "qr",
  "base64": "data:image/png;base64,iVBOR..."
}

Use isso para embutir a tela de reconexão na sua aplicação — o cliente final não precisa nunca abrir o painel da WS API. Ele escaneia o QR direto no seu produto.

Listar instâncias

terminal

curl https://api.wsapi.app/v1/instance \
  -H "Authorization: Bearer $ACCOUNT_TOKEN"

Deletar instância

terminal

curl -X DELETE https://api.wsapi.app/v1/instance/$INSTANCE_ID \
  -H "Authorization: Bearer $ACCOUNT_TOKEN"

A deleção é imediata. A sessão é removida do servidor e o WhatsApp do celular se desconecta. Para apenas pausar o uso, basta desconectar — você não é cobrado por instâncias em estado disconnected que não foram conectadas no ciclo.