Skip to main content
PATCH
Atualização da Instância
Use este endpoint para atualizar os dados da própria instância na plataforma: o nome (name), os metadados (metadata) e o identificador de pesquisa (lookup_key). Ele não altera o perfil do WhatsApp (nome de exibição, foto, descrição). Para isso, use o endpoint de atualização de perfil. As configurações de comportamento têm o seu próprio endpoint de atualização de configurações.

Atualize só o que precisar

Você não precisa enviar todos os campos a cada chamada. Envie apenas o que quer mudar e tudo o que ficar de fora continua exatamente como está. Nenhum campo aceita null: name é sempre um texto, e os valores de metadata são sempre um texto ou um número. Para “limpar” um valor, veja a regra da string vazia logo abaixo.

Como o metadata é atualizado

O metadata também é atualizado de forma parcial: as chaves enviadas são alteradas e todas as outras permanecem intactas. Não é necessário (nem recomendado) reenviar o objeto inteiro.
  • Para alterar ou criar uma chave, envie a chave com o novo valor.
  • Para manter uma chave como está, simplesmente não a envie.
  • Para limpar o valor de uma chave, envie uma string vazia "".
Por exemplo, se a instância tem os metadados customer_id, customer_name e campaign, a requisição abaixo altera customer_id, limpa campaign e mantém customer_name intacto:

Chaves reservadas wa_

Chaves de metadata iniciadas com wa_ são gerenciadas automaticamente pela plataforma e funcionam como somente leitura: se você enviá-las na requisição, elas são ignoradas e os valores originais são preservados. Use outros nomes para as suas próprias chaves.

Autorizações

Authorization
string
header
obrigatório

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Parâmetros de caminho

instance_id
string
obrigatório

ID da instância.

Corpo

application/json
name
string

Nome da instância na plataforma. Sempre um texto, nunca null.

Exemplo:

"Minha Instância"

metadata
object

Metadados armazenados como chave e valor. Cada chave é um texto e o valor pode ser um texto ou um número, nunca null.

A atualização é parcial: apenas as chaves enviadas são alteradas e as demais permanecem como estão. Para limpar o valor de uma chave, envie uma string vazia "".

Chaves iniciadas com wa_ são gerenciadas pela plataforma e somente leitura: se enviadas, são ignoradas.

lookup_key
string

Identificador único opcional de pesquisa que permite associar sua instância a uma estrutura de dados específica. A Zapster API não utiliza esse dado internamente; ele serve exclusivamente para facilitar consultas na API.

Maximum string length: 32
Exemplo:

"ins_8j7wlxmpjlixx9mux5"

Resposta

Success

Estrutura de uma instância registrada na API.

created_at
string<date-time>
obrigatório

Data e hora de criação da instância no formato ISO 8601.

Exemplo:

"2024-10-03T21:56:22.620Z"

id
string
obrigatório

Identificador único da instância.

Exemplo:

"xy9rexnkwobmgg3tehgvs"

metadata
object
obrigatório

Metadados adicionais armazenados como chave e valor.

Exemplo:
name
string
obrigatório

Nome da instância.

Exemplo:

"MyNewInstance2"

owner
object
obrigatório

Informações sobre o proprietário da instância.

settings
object
obrigatório

Objeto opcional de configurações da sua instância.

status
enum<string>
obrigatório

Status atual da instância

Opções disponíveis:
connected,
disconnected,
offline
Exemplo:

"disconnected"

webhooks
object[]
obrigatório

Lista de webhooks configurados para esta instância.

connection_type
enum<string>

Tipo de conexão da instância:

  • unofficial: conexão via QR code (padrão)
  • waba: conexão via API oficial do WhatsApp (Cloud API da Meta)
Opções disponíveis:
unofficial,
waba
Exemplo:

"unofficial"

qrcode
string | null

QR Code da instância, caso disponível.

Exemplo:

null

lookup_key
string

Identificador de pesquisa criado anteriormente.

Exemplo:

"ins_8j7wlxmpjlixx9mux5"