Referência

Referência da API

Base URL https://api.pontzap.com.br. Corpo e respostas em JSON. Cada rota diz qual header usar (autenticação) e os erros seguem o padrão.

Instância

Uma instância é um número de WhatsApp conectado à PontZap. Aqui você conecta pelo QR code, consulta o estado, desconecta e ajusta perfil e privacidade.

Conectar ao WhatsApp

POST /instance/connect

header token (da instância)

Gera o QR code para parear o número. Sem phone, devolve o QR code em instance.qrcode (data URL PNG). Com phone, devolve um código de pareamento em instance.paircode.

Parâmetros (corpo JSON)

phone string
Telefone com DDI e DDD (só dígitos). Se informado, gera código de pareamento em vez de QR code.

Exemplo de requisição

curl -X POST 'https://api.pontzap.com.br/instance/connect' \
  -H 'token: SEU_TOKEN_DA_INSTANCIA' \
  -H 'Content-Type: application/json' \
  -d '{}'

Exemplo de resposta

200 OK · JSON
{
  "response": "Connecting",
  "connected": true,
  "loggedIn": false,
  "jid": null,
  "request_id": "93512449-a681-44d2-aa41-71597011b49d",
  "instance": {
    "id": "r395f3fbc2622e8",
    "token": "7f3c2a1e-…-token-da-instancia",
    "status": "connecting",
    "paircode": "",
    "qrcode": "data:image/png;base64,iVBORw0KGgoAAAANSU…",
    "name": "loja-centro",
    "profileName": "",
    "isBusiness": false,
    "systemName": "meu-erp",
    "owner": "",
    "current_presence": "unavailable",
    "currentPresence": "unavailable",
    "lastDisconnect": "",
    "lastDisconnectReason": "",
    "adminField01": "",
    "adminField02": "",
    "created": "2026-10-13 23:12:52.232Z",
    "updated": "2026-10-13 23:12:52.232Z"
  },
  "status": {
    "connected": true,
    "loggedIn": false,
    "jid": null
  }
}
  • O QR code expira em poucos segundos e é renovado: consulte GET /instance/status em intervalos curtos e mostre o qrcode mais recente.
  • Quando o celular confirma, status passa a connected, loggedIn vira true e chega o webhook connection.

Ver estado da instância

GET /instance/status

header token (da instância)

Diz se o número está conectado, conectando (com QR code pendente) ou desconectado.

Exemplo de requisição

curl -X GET 'https://api.pontzap.com.br/instance/status' \
  -H 'token: SEU_TOKEN_DA_INSTANCIA'

Exemplo de resposta

200 OK · JSON
{
  "instance": {
    "id": "r395f3fbc2622e8",
    "token": "7f3c2a1e-…-token-da-instancia",
    "status": "disconnected",
    "paircode": "",
    "qrcode": "",
    "name": "loja-centro",
    "profileName": "",
    "isBusiness": false,
    "systemName": "meu-erp",
    "owner": "",
    "current_presence": "unavailable",
    "currentPresence": "unavailable",
    "lastDisconnect": "",
    "lastDisconnectReason": "",
    "adminField01": "",
    "adminField02": "",
    "created": "2026-10-13 23:12:52.232Z",
    "updated": "2026-10-13 23:12:52.232Z"
  },
  "status": {
    "connected": false,
    "loggedIn": false,
    "jid": null
  }
}
  • Valores de instance.status: disconnected, connecting, connected.
  • Conectado, status.jid sai como objeto {user, agent, device, server}.

Desconectar

POST /instance/disconnect

header token (da instância)

Encerra a sessão do WhatsApp (logout). Para voltar será preciso um novo QR code. Emite o webhook connection.

Exemplo de requisição

curl -X POST 'https://api.pontzap.com.br/instance/disconnect' \
  -H 'token: SEU_TOKEN_DA_INSTANCIA'

Exemplo de resposta

200 OK · JSON
{
  "response": "Disconnected",
  "info": "Sessão encerrada. Será necessário um novo QR code para conectar.",
  "instance": {
    "id": "r395f3fbc2622e8",
    "token": "7f3c2a1e-…-token-da-instancia",
    "status": "disconnected",
    "paircode": "",
    "qrcode": "",
    "name": "loja-centro",
    "profileName": "",
    "isBusiness": false,
    "systemName": "meu-erp",
    "owner": "",
    "current_presence": "unavailable",
    "currentPresence": "unavailable",
    "lastDisconnect": "",
    "lastDisconnectReason": "disconnected by request",
    "adminField01": "",
    "adminField02": "",
    "created": "2026-10-13 23:12:52.232Z",
    "updated": "2026-10-13 23:12:52.232Z"
  }
}

Reiniciar a conexão

POST /instance/reset

header token (da instância)

Derruba e reconecta a sessão já pareada, sem pedir novo QR code. Intervalo mínimo de 10 segundos entre reinícios.

Exemplo de requisição

curl -X POST 'https://api.pontzap.com.br/instance/reset' \
  -H 'token: SEU_TOKEN_DA_INSTANCIA'

Apagar a instância

DELETE /instance

header token (da instância)

Desconecta o aparelho e remove a instância. O token deixa de funcionar.

Exemplo de requisição

curl -X DELETE 'https://api.pontzap.com.br/instance' \
  -H 'token: SEU_TOKEN_DA_INSTANCIA'

Exemplo de resposta

200 OK · JSON
{
  "response": "Instance Deleted",
  "info": "O dispositivo foi desconectado com sucesso e a instância foi removida do banco de dados."
}

Renomear a instância

POST /instance/updateInstanceName

header token (da instância)

Muda o nome interno da instância (o que aparece para você, não no WhatsApp).

Parâmetros (corpo JSON)

name stringobrigatório
Novo nome. Vazio responde 400.

Exemplo de requisição

curl -X POST 'https://api.pontzap.com.br/instance/updateInstanceName' \
  -H 'token: SEU_TOKEN_DA_INSTANCIA' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "loja-centro-2"
}'

Exemplo de resposta

200 OK · JSON
{
  "id": "r395f3fbc2622e8",
  "token": "7f3c2a1e-…-token-da-instancia",
  "status": "disconnected",
  "paircode": "",
  "qrcode": "",
  "name": "loja-centro-2",
  "profileName": "",
  "isBusiness": false,
  "systemName": "meu-erp",
  "owner": "",
  "current_presence": "unavailable",
  "currentPresence": "unavailable",
  "lastDisconnect": "",
  "lastDisconnectReason": "",
  "adminField01": "",
  "adminField02": "",
  "created": "2026-10-13 23:12:52.232Z",
  "updated": "2026-10-13 23:12:52.232Z"
}

Presença global

POST /instance/presence

header token (da instância)

Aparece como online (available) ou offline (unavailable) para todos os contatos.

Parâmetros (corpo JSON)

presence stringobrigatório
available ou unavailable.

Exemplo de requisição

curl -X POST 'https://api.pontzap.com.br/instance/presence' \
  -H 'token: SEU_TOKEN_DA_INSTANCIA' \
  -H 'Content-Type: application/json' \
  -d '{
  "presence": "available"
}'

Exemplo de resposta

200 OK · JSON
{
  "response": "Presence updated successfully"
}

Ver privacidade

GET /instance/privacy

header token (da instância)

Lê as configurações de privacidade da conta no WhatsApp. Exige a instância conectada.

Exemplo de requisição

curl -X GET 'https://api.pontzap.com.br/instance/privacy' \
  -H 'token: SEU_TOKEN_DA_INSTANCIA'

Alterar privacidade

POST /instance/privacy

header token (da instância)

Muda quem vê foto, status, visto por último etc. Só envia ao WhatsApp o que mudou.

Parâmetros (corpo JSON)

groupadd, last, status, profile, readreceipts, online, calladd string
Mande só as chaves que quer mudar, com os valores aceitos pelo WhatsApp (ex.: all, contacts, none).

Exemplo de requisição

curl -X POST 'https://api.pontzap.com.br/instance/privacy' \
  -H 'token: SEU_TOKEN_DA_INSTANCIA' \
  -H 'Content-Type: application/json' \
  -d '{
  "last": "contacts",
  "profile": "contacts"
}'

Nome do perfil

POST /profile/name

header token (da instância)

Altera o nome que seus contatos veem no WhatsApp.

Parâmetros (corpo JSON)

name stringobrigatório
Novo nome de perfil.

Exemplo de requisição

curl -X POST 'https://api.pontzap.com.br/profile/name' \
  -H 'token: SEU_TOKEN_DA_INSTANCIA' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "Loja Centro"
}'

Foto do perfil

POST /profile/image

header token (da instância)

Troca a foto do perfil. A imagem é convertida para JPEG 640×640. Use "remove" para apagar.

Parâmetros (corpo JSON)

image stringobrigatório
URL, data URL ou base64 da imagem, ou "remove".

Exemplo de requisição

curl -X POST 'https://api.pontzap.com.br/profile/image' \
  -H 'token: SEU_TOKEN_DA_INSTANCIA' \
  -H 'Content-Type: application/json' \
  -d '{
  "image": "https://meusite.com.br/logo.png"
}'

Envio

Enviar texto, mídia, contato e localização, direto ou pela fila assíncrona. Todas as rotas aceitam os campos comuns abaixo.

Enviar texto

POST /send/text

header token (da instância)

Envia uma mensagem de texto. A resposta traz o id da mensagem; o status de entrega e leitura chega depois pelo webhook messages_update.

Parâmetros (corpo JSON)

text stringobrigatório
Texto da mensagem.
number stringobrigatório
Telefone com DDI e DDD (ex.: 5592999999999) ou JID (…@s.whatsapp.net, …@g.us, …@lid, …@newsletter). Telefone é conferido no WhatsApp antes do envio.
async boolean
Coloca o envio na fila e responde na hora com status: "Queued". Veja “Fila assíncrona”.
delay number
Milissegundos mostrando “digitando…” antes de enviar (máximo 2 minutos).
replyid string
Id da mensagem a responder (citação).
mentions string
Telefones a mencionar, separados por vírgula.
forward boolean
Marca como encaminhada.
track_source / track_id string
Seus identificadores (ex.: erp / pedido-4821). Voltam na mensagem, no webhook e servem de filtro em /message/find.

Exemplo de requisição

curl -X POST 'https://api.pontzap.com.br/send/text' \
  -H 'token: SEU_TOKEN_DA_INSTANCIA' \
  -H 'Content-Type: application/json' \
  -d '{
  "number": "5592999999999",
  "text": "Seu pedido #4821 saiu para entrega.",
  "track_source": "erp",
  "track_id": "pedido-4821"
}'

Exemplo de resposta

200 OK · JSON
{
  "id": "5592988887777:3EB0D8448DC0B9FE593A2C",
  "messageid": "3EB0D8448DC0B9FE593A2C",
  "chatid": "5592999999999@s.whatsapp.net",
  "fromMe": true,
  "isGroup": false,
  "messageType": "Conversation",
  "source": "api",
  "messageTimestamp": 1791933175740,
  "status": "Sent",
  "text": "Seu pedido #4821 saiu para entrega.",
  "wasSentByApi": true,
  "sendFunction": "/send/text",
  "sendPayload": {
    "number": "5592999999999",
    "text": "Seu pedido #4821 saiu para entrega."
  },
  "track_source": "erp",
  "track_id": "pedido-4821",
  "owner": "5592988887777",
  "response": {
    "status": "success",
    "message": "Message sent successfully"
  }
}

Erros comuns

  • 400 — Missing number or text, Invalid number, The number … is not on WhatsApp ou WhatsApp instance is not connected.
  • Com a instância conectada, id sai como owner:messageid (owner = número da instância). As rotas de /message/* aceitam o id completo ou só o messageid.

Enviar mídia

POST /send/media

header token (da instância)

Imagem, vídeo, áudio, documento ou figurinha. O arquivo pode ser uma URL pública, data URL ou base64.

Parâmetros (corpo JSON)

type stringobrigatório
image, video, videoplay, ptv, audio, myaudio, ptt (áudio de voz, exige OGG/Opus), document ou sticker (exige WebP).
file stringobrigatório
URL, data URL ou base64.
text string
Legenda.
docName string
Nome do arquivo (documentos).
mimetype string
Força o tipo MIME.
viewOnce boolean
Visualização única.
number stringobrigatório
Telefone com DDI e DDD (ex.: 5592999999999) ou JID (…@s.whatsapp.net, …@g.us, …@lid, …@newsletter). Telefone é conferido no WhatsApp antes do envio.
async boolean
Coloca o envio na fila e responde na hora com status: "Queued". Veja “Fila assíncrona”.
delay number
Milissegundos mostrando “digitando…” antes de enviar (máximo 2 minutos).
replyid string
Id da mensagem a responder (citação).
mentions string
Telefones a mencionar, separados por vírgula.
forward boolean
Marca como encaminhada.
track_source / track_id string
Seus identificadores (ex.: erp / pedido-4821). Voltam na mensagem, no webhook e servem de filtro em /message/find.

Exemplo de requisição

curl -X POST 'https://api.pontzap.com.br/send/media' \
  -H 'token: SEU_TOKEN_DA_INSTANCIA' \
  -H 'Content-Type: application/json' \
  -d '{
  "number": "5592999999999",
  "type": "document",
  "file": "https://meusite.com.br/boleto-4821.pdf",
  "docName": "boleto-4821.pdf",
  "text": "Segue o boleto."
}'

Erros comuns

  • 400 — Invalid media type, Missing file, Could not download file…, ptt requires an OGG/Opus file.
  • 413 — Arquivo grande demais (File too large).

Enviar contato (vCard)

POST /send/contact

header token (da instância)

Envia um cartão de contato com um ou mais telefones.

Parâmetros (corpo JSON)

fullName stringobrigatório
Nome do contato.
phoneNumber stringobrigatório
Um ou mais telefones, separados por vírgula.
organization, email, url string
Opcionais.
number stringobrigatório
Telefone com DDI e DDD (ex.: 5592999999999) ou JID (…@s.whatsapp.net, …@g.us, …@lid, …@newsletter). Telefone é conferido no WhatsApp antes do envio.
async boolean
Coloca o envio na fila e responde na hora com status: "Queued". Veja “Fila assíncrona”.
delay number
Milissegundos mostrando “digitando…” antes de enviar (máximo 2 minutos).
replyid string
Id da mensagem a responder (citação).
mentions string
Telefones a mencionar, separados por vírgula.
forward boolean
Marca como encaminhada.
track_source / track_id string
Seus identificadores (ex.: erp / pedido-4821). Voltam na mensagem, no webhook e servem de filtro em /message/find.

Exemplo de requisição

curl -X POST 'https://api.pontzap.com.br/send/contact' \
  -H 'token: SEU_TOKEN_DA_INSTANCIA' \
  -H 'Content-Type: application/json' \
  -d '{
  "number": "5592999999999",
  "fullName": "Suporte Loja Centro",
  "phoneNumber": "5592988887777"
}'

Enviar localização

POST /send/location

header token (da instância)

Envia um ponto no mapa. Coordenadas fora do intervalo válido respondem 400.

Parâmetros (corpo JSON)

latitude numberobrigatório
-90 a 90.
longitude numberobrigatório
-180 a 180.
name, address string
Nome e endereço exibidos.
number stringobrigatório
Telefone com DDI e DDD (ex.: 5592999999999) ou JID (…@s.whatsapp.net, …@g.us, …@lid, …@newsletter). Telefone é conferido no WhatsApp antes do envio.
async boolean
Coloca o envio na fila e responde na hora com status: "Queued". Veja “Fila assíncrona”.
delay number
Milissegundos mostrando “digitando…” antes de enviar (máximo 2 minutos).
replyid string
Id da mensagem a responder (citação).
mentions string
Telefones a mencionar, separados por vírgula.
forward boolean
Marca como encaminhada.
track_source / track_id string
Seus identificadores (ex.: erp / pedido-4821). Voltam na mensagem, no webhook e servem de filtro em /message/find.

Exemplo de requisição

curl -X POST 'https://api.pontzap.com.br/send/location' \
  -H 'token: SEU_TOKEN_DA_INSTANCIA' \
  -H 'Content-Type: application/json' \
  -d '{
  "number": "5592999999999",
  "latitude": -3.119,
  "longitude": -60.0217,
  "name": "Loja Centro",
  "address": "Av. Eduardo Ribeiro, 520"
}'

“Digitando…” ou “gravando…”

POST /message/presence

header token (da instância)

Mostra para o contato que você está digitando ou gravando áudio. Com delay, mantém por até 5 minutos.

Parâmetros (corpo JSON)

number stringobrigatório
Telefone ou JID.
presence stringobrigatório
composing, recording ou paused.
delay number
Milissegundos para manter a presença.

Exemplo de requisição

curl -X POST 'https://api.pontzap.com.br/message/presence' \
  -H 'token: SEU_TOKEN_DA_INSTANCIA' \
  -H 'Content-Type: application/json' \
  -d '{
  "number": "5592999999999",
  "presence": "composing",
  "delay": 3000
}'

Exemplo de resposta

200 OK · JSON
{
  "response": "Chat presence sent successfully"
}

Estado da fila

GET /message/async

header token (da instância)

Quantos envios esperam na fila e o que ela está fazendo.

Exemplo de requisição

curl -X GET 'https://api.pontzap.com.br/message/async' \
  -H 'token: SEU_TOKEN_DA_INSTANCIA'

Exemplo de resposta

200 OK · JSON
{
  "response": "Async queue status",
  "instanceId": "r395f3fbc2622e8",
  "queue": {
    "status": "waiting_connection",
    "pending": 1,
    "processingNow": false,
    "acceptingNewMessages": true,
    "sessionReady": false,
    "resetting": false
  }
}
  • queue.status: idle (vazia), queued, processing ou waiting_connection (aguardando o número reconectar).

Cancelar a fila

DELETE /message/async

header token (da instância)

Cancela os envios que ainda não saíram. As mensagens ficam com status Canceled.

Exemplo de requisição

curl -X DELETE 'https://api.pontzap.com.br/message/async' \
  -H 'token: SEU_TOKEN_DA_INSTANCIA'

Exemplo de resposta

200 OK · JSON
{
  "response": "Async queue cleared",
  "instanceId": "r395f3fbc2622e8",
  "stats": {
    "persistedQueuedCanceled": 1,
    "trackedJobsCleared": 0,
    "bufferedJobsMarkedCanceled": 0,
    "drainedChannelJobs": 0,
    "clearedOverflowJobs": 0
  }
}

Intervalo entre envios da fila

POST /instance/updateDelaySettings

header token (da instância)

Define um intervalo aleatório, em segundos, entre uma mensagem e outra da fila. Ajuda a proteger o número.

Parâmetros (corpo JSON)

msg_delay_min numberobrigatório
Mínimo em segundos.
msg_delay_max numberobrigatório
Máximo em segundos (se menor que o mínimo, vira o mínimo).

Exemplo de requisição

curl -X POST 'https://api.pontzap.com.br/instance/updateDelaySettings' \
  -H 'token: SEU_TOKEN_DA_INSTANCIA' \
  -H 'Content-Type: application/json' \
  -d '{
  "msg_delay_min": 2,
  "msg_delay_max": 6
}'

Exemplo de resposta

200 OK · JSON
{
  "instance": {
    "id": "r395f3fbc2622e8",
    "token": "7f3c2a1e-…-token-da-instancia",
    "status": "disconnected",
    "paircode": "",
    "qrcode": "",
    "name": "loja-centro",
    "profileName": "",
    "isBusiness": false,
    "systemName": "meu-erp",
    "owner": "",
    "current_presence": "unavailable",
    "currentPresence": "unavailable",
    "lastDisconnect": "",
    "lastDisconnectReason": "",
    "adminField01": "",
    "adminField02": "",
    "created": "2026-10-13 23:12:52.232Z",
    "updated": "2026-10-13 23:12:52.232Z"
  }
}

Mensagens

Buscar mensagens guardadas (enviadas, recebidas e o histórico que o celular manda ao conectar) e agir sobre elas: ler, reagir, editar, apagar, fixar, baixar mídia.

Buscar mensagens

POST /message/find

header token (da instância)

Procura por id, conversa, tipo ou pelos seus identificadores track_source/track_id. Paginado com hasMore.

Parâmetros (corpo JSON)

id string
Id completo (owner:messageid) ou curto.
chatid string
Telefone ou JID da conversa.
messageType string
Tipo da mensagem (ex.: Conversation, ImageMessage).
track_source / track_id string
Os identificadores que você mandou no envio.
limit / offset number
Paginação.

Exemplo de requisição

curl -X POST 'https://api.pontzap.com.br/message/find' \
  -H 'token: SEU_TOKEN_DA_INSTANCIA' \
  -H 'Content-Type: application/json' \
  -d '{
  "track_source": "erp",
  "track_id": "pedido-4821",
  "limit": 10
}'

Exemplo de resposta

200 OK · JSON
{
  "messages": [
    {
      "id": "3EB0D8448DC0B9FE593A2C",
      "messageid": "3EB0D8448DC0B9FE593A2C",
      "chatid": "5592999999999@s.whatsapp.net",
      "fromMe": true,
      "isGroup": false,
      "messageType": "Conversation",
      "source": "api",
      "messageTimestamp": 1791933175740,
      "status": "Queued",
      "text": "Seu pedido #4821 saiu para entrega.",
      "wasSentByApi": true,
      "sendFunction": "/send/text",
      "sendPayload": {
        "number": "5592999999999",
        "text": "Seu pedido #4821 saiu para entrega."
      },
      "track_source": "erp",
      "track_id": "pedido-4821"
    }
  ],
  "pagination": {
    "limit": 10,
    "offset": 0,
    "hasMore": false
  }
}
  • As mensagens ficam guardadas por 90 dias (configurável).

Baixar mídia

POST /message/download

header token (da instância)

Baixa a mídia de uma mensagem (ou da mensagem citada). Devolve um link público válido por 2 dias e, se pedir, o base64.

Parâmetros (corpo JSON)

id stringobrigatório
Id da mensagem.
return_base64 boolean
Inclui o arquivo em base64 na resposta.
download_quoted boolean
Baixa a mídia da mensagem citada.

Exemplo de requisição

curl -X POST 'https://api.pontzap.com.br/message/download' \
  -H 'token: SEU_TOKEN_DA_INSTANCIA' \
  -H 'Content-Type: application/json' \
  -d '{
  "id": "3EB0D8448DC0B9FE593A2C",
  "return_base64": false
}'
  • generate_mp3 e transcribe ainda não são suportados (aceitos e ignorados).

Marcar como lida

POST /message/markread

header token (da instância)

Marca uma ou várias mensagens como lidas (os “dois tiques azuis”). Resultado por id.

Parâmetros (corpo JSON)

id string | string[]obrigatório
Um id ou uma lista.

Exemplo de requisição

curl -X POST 'https://api.pontzap.com.br/message/markread' \
  -H 'token: SEU_TOKEN_DA_INSTANCIA' \
  -H 'Content-Type: application/json' \
  -d '{
  "id": [
    "3EB0D8448DC0B9FE593A2C"
  ]
}'

Reagir

POST /message/react

header token (da instância)

Reage com um emoji. Emoji vazio ("") remove a reação.

Parâmetros (corpo JSON)

id stringobrigatório
Id da mensagem.
text stringobrigatório
O emoji, ou "" para remover.

Exemplo de requisição

curl -X POST 'https://api.pontzap.com.br/message/react' \
  -H 'token: SEU_TOKEN_DA_INSTANCIA' \
  -H 'Content-Type: application/json' \
  -d '{
  "id": "3EB0D8448DC0B9FE593A2C",
  "text": "👍"
}'

Editar

POST /message/edit

header token (da instância)

Edita o texto de uma mensagem enviada pela própria conta.

Parâmetros (corpo JSON)

id stringobrigatório
Id da mensagem.
text stringobrigatório
Novo texto.

Exemplo de requisição

curl -X POST 'https://api.pontzap.com.br/message/edit' \
  -H 'token: SEU_TOKEN_DA_INSTANCIA' \
  -H 'Content-Type: application/json' \
  -d '{
  "id": "3EB0D8448DC0B9FE593A2C",
  "text": "Seu pedido #4821 saiu para entrega (previsão 15h)."
}'

Apagar para todos

POST /message/delete

header token (da instância)

Apaga a mensagem para todos. O status Deleted é definitivo e gera o webhook messages_update.

Parâmetros (corpo JSON)

id stringobrigatório
Id da mensagem.

Exemplo de requisição

curl -X POST 'https://api.pontzap.com.br/message/delete' \
  -H 'token: SEU_TOKEN_DA_INSTANCIA' \
  -H 'Content-Type: application/json' \
  -d '{
  "id": "3EB0D8448DC0B9FE593A2C"
}'

Fixar mensagem

POST /message/pin

header token (da instância)

Fixa ou desafixa uma mensagem na conversa por 1, 7 ou 30 dias (outro valor vira 7).

Parâmetros (corpo JSON)

id stringobrigatório
Id da mensagem.
pin booleanobrigatório
true fixa, false desafixa.
duration number
Dias: 1, 7 ou 30.

Exemplo de requisição

curl -X POST 'https://api.pontzap.com.br/message/pin' \
  -H 'token: SEU_TOKEN_DA_INSTANCIA' \
  -H 'Content-Type: application/json' \
  -d '{
  "id": "3EB0D8448DC0B9FE593A2C",
  "pin": true,
  "duration": 7
}'

Quem recebeu e leu (grupos)

POST /message/status

header token (da instância)

Lista os recibos de entrega e leitura de uma mensagem enviada em grupo. Os recibos ficam gravados no banco.

Parâmetros (corpo JSON)

id stringobrigatório
Id da mensagem.
state string
Filtra por estado (ex.: Read).
limit / offset number
Paginação.

Exemplo de requisição

curl -X POST 'https://api.pontzap.com.br/message/status' \
  -H 'token: SEU_TOKEN_DA_INSTANCIA' \
  -H 'Content-Type: application/json' \
  -d '{
  "id": "3EB0D8448DC0B9FE593A2C"
}'

Chats e contatos

Conversas, contatos e bloqueios. Os chats ficam guardados no banco da PontZap, então a busca e os contadores funcionam mesmo com o número desconectado.

Buscar chats

POST /chat/find

header token (da instância)

Filtra conversas por qualquer campo wa_* (ex.: wa_isGroup, wa_unreadCount, wa_archived), com operadores e ordenação.

Parâmetros (corpo JSON)

wa_* / phone qualquer
Filtros. Valor com operador na frente: =, !=, ~ (contém), !~, >, >=, <, <=. Ex.: "wa_unreadCount": ">0".
operator string
AND (padrão) ou OR entre os filtros.
sort string
Campo com + ou - na frente. Ex.: -wa_lastMsgTimestamp.
limit / offset number
Padrão 2000 (completo) ou 100 com compact (máximo 200).
compact boolean
Resposta enxuta.

Exemplo de requisição

curl -X POST 'https://api.pontzap.com.br/chat/find' \
  -H 'token: SEU_TOKEN_DA_INSTANCIA' \
  -H 'Content-Type: application/json' \
  -d '{
  "wa_isGroup": false,
  "wa_unreadCount": ">0",
  "sort": "-wa_lastMsgTimestamp",
  "limit": 20
}'

Exemplo de resposta

200 OK · JSON
{
  "chats": [],
  "pagination": {
    "totalRecords": 0,
    "limit": 20,
    "offset": 0,
    "hasMore": false
  },
  "totalChatsStats": {
    "total": 0,
    "unread": 0,
    "groups": 0,
    "archived": 0,
    "pinned": 0
  }
}

Erros comuns

  • 400 — Filtro de CRM (lead_*) ainda não suportado.

Contadores

GET /chat/totalcount

header token (da instância)

Totais de conversas abertas, arquivadas, de grupo, bloqueadas e não lidas. Lê só o banco.

Exemplo de requisição

curl -X GET 'https://api.pontzap.com.br/chat/totalcount' \
  -H 'token: SEU_TOKEN_DA_INSTANCIA'

Exemplo de resposta

200 OK · JSON
{
  "total_chats": {
    "total": 0,
    "unread": 0
  },
  "open_chats": {
    "total": 0,
    "unread": 0
  },
  "archived_chats": {
    "total": 0,
    "unread": 0
  },
  "group_chats": {
    "total": 0,
    "unread": 0
  },
  "blocked_chats": {
    "total": 0,
    "unread": 0
  },
  "label_counts": [],
  "attendant_counts": []
}

Detalhes de um chat

POST /chat/details

header token (da instância)

O chat completo, com nome, foto e se é conta comercial.

Parâmetros (corpo JSON)

number stringobrigatório
Telefone ou JID.
preview boolean
Foto em miniatura.

Exemplo de requisição

curl -X POST 'https://api.pontzap.com.br/chat/details' \
  -H 'token: SEU_TOKEN_DA_INSTANCIA' \
  -H 'Content-Type: application/json' \
  -d '{
  "number": "5592999999999"
}'

Foto de um chat

POST /chat/avatar

header token (da instância)

URL da foto do contato ou grupo.

Parâmetros (corpo JSON)

number stringobrigatório
Telefone ou JID.
preview boolean
Miniatura.

Exemplo de requisição

curl -X POST 'https://api.pontzap.com.br/chat/avatar' \
  -H 'token: SEU_TOKEN_DA_INSTANCIA' \
  -H 'Content-Type: application/json' \
  -d '{
  "number": "5592999999999",
  "preview": true
}'

Verificar números

POST /chat/check

header token (da instância)

Confere se até 500 números têm WhatsApp, e devolve o JID e o nome verificado.

Parâmetros (corpo JSON)

numbers string[]obrigatório
Telefones ou JIDs (até 500).

Exemplo de requisição

curl -X POST 'https://api.pontzap.com.br/chat/check' \
  -H 'token: SEU_TOKEN_DA_INSTANCIA' \
  -H 'Content-Type: application/json' \
  -d '{
  "numbers": [
    "5592999999999",
    "5511988887777"
  ]
}'

Arquivar

POST /chat/archive

header token (da instância)

Arquiva ou desarquiva. Arquivar também desafixa.

Parâmetros (corpo JSON)

number stringobrigatório
Telefone ou JID.
archive booleanobrigatório
true arquiva.

Exemplo de requisição

curl -X POST 'https://api.pontzap.com.br/chat/archive' \
  -H 'token: SEU_TOKEN_DA_INSTANCIA' \
  -H 'Content-Type: application/json' \
  -d '{
  "number": "5592999999999",
  "archive": true
}'

Fixar chat

POST /chat/pin

header token (da instância)

Fixa ou desafixa a conversa no topo.

Parâmetros (corpo JSON)

number stringobrigatório
Telefone ou JID.
pin booleanobrigatório
true fixa.

Exemplo de requisição

curl -X POST 'https://api.pontzap.com.br/chat/pin' \
  -H 'token: SEU_TOKEN_DA_INSTANCIA' \
  -H 'Content-Type: application/json' \
  -d '{
  "number": "5592999999999",
  "pin": true
}'

Silenciar

POST /chat/mute

header token (da instância)

Silencia por 8 horas, 1 semana ou para sempre.

Parâmetros (corpo JSON)

number stringobrigatório
Telefone ou JID.
muteEndTime numberobrigatório
0 (tira o silêncio), 8 (horas), 168 (1 semana) ou -1 (sempre). Outro valor → 400.

Exemplo de requisição

curl -X POST 'https://api.pontzap.com.br/chat/mute' \
  -H 'token: SEU_TOKEN_DA_INSTANCIA' \
  -H 'Content-Type: application/json' \
  -d '{
  "number": "5592999999999",
  "muteEndTime": 8
}'

Marcar chat como lido

POST /chat/read

header token (da instância)

Marca a conversa inteira como lida ou não lida.

Parâmetros (corpo JSON)

number stringobrigatório
Telefone ou JID.
read booleanobrigatório
true lida, false não lida.

Exemplo de requisição

curl -X POST 'https://api.pontzap.com.br/chat/read' \
  -H 'token: SEU_TOKEN_DA_INSTANCIA' \
  -H 'Content-Type: application/json' \
  -d '{
  "number": "5592999999999",
  "read": true
}'

Mensagens temporárias

POST /chat/ephemeral

header token (da instância)

Liga ou desliga as mensagens que somem sozinhas numa conversa privada.

Parâmetros (corpo JSON)

number stringobrigatório
Telefone ou JID.
duration string | numberobrigatório
0/off, 24h, 7d, 90d ou segundos.

Exemplo de requisição

curl -X POST 'https://api.pontzap.com.br/chat/ephemeral' \
  -H 'token: SEU_TOKEN_DA_INSTANCIA' \
  -H 'Content-Type: application/json' \
  -d '{
  "number": "5592999999999",
  "duration": "7d"
}'

Apagar chat

POST /chat/delete

header token (da instância)

Apaga o chat no banco da PontZap e, se pedir, no WhatsApp. Sem flags, apaga só o registro local.

Parâmetros (corpo JSON)

number stringobrigatório
Telefone ou JID.
deleteChatDB boolean
Apaga o chat no banco.
deleteMessagesDB boolean
Apaga as mensagens no banco.
deleteChatWhatsApp boolean
Apaga a conversa no WhatsApp.

Exemplo de requisição

curl -X POST 'https://api.pontzap.com.br/chat/delete' \
  -H 'token: SEU_TOKEN_DA_INSTANCIA' \
  -H 'Content-Type: application/json' \
  -d '{
  "number": "5592999999999",
  "deleteChatDB": true,
  "deleteMessagesDB": true
}'
  • A resposta traz {response, actions, errors} com o resultado de cada ação.

Agenda

GET /contacts

header token (da instância)

Contatos da sessão do WhatsApp. Exige a instância conectada.

Exemplo de requisição

curl -X GET 'https://api.pontzap.com.br/contacts' \
  -H 'token: SEU_TOKEN_DA_INSTANCIA'

Agenda paginada

POST /contacts/list

header token (da instância)

Mesma agenda, em páginas.

Parâmetros (corpo JSON)

contactScope string
all ou address_book (só os salvos).
limit / offset number
Paginação (hasMore, nextOffset).

Exemplo de requisição

curl -X POST 'https://api.pontzap.com.br/contacts/list' \
  -H 'token: SEU_TOKEN_DA_INSTANCIA' \
  -H 'Content-Type: application/json' \
  -d '{
  "contactScope": "address_book",
  "limit": 100,
  "offset": 0
}'

Bloquear contato

POST /chat/block

header token (da instância)

Bloqueia ou desbloqueia. Devolve a lista de bloqueados atualizada.

Parâmetros (corpo JSON)

number stringobrigatório
Telefone ou JID.
block booleanobrigatório
true bloqueia.

Exemplo de requisição

curl -X POST 'https://api.pontzap.com.br/chat/block' \
  -H 'token: SEU_TOKEN_DA_INSTANCIA' \
  -H 'Content-Type: application/json' \
  -d '{
  "number": "5592999999999",
  "block": true
}'

Bloqueados

GET /chat/blocklist

header token (da instância)

Lista os contatos bloqueados. Exige a instância conectada.

Exemplo de requisição

curl -X GET 'https://api.pontzap.com.br/chat/blocklist' \
  -H 'token: SEU_TOKEN_DA_INSTANCIA'

Grupos e comunidades

Criar e administrar grupos e comunidades do WhatsApp. A lista de grupos fica em cache (sincroniza uma vez por conexão); force: true consulta o WhatsApp na hora.

Listar grupos (paginado)

POST /group/list

header token (da instância)

Lista os grupos do número, com busca por nome, JID, descrição ou comunidade. Página padrão 50, máximo 1000.

Parâmetros (corpo JSON)

search string
Texto a procurar.
limit / offset number
Paginação.
noParticipants boolean
Omite a lista de participantes (resposta menor).
force boolean
Ignora o cache e consulta o WhatsApp.

Exemplo de requisição

curl -X POST 'https://api.pontzap.com.br/group/list' \
  -H 'token: SEU_TOKEN_DA_INSTANCIA' \
  -H 'Content-Type: application/json' \
  -d '{
  "search": "clientes",
  "limit": 50,
  "offset": 0,
  "noParticipants": true
}'

Erros comuns

  • 408 — O WhatsApp não respondeu a tempo.

Listar grupos (todos)

GET /group/list

header token (da instância)

Versão antiga, sem paginação: devolve todos os grupos do cache.

Exemplo de requisição

curl -X GET 'https://api.pontzap.com.br/group/list' \
  -H 'token: SEU_TOKEN_DA_INSTANCIA'

Exemplo de resposta

200 OK · JSON
{
  "groups": []
}

Detalhes de um grupo

POST /group/info

header token (da instância)

Nome, descrição, participantes e configurações. Link de convite e pedidos de entrada só aparecem se o número for admin.

Parâmetros (corpo JSON)

groupjid stringobrigatório
JID do grupo (…@g.us).
getInviteLink boolean
Inclui o link de convite.
getRequestsParticipants boolean
Inclui os pedidos de entrada pendentes.
force boolean
Consulta o WhatsApp em vez do cache.

Exemplo de requisição

curl -X POST 'https://api.pontzap.com.br/group/info' \
  -H 'token: SEU_TOKEN_DA_INSTANCIA' \
  -H 'Content-Type: application/json' \
  -d '{
  "groupjid": "120363012345678901@g.us",
  "getInviteLink": true
}'

Criar grupo

POST /group/create

header token (da instância)

Cria um grupo com os participantes. Números inválidos ou bloqueados pela privacidade voltam em failed.

Parâmetros (corpo JSON)

name stringobrigatório
Nome do grupo.
participants string[]obrigatório
Telefones ou JIDs. O próprio número é ignorado.

Exemplo de requisição

curl -X POST 'https://api.pontzap.com.br/group/create' \
  -H 'token: SEU_TOKEN_DA_INSTANCIA' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "Clientes VIP",
  "participants": [
    "5592999999999",
    "5592988887777"
  ]
}'

Ver grupo pelo convite

POST /group/inviteInfo

header token (da instância)

Mostra os dados de um grupo a partir do código ou link de convite, sem entrar nele. Link revogado → 400.

Parâmetros (corpo JSON)

invitecode stringobrigatório
Código ou link completo.

Exemplo de requisição

curl -X POST 'https://api.pontzap.com.br/group/inviteInfo' \
  -H 'token: SEU_TOKEN_DA_INSTANCIA' \
  -H 'Content-Type: application/json' \
  -d '{
  "invitecode": "https://chat.whatsapp.com/AbCdEfGhIjK"
}'

Entrar num grupo

POST /group/join

header token (da instância)

Entra no grupo pelo código ou link de convite.

Parâmetros (corpo JSON)

invitecode stringobrigatório
Código ou link completo.

Exemplo de requisição

curl -X POST 'https://api.pontzap.com.br/group/join' \
  -H 'token: SEU_TOKEN_DA_INSTANCIA' \
  -H 'Content-Type: application/json' \
  -d '{
  "invitecode": "AbCdEfGhIjK"
}'

Sair do grupo

POST /group/leave

header token (da instância)

O número sai do grupo.

Parâmetros (corpo JSON)

groupjid stringobrigatório
JID do grupo.

Exemplo de requisição

curl -X POST 'https://api.pontzap.com.br/group/leave' \
  -H 'token: SEU_TOKEN_DA_INSTANCIA' \
  -H 'Content-Type: application/json' \
  -d '{
  "groupjid": "120363012345678901@g.us"
}'

Novo link de convite

POST /group/resetInviteCode

header token (da instância)

Revoga o link atual e gera outro.

Parâmetros (corpo JSON)

groupjid stringobrigatório
JID do grupo.

Exemplo de requisição

curl -X POST 'https://api.pontzap.com.br/group/resetInviteCode' \
  -H 'token: SEU_TOKEN_DA_INSTANCIA' \
  -H 'Content-Type: application/json' \
  -d '{
  "groupjid": "120363012345678901@g.us"
}'

Gerenciar participantes

POST /group/updateParticipants

header token (da instância)

Adiciona, remove, promove a admin, rebaixa, aprova ou recusa pedidos de entrada. Resultado por participante.

Parâmetros (corpo JSON)

groupjid stringobrigatório
JID do grupo.
action stringobrigatório
add, remove, promote, demote, approve ou reject.
participants string[]obrigatório
Telefones ou JIDs.

Exemplo de requisição

curl -X POST 'https://api.pontzap.com.br/group/updateParticipants' \
  -H 'token: SEU_TOKEN_DA_INSTANCIA' \
  -H 'Content-Type: application/json' \
  -d '{
  "groupjid": "120363012345678901@g.us",
  "action": "add",
  "participants": [
    "5592977776666"
  ]
}'
  • Quem a privacidade impede de ser adicionado volta com Error: 403 e um AddRequest (convite).

Renomear grupo

POST /group/updateName

header token (da instância)

Muda o nome do grupo e devolve o grupo relido.

Parâmetros (corpo JSON)

groupjid stringobrigatório
JID do grupo.
name stringobrigatório
Novo nome.

Exemplo de requisição

curl -X POST 'https://api.pontzap.com.br/group/updateName' \
  -H 'token: SEU_TOKEN_DA_INSTANCIA' \
  -H 'Content-Type: application/json' \
  -d '{
  "groupjid": "120363012345678901@g.us",
  "name": "Clientes VIP 2026"
}'
  • Nesta e nas outras rotas updateX: se a releitura falhar, a resposta traz o cache com needs_refresh: true.

Descrição do grupo

POST /group/updateDescription

header token (da instância)

Muda a descrição (até 2048 caracteres; acima disso → 413).

Parâmetros (corpo JSON)

groupjid stringobrigatório
JID do grupo.
description stringobrigatório
Texto.

Exemplo de requisição

curl -X POST 'https://api.pontzap.com.br/group/updateDescription' \
  -H 'token: SEU_TOKEN_DA_INSTANCIA' \
  -H 'Content-Type: application/json' \
  -d '{
  "groupjid": "120363012345678901@g.us",
  "description": "Avisos de promoções e novidades."
}'

Foto do grupo

POST /group/updateImage

header token (da instância)

Troca a foto. Imagem que não dá para decodificar → 415.

Parâmetros (corpo JSON)

groupjid stringobrigatório
JID do grupo.
image stringobrigatório
URL, data URL ou base64.

Exemplo de requisição

curl -X POST 'https://api.pontzap.com.br/group/updateImage' \
  -H 'token: SEU_TOKEN_DA_INSTANCIA' \
  -H 'Content-Type: application/json' \
  -d '{
  "groupjid": "120363012345678901@g.us",
  "image": "https://meusite.com.br/logo.png"
}'

Só admins enviam

POST /group/updateAnnounce

header token (da instância)

Liga ou desliga o modo em que só administradores mandam mensagem.

Parâmetros (corpo JSON)

groupjid stringobrigatório
JID do grupo.
announce booleanobrigatório
true = só admins enviam.

Exemplo de requisição

curl -X POST 'https://api.pontzap.com.br/group/updateAnnounce' \
  -H 'token: SEU_TOKEN_DA_INSTANCIA' \
  -H 'Content-Type: application/json' \
  -d '{
  "groupjid": "120363012345678901@g.us",
  "announce": true
}'

Só admins editam

POST /group/updateLocked

header token (da instância)

Define se só administradores podem mudar nome, foto e descrição.

Parâmetros (corpo JSON)

groupjid stringobrigatório
JID do grupo.
locked booleanobrigatório
true = só admins editam.

Exemplo de requisição

curl -X POST 'https://api.pontzap.com.br/group/updateLocked' \
  -H 'token: SEU_TOKEN_DA_INSTANCIA' \
  -H 'Content-Type: application/json' \
  -d '{
  "groupjid": "120363012345678901@g.us",
  "locked": true
}'

Aprovar entradas

POST /group/updateJoinApproval

header token (da instância)

Exige aprovação de um admin para quem entra pelo link.

Parâmetros (corpo JSON)

groupjid stringobrigatório
JID do grupo.
IsJoinApprovalRequired booleanobrigatório
true liga a aprovação.

Exemplo de requisição

curl -X POST 'https://api.pontzap.com.br/group/updateJoinApproval' \
  -H 'token: SEU_TOKEN_DA_INSTANCIA' \
  -H 'Content-Type: application/json' \
  -d '{
  "groupjid": "120363012345678901@g.us",
  "IsJoinApprovalRequired": true
}'

Quem pode adicionar

POST /group/updateMemberAddMode

header token (da instância)

Define se só admins ou todos os membros podem adicionar pessoas.

Parâmetros (corpo JSON)

groupjid stringobrigatório
JID do grupo.
MemberAddMode stringobrigatório
admin_add ou all_member_add.

Exemplo de requisição

curl -X POST 'https://api.pontzap.com.br/group/updateMemberAddMode' \
  -H 'token: SEU_TOKEN_DA_INSTANCIA' \
  -H 'Content-Type: application/json' \
  -d '{
  "groupjid": "120363012345678901@g.us",
  "MemberAddMode": "admin_add"
}'

Mensagens temporárias no grupo

POST /group/ephemeral

header token (da instância)

Liga ou desliga as mensagens que somem sozinhas.

Parâmetros (corpo JSON)

groupjid stringobrigatório
JID do grupo.
duration string | numberobrigatório
0/off, 24h, 7d, 90d ou segundos.

Exemplo de requisição

curl -X POST 'https://api.pontzap.com.br/group/ephemeral' \
  -H 'token: SEU_TOKEN_DA_INSTANCIA' \
  -H 'Content-Type: application/json' \
  -d '{
  "groupjid": "120363012345678901@g.us",
  "duration": "24h"
}'

Criar comunidade

POST /community/create

header token (da instância)

Cria uma comunidade (o “guarda-chuva” que reúne vários grupos).

Parâmetros (corpo JSON)

name stringobrigatório
Nome da comunidade.

Exemplo de requisição

curl -X POST 'https://api.pontzap.com.br/community/create' \
  -H 'token: SEU_TOKEN_DA_INSTANCIA' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "Rede de lojas"
}'

Grupos da comunidade

POST /community/editgroups

header token (da instância)

Inclui ou tira grupos de uma comunidade, em lote. O que falhar volta em failed.

Parâmetros (corpo JSON)

community stringobrigatório
JID da comunidade.
action stringobrigatório
add ou remove.
groupjids string[]obrigatório
JIDs dos grupos.

Exemplo de requisição

curl -X POST 'https://api.pontzap.com.br/community/editgroups' \
  -H 'token: SEU_TOKEN_DA_INSTANCIA' \
  -H 'Content-Type: application/json' \
  -d '{
  "community": "120363098765432109@g.us",
  "action": "add",
  "groupjids": [
    "120363012345678901@g.us"
  ]
}'

Exemplo de resposta

200 OK · JSON
{
  "message": "Groups updated successfully",
  "success": [
    "120363012345678901@g.us"
  ],
  "failed": []
}

Erros comuns

  • 403 — O número não é admin da comunidade.

Webhooks

Webhook é o endereço do seu sistema que a PontZap chama quando algo acontece: mensagem recebida, mensagem lida, número desconectado. Cada instância pode ter vários.

Configurar webhook

POST /webhook

header token (da instância)

Sem action, configura o webhook principal (cria se não existir). Com action add, update ou delete, gerencia vários webhooks. Responde a lista atualizada.

Parâmetros (corpo JSON)

url stringobrigatório
Endereço http(s) do seu sistema. Precisa ser público (veja a nota).
events string[]
Eventos a receber: connection, messages, messages_update, history, chats, groups, newsletter_messages, status_posts (ou all).
excludeMessages string[]
Filtros de messages: wasSentByApi, wasNotSentByApi, fromMeYes, fromMeNo, isGroupYes, isGroupNo.
addUrlEvents boolean
Acrescenta o evento ao fim da URL (…/messages).
addUrlTypesMessages boolean
Acrescenta o tipo da mensagem ao fim da URL.
enabled boolean
Liga/desliga sem apagar.
action / id string
add, update ou delete; id é obrigatório em update/delete.

Exemplo de requisição

curl -X POST 'https://api.pontzap.com.br/webhook' \
  -H 'token: SEU_TOKEN_DA_INSTANCIA' \
  -H 'Content-Type: application/json' \
  -d '{
  "url": "https://meusistema.com.br/webhooks/pontzap",
  "events": [
    "messages",
    "messages_update",
    "connection"
  ],
  "excludeMessages": [
    "wasSentByApi"
  ]
}'

Exemplo de resposta

200 OK · JSON
[
  {
    "id": "wh_db2aff2c34",
    "enabled": true,
    "url": "https://meusistema.com.br/webhooks/pontzap",
    "events": [
      "messages",
      "messages_update",
      "connection"
    ],
    "addUrlTypesMessages": false,
    "addUrlEvents": false,
    "excludeMessages": [
      "wasSentByApi"
    ]
  }
]

Erros comuns

  • 400 — Missing webhook url, Invalid webhook url, Invalid event: …, Webhook not found, Invalid action.
  • newsletter_messages e status_posts só chegam se estiverem listados pelo nome.
  • A PontZap só entrega para endereços públicos: localhost e IPs internos são recusados na entrega. Para testar na sua máquina, use um túnel (ngrok, Cloudflare Tunnel).

Ver webhooks

GET /webhook

header token (da instância)

Lista os webhooks da instância.

Exemplo de requisição

curl -X GET 'https://api.pontzap.com.br/webhook' \
  -H 'token: SEU_TOKEN_DA_INSTANCIA'

Exemplo de resposta

200 OK · JSON
[
  {
    "id": "wh_db2aff2c34",
    "enabled": true,
    "url": "https://meusistema.com.br/webhooks/pontzap",
    "events": [
      "messages",
      "messages_update",
      "connection"
    ],
    "addUrlTypesMessages": false,
    "addUrlEvents": false,
    "excludeMessages": [
      "wasSentByApi"
    ]
  }
]

Últimas falhas

GET /webhook/errors

header token (da instância)

As 20 últimas entregas que falharam de vez, com o payload, o status HTTP e o erro.

Exemplo de requisição

curl -X GET 'https://api.pontzap.com.br/webhook/errors' \
  -H 'token: SEU_TOKEN_DA_INSTANCIA'

Exemplo de resposta

200 OK · JSON
[
  {
    "created": "2026-10-13T23:20:00Z",
    "url": "https://meusistema.com.br/webhooks/pontzap",
    "type": "local",
    "event": "messages",
    "message_type": "Conversation",
    "status_code": 500,
    "attempts": 6,
    "error": "webhook returned non-success status: 500 Internal Server Error",
    "payload": {
      "EventType": "messages",
      "…": "…"
    },
    "stage": "http",
    "delivery_id": "1842"
  }
]

Administração

Rotas da conta (header admintoken): criar e listar instâncias, campos administrativos, rotação de token e o webhook global. Mais as rotas públicas de saúde.

Criar instância

POST /instance/create

header admintoken (da conta)

Cria uma instância desconectada e devolve o token dela. Guarde o token: é ele que autoriza as demais chamadas da instância.

Parâmetros (corpo JSON)

name stringobrigatório
Nome para você identificar (ex.: a loja ou o cliente).
systemName string
Nome do seu sistema.
adminField01 / adminField02 string
Campos livres para seu controle (ex.: id do cliente).

Exemplo de requisição

curl -X POST 'https://api.pontzap.com.br/instance/create' \
  -H 'admintoken: SEU_ADMINTOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "loja-centro",
  "systemName": "meu-erp"
}'

Exemplo de resposta

200 OK · JSON
{
  "response": "Instance created successfully",
  "instance": {
    "id": "r395f3fbc2622e8",
    "token": "7f3c2a1e-…-token-da-instancia",
    "status": "disconnected",
    "paircode": "",
    "qrcode": "",
    "name": "loja-centro",
    "profileName": "",
    "isBusiness": false,
    "systemName": "meu-erp",
    "owner": "",
    "current_presence": "unavailable",
    "currentPresence": "unavailable",
    "lastDisconnect": "",
    "lastDisconnectReason": "",
    "adminField01": "",
    "adminField02": "",
    "created": "2026-10-13 23:12:52.232Z",
    "updated": "2026-10-13 23:12:52.232Z"
  },
  "status": {
    "connected": false,
    "loggedIn": false,
    "jid": null
  },
  "name": "loja-centro",
  "token": "7f3c2a1e-…-token-da-instancia",
  "info": "Instância criada desconectada. Use /instance/connect para gerar o QR code."
}

Erros comuns

  • 400 — Missing name.

Listar instâncias

GET /instance/all

header admintoken (da conta)

Todas as instâncias da conta, com estado e token.

Exemplo de requisição

curl -X GET 'https://api.pontzap.com.br/instance/all' \
  -H 'admintoken: SEU_ADMINTOKEN'

Exemplo de resposta

200 OK · JSON
[
  {
    "id": "r395f3fbc2622e8",
    "token": "7f3c2a1e-…-token-da-instancia",
    "status": "disconnected",
    "paircode": "",
    "qrcode": "",
    "name": "loja-centro",
    "profileName": "",
    "isBusiness": false,
    "systemName": "meu-erp",
    "owner": "",
    "current_presence": "unavailable",
    "currentPresence": "unavailable",
    "lastDisconnect": "",
    "lastDisconnectReason": "",
    "adminField01": "",
    "adminField02": "",
    "created": "2026-10-13 23:12:52.232Z",
    "updated": "2026-10-13 23:12:52.232Z"
  }
]

Campos administrativos

POST /instance/updateAdminFields

header admintoken (da conta)

Atualiza adminField01/adminField02 de uma instância.

Parâmetros (corpo JSON)

id stringobrigatório
Id da instância (r…).
adminField01 / adminField02 string
Novos valores.

Exemplo de requisição

curl -X POST 'https://api.pontzap.com.br/instance/updateAdminFields' \
  -H 'admintoken: SEU_ADMINTOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "id": "r395f3fbc2622e8",
  "adminField01": "cliente-42"
}'

Exemplo de resposta

200 OK · JSON
{
  "id": "r395f3fbc2622e8",
  "token": "7f3c2a1e-…-token-da-instancia",
  "status": "disconnected",
  "paircode": "",
  "qrcode": "",
  "name": "loja-centro",
  "profileName": "",
  "isBusiness": false,
  "systemName": "meu-erp",
  "owner": "",
  "current_presence": "unavailable",
  "currentPresence": "unavailable",
  "lastDisconnect": "",
  "lastDisconnectReason": "",
  "adminField01": "cliente-42",
  "adminField02": "",
  "created": "2026-10-13 23:12:52.232Z",
  "updated": "2026-10-13 23:12:52.232Z"
}

Erros comuns

  • 404 — Instance not found.

Trocar o token da instância

POST /instance/token/rotate

header admintoken (da conta)

Gera um novo token. O antigo para de valer na hora — atualize seu sistema antes de confirmar.

Parâmetros (corpo JSON)

id stringobrigatório
Id da instância.
confirm_impacts booleanobrigatório
Precisa ser true. Sem isso, responde 409 listando os impactos.

Exemplo de requisição

curl -X POST 'https://api.pontzap.com.br/instance/token/rotate' \
  -H 'admintoken: SEU_ADMINTOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "id": "r395f3fbc2622e8",
  "confirm_impacts": true
}'

Erros comuns

  • 409 — Sem confirm_impacts: true (requires_confirmation, impacts, warnings).
  • 404 — Instance not found.

Webhook global

POST /globalwebhook

header admintoken (da conta)

Um único endereço que recebe os eventos de todas as instâncias da conta, com os mesmos filtros do webhook de instância.

Parâmetros (corpo JSON)

url stringobrigatório
Endereço público.
events string[]obrigatório
Eventos (mesma lista do webhook de instância).
excludeMessages, addUrlEvents, addUrlTypesMessages, enabled —
Como no webhook de instância.

Exemplo de requisição

curl -X POST 'https://api.pontzap.com.br/globalwebhook' \
  -H 'admintoken: SEU_ADMINTOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "url": "https://meusistema.com.br/webhooks/todas",
  "events": [
    "connection",
    "messages"
  ]
}'

Exemplo de resposta

200 OK · JSON
{
  "id": "wh_ea62dad75e",
  "enabled": true,
  "url": "https://meusistema.com.br/webhooks/todas",
  "events": [
    "connection",
    "messages"
  ],
  "addUrlTypesMessages": false,
  "addUrlEvents": false,
  "excludeMessages": []
}

Erros comuns

  • 400 — Missing url or events.

Ver webhook global

GET /globalwebhook

header admintoken (da conta)

Mostra a configuração atual. 404 se ainda não houver.

Exemplo de requisição

curl -X GET 'https://api.pontzap.com.br/globalwebhook' \
  -H 'admintoken: SEU_ADMINTOKEN'

Falhas do webhook global

GET /globalwebhook/errors

header admintoken (da conta)

Últimas entregas que falharam de vez no webhook global (type: "global").

Exemplo de requisição

curl -X GET 'https://api.pontzap.com.br/globalwebhook/errors' \
  -H 'admintoken: SEU_ADMINTOKEN'

Status do servidor

GET /status

pública, sem token

Público. Versão e quantas instâncias estão em cada estado.

Exemplo de requisição

curl -X GET 'https://api.pontzap.com.br/status'

Exemplo de resposta

200 OK · JSON
{
  "info": "Server health check completed",
  "build": {
    "version": "0.2.0",
    "revision": "dev",
    "date": ""
  },
  "instance_counts": {
    "total": 0,
    "connected": 0,
    "connecting": 0,
    "disconnected": 0,
    "observed_at": "2026-10-13T23:12:37Z"
  },
  "status": {
    "server_status": "running",
    "total_instances": 0,
    "last_check": "2026-10-13T23:12:37Z"
  }
}

Health check

GET /health

pública, sem token

Público. Responde {"status":"ok"} se o processo está de pé.

Exemplo de requisição

curl -X GET 'https://api.pontzap.com.br/health'

Exemplo de resposta

200 OK · JSON
{
  "status": "ok"
}

Pronto para atender

GET /health/ready

pública, sem token

Público. Confere o banco de dados; 503 com ready: false se algo falhar.

Exemplo de requisição

curl -X GET 'https://api.pontzap.com.br/health/ready'

Exemplo de resposta

200 OK · JSON
{
  "ready": true
}

Em breve

Rotas do contrato uazapi que a PontZap ainda não implementou. Hoje elas respondem 501 com a onda prevista, então uma integração que as chame recebe um erro claro em vez de um comportamento diferente.

Onda 2 — Contatos na agenda 2 rotas
  • POST /contact/add Adiciona um contato à agenda
  • POST /contact/remove Remove um contato da agenda
Onda 3 — Etiquetas e mensagens interativas 13 rotas
  • POST /message/payment/status Atualizar pagamento e pedido
  • POST /send/carousel Enviar carrossel de mídia com botões
  • POST /send/event Enviar evento
  • POST /send/group-invite Enviar convite de grupo
  • POST /send/location-button Solicitar localização do usuário
  • POST /send/menu Enviar menu interativo (botões, carrossel, lista ou enquete)
  • POST /send/pix-button Enviar botão PIX
  • POST /send/request-payment Solicitar pagamento
  • POST /send/status Enviar status (stories)
  • POST /chat/labels Gerencia labels de um chat
  • POST /label/edit Criar, editar ou deletar etiqueta
  • GET /labels Buscar todas as etiquetas
  • POST /labels/refresh Iniciar recarga de etiquetas do WhatsApp
Onda 4 — Canais, campanhas em massa, chamadas e SSE 37 rotas
  • POST /call/make Iniciar chamada de voz
  • POST /call/reject Rejeitar chamada recebida
  • POST /sender/advanced Criar envio em massa avançado
  • DELETE /sender/clearall Limpar toda fila de mensagens
  • POST /sender/cleardone Limpar mensagens enviadas
  • POST /sender/edit Controlar campanha de envio em massa
  • GET /sender/listfolders Listar campanhas de envio
  • POST /sender/listmessages Listar mensagens de uma campanha
  • POST /sender/simple Criar nova campanha (Simples)
  • GET /sender/stats Consultar estado e métricas das campanhas
  • POST /newsletter/admin/accept Aceitar convite de admin do canal
  • POST /newsletter/admin/invite Convidar admin do canal
  • POST /newsletter/admin/remove Remover admin do canal
  • POST /newsletter/admin/revoke Revogar convite de admin do canal
  • POST /newsletter/create Criar canal
  • POST /newsletter/delete Deletar canal
  • POST /newsletter/description Atualizar descrição do canal
  • POST /newsletter/follow Seguir canal
  • POST /newsletter/info Buscar informações de um canal
  • POST /newsletter/link Buscar canal por link-chave de convite
  • GET /newsletter/list Listar canais inscritos
  • POST /newsletter/messages Buscar mensagens de um canal
  • POST /newsletter/messages/delete Deletar mensagem recente de um canal
  • POST /newsletter/messages/edit Editar mensagem recente de um canal
  • POST /newsletter/mute Silenciar canal
  • POST /newsletter/name Atualizar nome do canal
  • POST /newsletter/owner/transfer Transferir dono do canal
  • POST /newsletter/picture Atualizar foto do canal
  • POST /newsletter/reaction Reagir a um post do canal
  • POST /newsletter/search Pesquisar canais públicos
  • POST /newsletter/settings Atualizar configurações do canal
  • POST /newsletter/subscribe Assinar live updates temporários de um canal
  • POST /newsletter/unfollow Deixar de seguir canal
  • POST /newsletter/unmute Remover mute do canal
  • POST /newsletter/updates Buscar updates de mensagens de um canal
  • POST /newsletter/viewed Marcar posts do canal como visualizados
  • GET /sse Server-Sent Events (SSE)
Onda 5 — Chatwoot, catálogo, respostas rápidas, CRM e proxy 38 rotas
  • POST /message/history-sync Solicitar histórico sob demanda de um chat
  • POST /message/reload Recuperar mensagem que não abriu
  • POST /admin/restart Reiniciar a aplicação
  • POST /admin/token/rotate Rotacionar admin token
  • DELETE /business/catalog/collection/{id} Apagar coleção do catálogo
  • PATCH /business/catalog/collection/{id} Editar coleção do catálogo
  • POST /business/catalog/collection/create Criar coleção no catálogo
  • GET /business/catalog/collection/list Listar coleções do catálogo
  • POST /business/catalog/delete Deletar um produto do catálogo
  • POST /business/catalog/hide Ocultar um produto do catálogo
  • POST /business/catalog/info Obter informações de um produto do catálogo
  • POST /business/catalog/list Listar os produtos do catálogo
  • POST /business/catalog/save Criar ou editar um produto do catálogo
  • POST /business/catalog/show Mostrar um produto do catálogo
  • GET /business/get/categories Obter as categorias de negócios
  • POST /business/get/profile Obter o perfil comercial
  • POST /business/update/profile Atualizar o perfil comercial
  • POST /chat/notes Consultar notas internas do chat
  • POST /chat/notes/edit Editar notas internas do chat
  • POST /chat/notes/refresh Recarregar notas internas do chat no WhatsApp
  • POST /chat/editLead Edita informações de lead
  • POST /instance/updateFieldsMap Nomear campos personalizados de leads
  • POST /lead/resolve Conclui conversas (aguardando você)
  • GET /lead/tags Lista tags de lead
  • POST /lead/tags/edit Cria, edita ou apaga uma tag de lead
  • GET /instance/history-sync/status Consultar o processamento do histórico inicial
  • GET /instance/wa_messages_limits Consultar limites atuais de novas conversas no WhatsApp
  • GET /chatwoot/config Obter configuração do Chatwoot
  • PUT /chatwoot/config Atualizar configuração do Chatwoot
  • GET /instance/proxy Obter configuração de proxy da instância
  • POST /instance/proxy Configurar ou alterar o proxy
  • GET /proxy-managed/cities Proxy Interno - Listar cidades disponíveis
  • GET /proxy-managed/countries Proxy Interno - Listar países disponíveis
  • GET /quick-replies Listar respostas rápidas
  • POST /quick-replies Criar resposta rápida
  • DELETE /quick-replies/{id} Apagar resposta rápida
  • GET /quick-replies/{id} Ver resposta rápida
  • PATCH /quick-replies/{id} Editar resposta rápida