Sessions

Uma sessão representa uma conexão WhatsApp ativa vinculada a um número de telefone. Você precisa criar uma sessão antes de enviar ou receber mensagens.

Criar sessão

POST /sessions

Cria uma nova sessão. Após criar, use o endpoint de QR ou Phone Pairing para conectar ao WhatsApp.

Parâmetros

Nome	Tipo	Obrigatório	Descrição
name	string	Sim	Identificador único da sessão

Request

cURL

curl -X POST https://api.wi.api.br/sessions \
  -H "x-api-key: $WIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "atendimento-sp"}'

JavaScript

const response = await fetch("https://api.wi.api.br/sessions", {
  method: "POST",
  headers: {
    "x-api-key": process.env.WIAPI_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ name: "atendimento-sp" }),
});

const session = await response.json();

Python

import requests

response = requests.post(
    "https://api.wi.api.br/sessions",
    headers={"x-api-key": WIAPI_KEY},
    json={"name": "atendimento-sp"},
)

session = response.json()

Response

{
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "name": "atendimento-sp",
  "status": "created"
}

Status da sessão

GET /sessions/{id}/status

Retorna o estado atual da conexão e o número vinculado.

Parâmetros

Nome	Tipo	Obrigatório	Descrição
id	string	Sim	ID da sessão (path param)

Request

cURL

curl https://api.wi.api.br/sessions/01234567-89ab-cdef-0123-456789abcdef/status \
  -H "x-api-key: $WIAPI_KEY"

JavaScript

const response = await fetch(
  "https://api.wi.api.br/sessions/01234567-89ab-cdef-0123-456789abcdef/status",
  { headers: { "x-api-key": process.env.WIAPI_KEY } }
);

const status = await response.json();

Python

import requests

response = requests.get(
    "https://api.wi.api.br/sessions/01234567-89ab-cdef-0123-456789abcdef/status",
    headers={"x-api-key": WIAPI_KEY},
)

status = response.json()

Response

{
  "connected": true,
  "phone": "5511987654321",
  "pushName": "Loja SP"
}

QR Code

GET /sessions/{id}/qr

Gera um QR code para parear o WhatsApp. O usuário deve escanear com o app do WhatsApp em até 60 segundos.

Parâmetros

Nome	Tipo	Obrigatório	Descrição
id	string	Sim	ID da sessão (path param)

Request

cURL

curl https://api.wi.api.br/sessions/01234567-89ab-cdef-0123-456789abcdef/qr \
  -H "x-api-key: $WIAPI_KEY"

JavaScript

const response = await fetch(
  "https://api.wi.api.br/sessions/01234567-89ab-cdef-0123-456789abcdef/qr",
  { headers: { "x-api-key": process.env.WIAPI_KEY } }
);

const { qr } = await response.json();
// qr contém a imagem PNG em base64

Python

import requests

response = requests.get(
    "https://api.wi.api.br/sessions/01234567-89ab-cdef-0123-456789abcdef/qr",
    headers={"x-api-key": WIAPI_KEY},
)

qr = response.json()["qr"]

Response

{
  "qr": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAQAAAAEA..."
}

Phone Pairing

POST /sessions/{id}/pairphone

Conecta a sessão via código de pareamento por número de telefone. Não requer câmera ou leitura de QR code.

Tip

Phone Pairing é ideal para automações server-side onde não há interface visual para exibir QR code.

Parâmetros

Nome	Tipo	Obrigatório	Descrição
id	string	Sim	ID da sessão (path param)
phone	string	Sim	Número com código do país, sem +

Request

cURL

curl -X POST https://api.wi.api.br/sessions/01234567-89ab-cdef-0123-456789abcdef/pairphone \
  -H "x-api-key: $WIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phone": "5511987654321"}'

JavaScript

const response = await fetch(
  "https://api.wi.api.br/sessions/01234567-89ab-cdef-0123-456789abcdef/pairphone",
  {
    method: "POST",
    headers: {
      "x-api-key": process.env.WIAPI_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ phone: "5511987654321" }),
  }
);

const pairing = await response.json();

Python

import requests

response = requests.post(
    "https://api.wi.api.br/sessions/01234567-89ab-cdef-0123-456789abcdef/pairphone",
    headers={"x-api-key": WIAPI_KEY},
    json={"phone": "5511987654321"},
)

pairing = response.json()

Response

{
  "code": "4A7B-2C9D",
  "expiresIn": 60
}

Conectar

POST /sessions/{id}/connect

Reconecta uma sessão que foi desconectada. Não é necessário escanear QR novamente.

Parâmetros

Nome	Tipo	Obrigatório	Descrição
id	string	Sim	ID da sessão (path param)

Request

cURL

curl -X POST https://api.wi.api.br/sessions/01234567-89ab-cdef-0123-456789abcdef/connect \
  -H "x-api-key: $WIAPI_KEY"

JavaScript

const response = await fetch(
  "https://api.wi.api.br/sessions/01234567-89ab-cdef-0123-456789abcdef/connect",
  {
    method: "POST",
    headers: { "x-api-key": process.env.WIAPI_KEY },
  }
);

const result = await response.json();

Python

import requests

response = requests.post(
    "https://api.wi.api.br/sessions/01234567-89ab-cdef-0123-456789abcdef/connect",
    headers={"x-api-key": WIAPI_KEY},
)

result = response.json()

Response

{
  "status": "connected"
}

Desconectar

POST /sessions/{id}/disconnect

Pausa a sessão temporariamente. A sessão pode ser reconectada com o endpoint Connect sem escanear QR novamente.

Parâmetros

Nome	Tipo	Obrigatório	Descrição
id	string	Sim	ID da sessão (path param)

Request

cURL

curl -X POST https://api.wi.api.br/sessions/01234567-89ab-cdef-0123-456789abcdef/disconnect \
  -H "x-api-key: $WIAPI_KEY"

JavaScript

const response = await fetch(
  "https://api.wi.api.br/sessions/01234567-89ab-cdef-0123-456789abcdef/disconnect",
  {
    method: "POST",
    headers: { "x-api-key": process.env.WIAPI_KEY },
  }
);

const result = await response.json();

Python

import requests

response = requests.post(
    "https://api.wi.api.br/sessions/01234567-89ab-cdef-0123-456789abcdef/disconnect",
    headers={"x-api-key": WIAPI_KEY},
)

result = response.json()

Response

{
  "status": "disconnected"
}

Logout

POST /sessions/{id}/logout

Remove a sessão permanentemente do WhatsApp. Para reconectar, será necessário escanear QR ou parear novamente.

Danger

Logout é irreversível. Todos os dispositivos vinculados a esta sessão serão desconectados.

Parâmetros

Nome	Tipo	Obrigatório	Descrição
id	string	Sim	ID da sessão (path param)

Request

cURL

curl -X POST https://api.wi.api.br/sessions/01234567-89ab-cdef-0123-456789abcdef/logout \
  -H "x-api-key: $WIAPI_KEY"

JavaScript

const response = await fetch(
  "https://api.wi.api.br/sessions/01234567-89ab-cdef-0123-456789abcdef/logout",
  {
    method: "POST",
    headers: { "x-api-key": process.env.WIAPI_KEY },
  }
);

const result = await response.json();

Python

import requests

response = requests.post(
    "https://api.wi.api.br/sessions/01234567-89ab-cdef-0123-456789abcdef/logout",
    headers={"x-api-key": WIAPI_KEY},
)

result = response.json()

Response

{
  "status": "logged_out"
}

Obter configurações

GET /sessions/{id}/config

Retorna as configurações atuais da sessão.

Parâmetros

Nome	Tipo	Obrigatório	Descrição
id	string	Sim	ID da sessão (path param)

Request

cURL

curl https://api.wi.api.br/sessions/01234567-89ab-cdef-0123-456789abcdef/config \
  -H "x-api-key: $WIAPI_KEY"

JavaScript

const response = await fetch(
  "https://api.wi.api.br/sessions/01234567-89ab-cdef-0123-456789abcdef/config",
  { headers: { "x-api-key": process.env.WIAPI_KEY } }
);

const config = await response.json();

Python

import requests

response = requests.get(
    "https://api.wi.api.br/sessions/01234567-89ab-cdef-0123-456789abcdef/config",
    headers={"x-api-key": WIAPI_KEY},
)

config = response.json()

Response

{
  "skipmedia": false,
  "skipgroups": false,
  "skipnewsletters": false,
  "skipbroadcasts": false,
  "skipownmessages": false,
  "skipcalls": false,
  "presence": true
}

Alterar configuração

POST /sessions/{id}/config/{key}

Ativa ou desativa uma configuração específica da sessão.

Parâmetros

Nome	Tipo	Obrigatório	Descrição
id	string	Sim	ID da sessão (path param)
key	string	Sim	Chave da configuração (path param)
enabled	boolean	Sim	true para ativar, false para desativar

Chaves disponíveis:

Chave	Efeito
skipmedia	Não recebe mídia nos webhooks (economiza banda)
skipgroups	Ignora mensagens de grupo
skipnewsletters	Ignora canais e newsletters
skipbroadcasts	Ignora listas de transmissão
skipownmessages	Não dispara webhook para mensagens enviadas
skipcalls	Ignora eventos de chamada
presence	Envia status “online” automaticamente

Request

cURL

curl -X POST https://api.wi.api.br/sessions/01234567-89ab-cdef-0123-456789abcdef/config/skipgroups \
  -H "x-api-key: $WIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled": true}'

JavaScript

const response = await fetch(
  "https://api.wi.api.br/sessions/01234567-89ab-cdef-0123-456789abcdef/config/skipgroups",
  {
    method: "POST",
    headers: {
      "x-api-key": process.env.WIAPI_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ enabled: true }),
  }
);

const result = await response.json();

Python

import requests

response = requests.post(
    "https://api.wi.api.br/sessions/01234567-89ab-cdef-0123-456789abcdef/config/skipgroups",
    headers={"x-api-key": WIAPI_KEY},
    json={"enabled": True},
)

result = response.json()

Response

{
  "key": "skipgroups",
  "enabled": true
}