Instância

Status, configurações e ciclo de vida da conexão.

Basehttps://app.onzap.io/v1/instances/{instanceId}AuthX-Instance-Token: SEU_TOKEN

Dados e status da instância

GET/v1/instances/{instanceId}

API OnZapAPI oficial

Dados da instância e o status da conexão (connectionStatus): STOPPED, STARTING, SCAN_QR_CODE, WORKING ou FAILED. Só envia mensagens em WORKING.

Na API oficial: mesmo formato; connectionStatus é WORKING enquanto a conexão com a Meta estiver válida.

Requisição

curl "https://app.onzap.io/v1/instances/SUA_INSTANCIA" \
  -H "X-Instance-Token: $ONZAP_TOKEN"

Resposta

Dados da instância

{
  "instance": {
    "billingStatus": "active",
    "cancelAtPeriodEnd": false,
    "connectionStatus": "WORKING",
    "createdAt": "2026-09-30T14:05:00Z",
    "currentPeriodEnd": "2026-10-30T14:05:00Z",
    "graceUntil": "2026-11-06T14:05:00Z",
    "id": "i01jabcdefghjkmnpqrstvwxyz",
    "name": "Loja Centro",
    "phone": "5511999999999",
    "provider": "onzap",
    "provisionedAt": "2026-09-30T14:05:00Z",
    "pushName": "Maria",
    "settings": {
      "client": {
        "browserName": "Chrome",
        "deviceName": "OnZap"
      },
      "ignore": {
        "broadcast": false,
        "channels": false,
        "groups": false,
        "status": false
      },
      "storage": {
        "chats": false,
        "contacts": false,
        "groups": false,
        "labels": false,
        "messageSecrets": false,
        "messages": false
      }
    },
    "suspendedAt": "2026-09-30T14:05:00Z",
    "trialEndsAt": "2026-10-02T14:05:00Z"
  }
}

Atualizar configurações da instância

PATCH/v1/instances/{instanceId}/settings

API OnZap

Ignorar eventos de grupos, status, canais ou listas de transmissão; nome do aparelho em "Aparelhos conectados"; o que fica guardado localmente.

Corpo (JSON)

clientobjectopcional

Como a instância aparece em "Aparelhos conectados" no celular.

client.browserNamestringopcional

Nome do navegador em "Aparelhos conectados".

client.deviceNamestringopcional

Nome do aparelho em "Aparelhos conectados" (até 40 caracteres).

ignoreobjectopcional

Tipos de conversa cujos eventos não são emitidos.

ignore.broadcastbooleanopcional

Não emitir eventos de listas de transmissão.

ignore.channelsbooleanopcional

Não emitir eventos de canais.

ignore.groupsbooleanopcional

Não emitir eventos de grupos.

ignore.statusbooleanopcional

Não emitir eventos de status (stories).

storageobjectopcional

O que a instância guarda para as rotas de leitura (GET /chats, /contacts, histórico). Desligar economiza memória, mas essas rotas passam a voltar vazias.

storage.chatsbooleanopcional

Guardar a lista de conversas.

storage.contactsbooleanopcional

Guardar os contatos.

storage.groupsbooleanopcional

Guardar os grupos.

storage.labelsbooleanopcional

Guardar as etiquetas.

storage.messageSecretsbooleanopcional

Guardar as chaves de mensagens (necessário para votos de enquete e edições).

storage.messagesbooleanopcional

Guardar mensagens (histórico das conversas).

Requisição

curl -X PATCH "https://app.onzap.io/v1/instances/SUA_INSTANCIA/settings" \
  -H "X-Instance-Token: $ONZAP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

Resposta

Dados da instância

{
  "instance": {
    "billingStatus": "active",
    "cancelAtPeriodEnd": false,
    "connectionStatus": "WORKING",
    "createdAt": "2026-09-30T14:05:00Z",
    "currentPeriodEnd": "2026-10-30T14:05:00Z",
    "graceUntil": "2026-11-06T14:05:00Z",
    "id": "i01jabcdefghjkmnpqrstvwxyz",
    "name": "Loja Centro",
    "phone": "5511999999999",
    "provider": "onzap",
    "provisionedAt": "2026-09-30T14:05:00Z",
    "pushName": "Maria",
    "settings": {
      "client": {
        "browserName": "Chrome",
        "deviceName": "OnZap"
      },
      "ignore": {
        "broadcast": false,
        "channels": false,
        "groups": false,
        "status": false
      },
      "storage": {
        "chats": false,
        "contacts": false,
        "groups": false,
        "labels": false,
        "messageSecrets": false,
        "messages": false
      }
    },
    "suspendedAt": "2026-09-30T14:05:00Z",
    "trialEndsAt": "2026-10-02T14:05:00Z"
  }
}

Conta do WhatsApp conectada

GET/v1/instances/{instanceId}/me

API OnZap

Requisição

curl "https://app.onzap.io/v1/instances/SUA_INSTANCIA/me" \
  -H "X-Instance-Token: $ONZAP_TOKEN"

Resposta

{
  "id": "5511999999999@c.us",
  "jid": "123123:123@s.whatsapp.net",
  "lid": "123123@lid",
  "messageCapping": {
    "cappingStatus": "FIRST_WARNING",
    "cycleEnd": 1785553199,
    "cycleStart": 1782874800,
    "mvStatus": "NOT_ELIGIBLE",
    "oteStatus": "NOT_ELIGIBLE",
    "totalQuota": 1000,
    "usedQuota": 640
  },
  "pushName": "Maria",
  "reachoutTimelock": {
    "enforcementType": "RESTRICT_ALL_COMPANIONS",
    "isActive": true,
    "timeEnforcementEnds": 1784477333
  }
}

Cota de novas conversas (capping)

GET/v1/instances/{instanceId}/capping

API OnZap

Requisição

curl "https://app.onzap.io/v1/instances/SUA_INSTANCIA/capping" \
  -H "X-Instance-Token: $ONZAP_TOKEN"

Resposta

{
  "cappingStatus": "FIRST_WARNING",
  "cycleEnd": 1785553199,
  "cycleStart": 1782874800,
  "mvStatus": "NOT_ELIGIBLE",
  "oteStatus": "NOT_ELIGIBLE",
  "totalQuota": 1000,
  "usedQuota": 640
}

Restrição de contato (timelock)

GET/v1/instances/{instanceId}/timelock

API OnZap

Requisição

curl "https://app.onzap.io/v1/instances/SUA_INSTANCIA/timelock" \
  -H "X-Instance-Token: $ONZAP_TOKEN"

Resposta

{
  "enforcementType": "RESTRICT_ALL_COMPANIONS",
  "isActive": true,
  "timeEnforcementEnds": 1784477333
}

Iniciar a instância

POST/v1/instances/{instanceId}/start

API OnZap

Liga a conexão (se o número já foi pareado, reconecta sem QR Code).

Requisição

curl -X POST "https://app.onzap.io/v1/instances/SUA_INSTANCIA/start" \
  -H "X-Instance-Token: $ONZAP_TOKEN"

Resposta

Dados da instância

{
  "instance": {
    "billingStatus": "active",
    "cancelAtPeriodEnd": false,
    "connectionStatus": "WORKING",
    "createdAt": "2026-09-30T14:05:00Z",
    "currentPeriodEnd": "2026-10-30T14:05:00Z",
    "graceUntil": "2026-11-06T14:05:00Z",
    "id": "i01jabcdefghjkmnpqrstvwxyz",
    "name": "Loja Centro",
    "phone": "5511999999999",
    "provider": "onzap",
    "provisionedAt": "2026-09-30T14:05:00Z",
    "pushName": "Maria",
    "settings": {
      "client": {
        "browserName": "Chrome",
        "deviceName": "OnZap"
      },
      "ignore": {
        "broadcast": false,
        "channels": false,
        "groups": false,
        "status": false
      },
      "storage": {
        "chats": false,
        "contacts": false,
        "groups": false,
        "labels": false,
        "messageSecrets": false,
        "messages": false
      }
    },
    "suspendedAt": "2026-09-30T14:05:00Z",
    "trialEndsAt": "2026-10-02T14:05:00Z"
  }
}

Parar a instância

POST/v1/instances/{instanceId}/stop

API OnZap

Desliga a conexão sem desparear: um start depois reconecta sem QR Code.

Requisição

curl -X POST "https://app.onzap.io/v1/instances/SUA_INSTANCIA/stop" \
  -H "X-Instance-Token: $ONZAP_TOKEN"

Resposta

Dados da instância

{
  "instance": {
    "billingStatus": "active",
    "cancelAtPeriodEnd": false,
    "connectionStatus": "WORKING",
    "createdAt": "2026-09-30T14:05:00Z",
    "currentPeriodEnd": "2026-10-30T14:05:00Z",
    "graceUntil": "2026-11-06T14:05:00Z",
    "id": "i01jabcdefghjkmnpqrstvwxyz",
    "name": "Loja Centro",
    "phone": "5511999999999",
    "provider": "onzap",
    "provisionedAt": "2026-09-30T14:05:00Z",
    "pushName": "Maria",
    "settings": {
      "client": {
        "browserName": "Chrome",
        "deviceName": "OnZap"
      },
      "ignore": {
        "broadcast": false,
        "channels": false,
        "groups": false,
        "status": false
      },
      "storage": {
        "chats": false,
        "contacts": false,
        "groups": false,
        "labels": false,
        "messageSecrets": false,
        "messages": false
      }
    },
    "suspendedAt": "2026-09-30T14:05:00Z",
    "trialEndsAt": "2026-10-02T14:05:00Z"
  }
}

Reiniciar a instância

POST/v1/instances/{instanceId}/restart

API OnZap

Requisição

curl -X POST "https://app.onzap.io/v1/instances/SUA_INSTANCIA/restart" \
  -H "X-Instance-Token: $ONZAP_TOKEN"

Resposta

Dados da instância

{
  "instance": {
    "billingStatus": "active",
    "cancelAtPeriodEnd": false,
    "connectionStatus": "WORKING",
    "createdAt": "2026-09-30T14:05:00Z",
    "currentPeriodEnd": "2026-10-30T14:05:00Z",
    "graceUntil": "2026-11-06T14:05:00Z",
    "id": "i01jabcdefghjkmnpqrstvwxyz",
    "name": "Loja Centro",
    "phone": "5511999999999",
    "provider": "onzap",
    "provisionedAt": "2026-09-30T14:05:00Z",
    "pushName": "Maria",
    "settings": {
      "client": {
        "browserName": "Chrome",
        "deviceName": "OnZap"
      },
      "ignore": {
        "broadcast": false,
        "channels": false,
        "groups": false,
        "status": false
      },
      "storage": {
        "chats": false,
        "contacts": false,
        "groups": false,
        "labels": false,
        "messageSecrets": false,
        "messages": false
      }
    },
    "suspendedAt": "2026-09-30T14:05:00Z",
    "trialEndsAt": "2026-10-02T14:05:00Z"
  }
}

Desconectar o WhatsApp (logout)

POST/v1/instances/{instanceId}/logout

API OnZap

Desconecta o número (remove o aparelho no celular). Para conectar de novo é preciso ler o QR Code.

Corpo (JSON)

appsobjectopcional

Options for the session apps during logout.

apps.purgebooleanopcional

Purge the session apps' storage (messages, caches) as part of logout.

Requisição

curl -X POST "https://app.onzap.io/v1/instances/SUA_INSTANCIA/logout" \
  -H "X-Instance-Token: $ONZAP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

Resposta

Dados da instância

{
  "instance": {
    "billingStatus": "active",
    "cancelAtPeriodEnd": false,
    "connectionStatus": "WORKING",
    "createdAt": "2026-09-30T14:05:00Z",
    "currentPeriodEnd": "2026-10-30T14:05:00Z",
    "graceUntil": "2026-11-06T14:05:00Z",
    "id": "i01jabcdefghjkmnpqrstvwxyz",
    "name": "Loja Centro",
    "phone": "5511999999999",
    "provider": "onzap",
    "provisionedAt": "2026-09-30T14:05:00Z",
    "pushName": "Maria",
    "settings": {
      "client": {
        "browserName": "Chrome",
        "deviceName": "OnZap"
      },
      "ignore": {
        "broadcast": false,
        "channels": false,
        "groups": false,
        "status": false
      },
      "storage": {
        "chats": false,
        "contacts": false,
        "groups": false,
        "labels": false,
        "messageSecrets": false,
        "messages": false
      }
    },
    "suspendedAt": "2026-09-30T14:05:00Z",
    "trialEndsAt": "2026-10-02T14:05:00Z"
  }
}