Sua primeira instância

Uma instância representa uma conexão com o WhatsApp dentro do seu Projeto — na prática, um número de telefone conectado. Cada instância tem um id próprio (prefixo inst_), um status que descreve em que ponto do ciclo de vida ela está, e, depois de pareada, o número (phoneNumber) e o jid (o endereço do contato no WhatsApp). Você pode ter mais de uma instância por Projeto, até o limite de números do seu plano.

Este guia cobre o ciclo de vida completo: criar a instância, parear com o WhatsApp lendo o QR Code (por polling — recomendado — ou por Server-Sent Events), consultar o estado atual, remover e tratar os erros de cada etapa.

Autenticação e modos

Todas as requisições exigem o header Authorization: Bearer <API_KEY>. A única exceção é o endpoint de QR via SSE, que autentica via ?token=<API_KEY> na query string, porque o EventSource do navegador não envia headers (detalhado em Alternativa: stream SSE). O endpoint de QR via polling usa o header normalmente.

O host decide o modo, e a key precisa casar com ele:

Uma key de teste contra o host de produção (ou vice-versa) retorna 401. Os exemplos abaixo usam a URL de produção; troque o host e o prefixo da key para validar no sandbox.

Ciclo de vida

O status da instância é um enum de seis valores:

O caminho feliz, do zero ao número operando, percorre os quatro primeiros em ordem:

DISCONNECTED  →  CONNECTING  →  QR_PENDING  →  CONNECTED

Logo após a criação, a instância nasce em DISCONNECTED. Quando você abre o fluxo de pareamento (qualquer um dos endpoints de QR abaixo), ela passa por CONNECTING e chega a QR_PENDING, expondo o QR Code. Assim que o QR é lido no aparelho, ela vai para CONNECTED — e só então aceita envio de mensagens.

Listar instâncias

Para ver todas as instâncias do Projeto no modo atual:

curl https://api.pepinozap.com.br/v1/instances \
  -H "Authorization: Bearer $YOUR_API_KEY"

Resposta 200 OK com um array (vazio [] se você ainda não criou nenhuma):

[
  {
    "id": "inst_abc123",
    "projectId": "proj_xyz789",
    "name": "minha-instancia",
    "status": "CONNECTED",
    "phoneNumber": "5511999999999",
    "jid": "5511999999999@s.whatsapp.net",
    "settings": {
      "rejectCalls": false,
      "rejectCallMessage": "",
      "ignoreGroups": false,
      "alwaysOnline": false,
      "readReceipts": false
    },
    "createdAt": "2026-05-30T12:00:00Z",
    "updatedAt": "2026-05-30T12:00:00Z"
  }
]

A lista traz apenas as instâncias do modo da key usada (teste ou produção).

Criar uma instância

O único campo do corpo é o name:

curl -X POST https://api.pepinozap.com.br/v1/instances \
  -H "Authorization: Bearer $YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "minha-instancia"}'

Resposta 201 Created:

{
  "id": "inst_abc123",
  "projectId": "proj_xyz789",
  "name": "minha-instancia",
  "status": "DISCONNECTED",
  "phoneNumber": null,
  "jid": null,
  "settings": {
    "rejectCalls": false,
    "rejectCallMessage": "",
    "ignoreGroups": false,
    "alwaysOnline": false,
    "readReceipts": false
  },
  "createdAt": "2026-05-30T12:00:00Z",
  "updatedAt": "2026-05-30T12:00:00Z"
}

O que cada campo significa logo na criação:

• id — guarde este valor. É ele que identifica a instância em todas as demais chamadas (QR, consulta, envio, configurações, remoção).
• status — sempre DISCONNECTED no nascimento; só muda quando você inicia o pareamento.
• phoneNumber e jid — vêm null enquanto a instância não estiver pareada. São preenchidos automaticamente após o CONNECTED (o phoneNumber é o número em formato E.164 sem +, e o jid é o endereço completo no WhatsApp, ex.: 5511999999999@s.whatsapp.net).
• settings — começa com todas as opções desligadas (ver Configurações da instância).

Erros ao criar

O envelope de erro é { "error": { "code", "message" } }.

Parear via QR Code

O pareamento conecta o número do WhatsApp à instância. O fluxo é: você abre um dos endpoints de QR, isso pede ao serviço para gerar um QR Code na hora, você renderiza esse código na sua interface, e o usuário o lê no aparelho em WhatsApp → Aparelhos conectados → Conectar um aparelho. Assim que o aparelho confirma, a instância vai para CONNECTED.

Há duas formas de obter o QR Code. Recomendamos o polling (GET /v1/instances/{id}/qr/poll): cada requisição é curta e atravessa antivírus e proxies corporativos sem problemas. O stream SSE (GET /v1/instances/{id}/qr) é uma alternativa, porém alguns antivírus e proxies bufferizam streams e impedem a entrega do QR Code.

Polling (recomendado)

Faça GET /v1/instances/{id}/qr/poll a cada ~2 segundos. Cada chamada faz duas coisas: pede ao worker que conecte a instância agora (idempotente — não faz nada se já houver conexão, e revive o QR se o ciclo anterior expirou) e devolve o snapshot atual.

O corpo da resposta (200 OK) tem dois campos:

Exemplos de resposta — antes e depois do pareamento:

// ainda aguardando leitura
{
  "connected": false,
  "qr": {
    "code": "2@A1b2C3d4E5f6...",
    "at": "2026-05-30T12:00:03Z"
  }
}

// pareamento concluído — pare o polling
{
  "connected": true,
  "qr": null
}

const id = 'inst_abc123';
const apiKey = 'pzk_live_...';

const timer = setInterval(async () => {
  const res = await fetch(`https://api.pepinozap.com.br/v1/instances/${id}/qr/poll`, {
    headers: { Authorization: `Bearer ${apiKey}` },
  });
  const { connected, qr } = await res.json();

  if (connected) {
    clearInterval(timer); // pareamento concluído
    return;
  }
  if (qr) {
    // Renderize "qr.code" como QR Code usando uma biblioteca de QR.
    renderQrCode(qr.code);
  }
}, 2000);

Alternativa: stream SSE

O endpoint GET /v1/instances/{id}/qr transmite Server-Sent Events (Content-Type: text/event-stream). Em vez de você consultar repetidamente, o servidor empurra os eventos conforme acontecem. Os eventos são:

Trate PAIRED/CONNECTED como sucesso e PAIR_TIMEOUT/PAIR_ERROR/LOGGED_OUT/STREAM_REPLACED/TEMPORARY_BAN como falha/encerramento. Não faça um switch estrito só nos 6 valores do enum de status: o stream pareceria "travado" esperando um CONNECTED que, num timeout/erro, nunca chega. O polling acima evita essa complexidade — ele só expõe connected: true/false.

Abra o stream, renderize o code do evento qr e, quando o evento status reportar CONNECTED ou PAIRED, o pareamento foi concluído.

Token efêmero (não exponha a API key na URL)

Como o EventSource autentica pela query string (?token=), passar a API key crua na URL a expõe em logs e no histórico do navegador. Para evitar isso, emita um token efêmero com POST /v1/instances/{id}/qr-token e use-o no ?token=.

curl -X POST https://api.pepinozap.com.br/v1/instances/$INSTANCE_ID/qr-token \
  -H "Authorization: Bearer $YOUR_API_KEY"

Resposta 200 OK:

{ "token": "eyJhbGciOiJI..." }

O token é válido por ~2 minutos e serve apenas para abrir o stream de QR dessa instância — não dá acesso ao resto da API. Se o pareamento demorar mais que isso, emita um novo token e reabra o stream.

const id = 'inst_abc123';

// Emita o token efêmero (em vez de expor a API key na URL).
const tokenRes = await fetch(`https://api.pepinozap.com.br/v1/instances/${id}/qr-token`, {
  method: 'POST',
  headers: { Authorization: `Bearer ${apiKey}` },
});
const { token } = await tokenRes.json();

const url = `https://api.pepinozap.com.br/v1/instances/${id}/qr?token=${token}`;
const source = new EventSource(url);

source.addEventListener('ready', () => {
  // Stream aberto; aguardando o primeiro evento "qr".
});

source.addEventListener('qr', (event) => {
  const { code } = JSON.parse(event.data);
  // Renderize "code" como QR Code usando uma biblioteca de QR.
  renderQrCode(code);
});

source.addEventListener('status', (event) => {
  const { status } = JSON.parse(event.data);
  if (status === 'CONNECTED' || status === 'PAIRED') {
    source.close(); // pareado com sucesso
  } else if (['PAIR_TIMEOUT', 'PAIR_ERROR', 'LOGGED_OUT', 'STREAM_REPLACED', 'TEMPORARY_BAN'].includes(status)) {
    source.close(); // falhou/encerrou — gere um novo QR ou trate o erro
  }
});

Erros ao parear

O pareamento não exige plano ativo — você pode gerar e ler o QR Code mesmo sem assinatura. O que exige plano é criar a instância e enviar mensagens.

Consultar e remover

Consultar

Verifique o estado atual da instância a qualquer momento — é assim que você confirma se o pareamento chegou ao CONNECTED e lê o phoneNumber/jid preenchidos:

curl https://api.pepinozap.com.br/v1/instances/$INSTANCE_ID \
  -H "Authorization: Bearer $YOUR_API_KEY"

Resposta 200 OK com a instância completa:

{
  "id": "inst_abc123",
  "projectId": "proj_xyz789",
  "name": "minha-instancia",
  "status": "CONNECTED",
  "phoneNumber": "5511999999999",
  "jid": "5511999999999@s.whatsapp.net",
  "settings": {
    "rejectCalls": false,
    "rejectCallMessage": "",
    "ignoreGroups": false,
    "alwaysOnline": false,
    "readReceipts": false
  },
  "createdAt": "2026-05-30T12:00:00Z",
  "updatedAt": "2026-05-30T12:05:00Z"
}

Consultar não exige plano ativo — leitura é sempre liberada.

Remover

Para remover uma instância (retorna 204 No Content, sem corpo):

curl -X DELETE https://api.pepinozap.com.br/v1/instances/$INSTANCE_ID \
  -H "Authorization: Bearer $YOUR_API_KEY"

A remoção não exige plano ativo. Ela desfaz o pareamento e libera a vaga de número na sua cota — depois disso, o id não responde mais (uma consulta posterior retorna 404). Se você quiser reconectar o mesmo número, crie uma nova instância e pareie de novo.

Configurações da instância

Cada instância tem um conjunto de configurações de comportamento — pequenos liga/desliga que mudam como o número conectado reage a chamadas, grupos, presença e leitura. São totalmente opcionais: por padrão todas vêm desligadas (o comportamento neutro do WhatsApp), e você liga só as que fizerem sentido para o seu caso.

São cinco configurações, resumidas aqui e detalhadas logo abaixo:

Como atualizar

Use PATCH /v1/instances/{id}/settings. É um patch parcial: envie apenas os campos que quer alterar — os que você omitir permanecem com o valor atual (não são zerados). Para ligar só uma opção, mande só ela.

curl -X PATCH https://api.pepinozap.com.br/v1/instances/$INSTANCE_ID/settings \
  -H "Authorization: Bearer $YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "rejectCalls": true,
    "rejectCallMessage": "No momento não atendemos chamadas. Envie uma mensagem que respondemos por aqui.",
    "ignoreGroups": true,
    "alwaysOnline": false,
    "readReceipts": true
  }'

A resposta é 200 OK com a instância completa, já trazendo o objeto settings atualizado:

{
  "id": "inst_abc123",
  "projectId": "proj_xyz789",
  "name": "minha-instancia",
  "status": "CONNECTED",
  "phoneNumber": "5511999999999",
  "jid": "5511999999999@s.whatsapp.net",
  "settings": {
    "rejectCalls": true,
    "rejectCallMessage": "No momento não atendemos chamadas. Envie uma mensagem que respondemos por aqui.",
    "ignoreGroups": true,
    "alwaysOnline": false,
    "readReceipts": true
  },
  "createdAt": "2026-05-30T12:00:00Z",
  "updatedAt": "2026-06-05T12:00:00Z"
}

As mudanças são persistidas e aplicadas ao número em poucos segundos (no próximo ciclo de sincronização do worker). Continuam valendo após quedas, reconexões e deploys — você não precisa reenviar a cada conexão.

O que cada configuração faz

rejectCalls — rejeitar chamadas (boolean, padrão false)

Quando true, toda chamada de voz ou vídeo recebida é rejeitada automaticamente, na hora, sem tocar. Ideal para números que são só de mensagens (atendimento, notificações). Quando false, as chamadas tocam normalmente. Para avisar quem ligou, combine com rejectCallMessage.

rejectCallMessage — resposta automática à chamada (string, padrão "")

Texto enviado automaticamente como mensagem para quem ligou, logo depois de a chamada ser rejeitada. Só tem efeito quando rejectCalls: true (é ignorado se as chamadas não estão sendo rejeitadas). Deixe vazio para rejeitar sem mandar nada.

ignoreGroups — ignorar grupos (boolean, padrão false)

Quando true, mensagens recebidas em grupos são ignoradas pela plataforma: não disparam webhook nem WebSocket, e não criam nem atualizam conversa no CRM (Inbox). Use quando você só quer tratar conversas individuais (1:1) e não ser inundado pelo tráfego de grupos. Não afeta mensagens que você envia para grupos pela API. Quando false, os grupos são processados normalmente.

alwaysOnline — sempre online (boolean, padrão false)

Quando true, o número aparece sempre "online" para os contatos enquanto a instância estiver conectada (a presença "disponível" é reanunciada a cada conexão). Quando false, a presença segue o comportamento normal do WhatsApp. Não altera a entrega de mensagens — muda só a indicação de presença que os contatos veem.

readReceipts — confirmação de leitura automática (boolean, padrão false)

Quando true, cada mensagem recebida é marcada como lida automaticamente assim que a plataforma a processa — o remetente vê o "lido" (tique azul). Quando false, as mensagens não são marcadas como lidas (o remetente não vê o tique azul), mesmo que você já as tenha recebido pelo webhook. Ligue se quer dar confirmação de leitura automática aos contatos.

importHistory — importar histórico ao conectar (boolean, padrão false)

Quando true, ao parear a instância a plataforma importa o histórico de conversas que o WhatsApp libera no pareamento e o persiste — você passa a lê-lo pelos endpoints de Inbox. Quando false (padrão), a instância começa do zero: captura só as mensagens novas dali pra frente (conecta e carrega mais rápido). Para trazer conversas anteriores sob demanda depois (sem ligar o import no pareamento), use POST /v1/inbox/conversations/{id}/history — ele puxa o lote anterior de uma conversa específica.

Como desligar uma configuração

Como é patch parcial, para desligar uma opção envie-a com o valor desligado — false (booleanos) ou "" (o texto de rejeição):

curl -X PATCH https://api.pepinozap.com.br/v1/instances/$INSTANCE_ID/settings \
  -H "Authorization: Bearer $YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "rejectCalls": false, "rejectCallMessage": "" }'

Erros possíveis

O envelope de erro é { "error": { "code", "message" } }.

• 400 — corpo JSON inválido (por exemplo, um campo com o tipo errado).
• 401 — API key ausente ou inválida.
• 403 — projeto inativo.
• 404 — instância não encontrada (não existe, não é do seu Projeto, ou é de outro modo — teste/produção).

A referência completa, com todos os campos e o playground "Try it", está em API Reference: configurações da instância.

Erros por endpoint

Todos os erros usam o envelope { "error": { "code", "message" } }. Resumo por etapa deste guia:

Próximos passos

• Autenticação — como usar a API key e os modos teste/produção.
• Configurações da instância (API Reference) — referência completa do PATCH de settings.
• Enviar mensagens — envio de texto e mídia após o pareamento.
• Webhooks — receba eventos de mensagens e de status da instância.