# Introdução
Source: https://developer.z-api.io/api-reference/introduction
Visão geral da API da Z-API
## API Reference
Bem-vindo à referência da API da Z-API! Aqui você encontrará todos os endpoints disponíveis para interagir com o WhatsApp através da nossa plataforma.
***
## Base URL
Todas as requisições devem ser feitas para a seguinte URL base:
```
https://api.z-api.io/instances/{instanceId}/token/{token}
```
| Parâmetro | Descrição |
| - | - |
| `instanceId` | ID da sua instância, obtido no painel da Z-API |
| `token` | Token da sua instância, obtido no painel da Z-API |
***
## Autenticação
Além do ID e Token na URL, todas as requisições precisam do header de segurança:
| Header | Descrição |
| - | - |
| `Client-Token` | Token de segurança da conta. [Saiba mais](/security/client-token) |
***
## Formato das requisições
* Todas as requisições devem incluir o header `Content-Type: application/json`
* Os corpos das requisições e respostas são em formato JSON
***
## Códigos de resposta comuns
| Código | Descrição |
| - | - |
| `200` | Requisição realizada com sucesso |
| `400` | Requisição inválida. Verifique os dados enviados |
| `405` | Método HTTP incorreto |
| `415` | Header `Content-Type` não informado |
# Dados do celular
Source: https://developer.z-api.io/instance/device
GET /instances/{instanceId}/token/{token}/device
Retorna informações sobre o dispositivo/celular conectado à instância
## Conceituação
Este método é responsável por retornar informações sobre o device/celular conectado.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
***
## Response
### 200
Número telefônico do dispositivo conectado
URL da imagem/foto de perfil do usuário
Recado do perfil do contato
Nome do proprietário da conta
Informações do dispositivo
Identificador da sessão (padrão: Z-API)
Modelo do dispositivo ou identificação
Tipo original do aparelho: "iphone", "android", "smbi" ou "smba"
Identificador numérico único da sessão
Indica se é conta comercial
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"phone": "5511999999999",
"imgUrl": "https://...",
"about": "Recado do perfil do contato",
"name": "Nome do usuário",
"device": {
"sessionName": "Z-API",
"device_model": "Z-API"
},
"originalDevice": "iphone",
"sessionId": 175,
"isBusiness": false
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Desconectar
Source: https://developer.z-api.io/instance/disconnect
GET /instances/{instanceId}/token/{token}/disconnect
Desconecta o número do WhatsApp da instância Z-API
## Conceituação
Este método desconecta seu número do Z-API. Mas não se preocupe, para conectar novamente basta ler o QRCode :)
Uma vez desconectado todos os métodos da API ficam indisponíveis e os webhooks deixam de ser enviados.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
***
## Response
### 200
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"value": true
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Gerar token para extensão
Source: https://developer.z-api.io/instance/extension-token
GET /instances/{instanceId}/token/{token}/extension-token
Gera um token de acesso para autenticação na extensão Z-API
## Conceituação
Este método gera um token de acesso para autenticar a extensão Z-API. O token retornado deve ser inserido diretamente na extensão, e possui uma data de expiração definida.
O token tem validade de até **5 minutos**. Após esse período, é necessário gerar um novo.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
***
## Response
### 200
Token de acesso a ser inserido na extensão
Timestamp Unix (em milissegundos) com a data de expiração do token
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"token": "FA48-HS63",
"expiresAt": 1782851138085
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Introdução
Source: https://developer.z-api.io/instance/introduction
Entenda o que é uma instância na Z-API e como ela funciona
## Mas afinal o que é uma instância?
Uma instância é uma conexão a partir de um número de telefone com conta no WhatsApp, que será responsável pelo envio e recebimento de mensagens.
É possível criar várias instâncias para que você consiga ter vários números de WhatsApp conectado a sua conta.
Tecnicamente falando uma instância nada mais é do que uma máquina virtual (ou container) dentro da nossa infraestrutura de servidores, dedicada a prover um ambiente para conexão do seu número.
Cada instância só possui um número, caso precise conectar mais números será necessário criar mais instâncias.
Mas uma instância não é presa a um único número, ou seja, você pode desconectar um número e conectar outro na mesma instância.
Para ajudar você a entender o funcionamento do Z-API, nosso serviço roda com base em um WhatsApp Web, e abstraímos os métodos permitindo que você manipule via API RestFul.
**Curiosidade**
É bacana você saber que toda vez que você cria uma instância nossos FlyBots responsáveis por orquestrar todo nosso Devops, inicia o processo de criação de um container com a Stack Z-API na Oracle Cloud.
Sim! Todos nossos serviços são nacionais e rodam na Oracle Cloud.
# Dados da instância
Source: https://developer.z-api.io/instance/me
GET /instances/{instanceId}/token/{token}/me
Retorna os dados e configurações da instância
## Conceituação
Este método retorna os dados e configurações da sua instância.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
***
## Response
### 200
Id da instância
Token da instância
Nome da instância
Timestamp com a data de vencimento da instância (unix timestamp)
Define se a instância está conectada
Define o status de pagamento da instância
Data de criação da instância
URL do webhook de conexão
URL do webhook de envio de mensagem
URL do webhook de desconexão
URL do webhook de status da mensagem
URL do webhook de presença do chat
URL do webhook de recebimento
Define se irá receber webhook das mensagens enviadas pela própria instância
Define se irá rejeitar uma chamada recebida automaticamente
Mensagem a ser enviada quando rejeitar uma chamada
Define se irá marcar as mensagens recebidas como lidas automaticamente
URL do webhook de dados iniciais após conexão
URL do proxy configurado na instância
Define se a instância está utilizando o proxy configurado
Define se a instância com o recurso de proteção anti-golpe em grupos de avisos ativa.
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"id": "123456",
"token": "abcdef-ghij-klmn-opqr",
"name": "Minha instância",
"due": 1700000000,
"connected": true,
"paymentStatus": "ACTIVE",
"created": "2024-01-01T00:00:00.000Z",
"connectedCallbackUrl": "https://meusite.com/webhook/connected",
"deliveryCallbackUrl": "https://meusite.com/webhook/delivery",
"disconnectedCallbackUrl": "https://meusite.com/webhook/disconnected",
"messageStatusCallbackUrl": "https://meusite.com/webhook/message-status",
"presenceChatCallbackUrl": "https://meusite.com/webhook/presence",
"receivedCallbackUrl": "https://meusite.com/webhook/received",
"receiveCallbackSentByMe": false,
"callRejectAuto": false,
"callRejectMessage": "",
"autoReadMessage": false,
"initialDataCallbackUrl": "",
"proxyUrl": "socks5://user:senha123@localhost:1080",
"useProxy": true,
"announcementGuard": true
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Concluir o Challenge
Source: https://developer.z-api.io/instance/passkey-prologue
POST /instances/{instanceId}/token/{token}/passkey-prologue
Envia o resultado da resolução do passkey (assertion WebAuthn) para concluir a conexão da instância
## Conceituação
Em alguns dispositivos, o WhatsApp passou a exigir uma verificação adicional ao tentar conectar ao WhatsApp, chamada de **[Chave de Acesso (Passkey)](/tips/extension-guide)**. Devido a isso, tais dispositivos, quando tentarem ler o QR Code podem receber o retorno do **Challenge**.
Este método faz parte do fluxo de conexão da instância via **[Passkey (WebAuthn)](/tips/extension-guide)**, sendo a etapa final desse processo:
1. O endpoint de QR Code é chamado e retorna um `challenge`.
2. Esse challenge é resolvido no dispositivo / [autenticador](/tips/extension-guide) (procedimento feito fora do Z-API, e que não depende da nossa API).
3. O resultado dessa resolução (a **assertion WebAuthn**) é enviado para este endpoint, para que a instância conclua a conexão.
A resolução do challenge acontece diretamente entre o dispositivo do usuário e o autenticador (Passkey), fora do ecossistema Z-API. Este endpoint apenas recebe o resultado já processado.
Pensando nessa nova autenticação do WhatsApp, o Z-API criou uma extensão chamada **[Z-API Connector](/tips/extension-guide)**, justamente para facilitar essa validação da Chave de Acesso.
***
## Atributos
### Obrigatórios
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Obrigatórios
Identificador da credencial gerada pelo autenticador
Identificador bruto (raw) da credencial
Tipo da credencial. Sempre "public-key"
Dados da assinatura WebAuthn retornados pelo autenticador
Dados do autenticador, codificados em base64
Dados do cliente relativos à assertion, codificados em base64
Assinatura gerada pelo autenticador, codificada em base64
Identificador do usuário associado à credencial, quando aplicável
### Opcionais
Extensões do cliente retornadas pelo autenticador
Métodos de verificação de usuário utilizados durante a assertion
***
## Request Body
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"id": "...",
"rawId": "...",
"type": "public-key",
"response": {
"authenticatorData": "...",
"clientDataJSON": "...",
"signature": "...",
"userHandle": null
},
"clientExtensionResults": { "uvm": [] }
}
```
***
## Response
### 200
Retorna o resultado do processamento da assertion pelo middleware da instância. Existem três variações possíveis:
**Sucesso:**
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{ "success": true }
```
**Falha — campos obrigatórios ausentes:**
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{ "success": false, "reason": "assertion (rawId + response) is required" }
```
**Falha — tipo de campo inválido:**
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{ "success": false, "reason": "assertion fields must be strings" }
```
Respostas com `success: false` indicam que o payload da assertion está malformado — é necessário corrigir o corpo enviado e reenviar. Não se trata de um erro de infraestrutura do Z-API.
### 400
Retornado nos seguintes casos:
* **Instância não encontrada** para o par `instanceId` + `token`:
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{ "error": "Instance not found", "value": null }
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Conectar com telefone
Source: https://developer.z-api.io/instance/phone-code
GET /instances/{instanceId}/token/{token}/phone-code/{phone}
Conecta à instância usando número de telefone ao invés do QRCode
## Conceituação
Permite a conexão sem a necessidade de escanear o QRCode, utilizando o recurso "Conectar com número de telefone".
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Path
Número de telefone com DDI (ex: 5511999999999)
***
## Response
### 200
O endpoint pode retornar o código de conexão padrão ou, em dispositivos que exigem a **[Chave de Acesso](/tips/extension-guide)**, retornar o objeto Challenge para dar continuidade ao processo de autenticação.
**Exemplo de retorno do código de conexão**
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"value": "A1B2C3D4E5"
}
```
**Exemplo de retorno para dispositivos que precisam da [Chave de Acesso](/tips/extension-guide)**
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"challenge": {
"allowCredentials": [],
"challenge": "V275tRcRUu2XjHiF9a6GTKFaZj8G4W_EEuRwdW5zCAM",
"extensions": {
"uvm": true
},
"rpId": "whatsapp.com",
"timeout": 600000,
"userVerification": "required"
}
}
```
Em casos desse retorno, é necessário concluir a autenticação que foi solicitada por meio do Challenge, para isso temos o endpoint para **[Concluir o Challenge](/instance/passkey-prologue)**
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
# Atualizar descrição do perfil
Source: https://developer.z-api.io/instance/profile-description
PUT /instances/{instanceId}/token/{token}/profile-description
Altera a descrição do perfil do WhatsApp conectado à instância
## Conceituação
Este método é responsável por alterar a sua descrição de perfil no WhatsApp.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Body
Descrição do perfil
***
## Request Body
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"value": "Descrição do perfil"
}
```
***
## Response
### 200
`true` caso tenha dado certo e `false` em caso de falha
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"value": true
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou PUT conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Atualizar nome do perfil
Source: https://developer.z-api.io/instance/profile-name
PUT /instances/{instanceId}/token/{token}/profile-name
Altera o nome do perfil do WhatsApp conectado à instância
## Conceituação
Este método é responsável por alterar o nome do seu perfil no WhatsApp.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Body
Nome do perfil
***
## Request Body
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"value": "Nome do perfil"
}
```
***
## Response
### 200
`true` caso tenha dado certo e `false` em caso de falha
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"value": true
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou PUT conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Atualizar imagem de perfil
Source: https://developer.z-api.io/instance/profile-picture
PUT /instances/{instanceId}/token/{token}/profile-picture
Altera a imagem de perfil do WhatsApp conectado à instância
## Conceituação
Este método é responsável por alterar a sua imagem de perfil no WhatsApp.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Body
URL da imagem
***
## Request Body
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"value": "https://exemplo.com/imagem.jpg"
}
```
***
## Response
### 200
`true` caso tenha dado certo e `false` em caso de falha
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"value": true
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou PUT conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# QRCode em bytes
Source: https://developer.z-api.io/instance/qr-code
GET /instances/{instanceId}/token/{token}/qr-code
Retorna os bytes do QRCode para renderização
## Conceituação
Retorna os bytes do QRCode para que você renderize em um componente compatível.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
***
## Response
### 200
Pode ser retornado o QR Code em bytes ou, em dispositivos que solicitam a **[Chave de Acesso](/tips/extension-guide)**, o objeto **Challenge** para dar continuidade ao processo de autenticação.
**Exemplo de retorno do bytes do QR Code**
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"value": "data:image/png;base64,iVBOR..."
}
```
**Exemplo de retorno para dispositivos que precisam da [Chave de Acesso](/tips/extension-guide)**
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"challenge": {
"allowCredentials": [],
"challenge": "V275tRcRUu2XjHiF9a6GTKFaZj8G4W_EEuRwdW5zCAM",
"extensions": {
"uvm": true
},
"rpId": "whatsapp.com",
"timeout": 600000,
"userVerification": "required"
}
}
```
Em casos desse retorno, é necessário concluir a autenticação que foi solicitada por meio do Challenge, para isso temos o endpoint para **[Concluir o Challenge](/instance/passkey-prologue)**
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# QRCode em imagem
Source: https://developer.z-api.io/instance/qr-code-image
GET /instances/{instanceId}/token/{token}/qr-code/image
Retorna o QRCode em formato de imagem base64
## Conceituação
Retorna o QRCode em formato de imagem base64, para que você exiba em um componente de imagem.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
***
## Response
### 200
Pode ser retornada a imagem do QR Code em Base64 ou, em dispositivos que solicitam a **[Chave de Acesso](/tips/extension-guide)**, o objeto **Challenge** para dar continuidade ao processo de autenticação.
**Exemplo de retorno para dispositivos que precisam da [Chave de Acesso](/tips/extension-guide)**
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"challenge": {
"allowCredentials": [],
"challenge": "V275tRcRUu2XjHiF9a6GTKFaZj8G4W_EEuRwdW5zCAM",
"extensions": {
"uvm": true
},
"rpId": "whatsapp.com",
"timeout": 600000,
"userVerification": "required"
}
}
```
Em casos desse retorno, é necessário concluir a autenticação que foi solicitada por meio do Challenge, para isso temos o endpoint para **[Concluir o Challenge](/instance/passkey-prologue)**
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
# Pegar QRCode
Source: https://developer.z-api.io/instance/qrcode
Obtenha o QRCode para conectar seu WhatsApp à instância
## Conceituação
Assim como no WhatsApp Web para se conectar à Z-API é necessário ler um QRCode ou informar um número de telefone. Você pode fazer isso de duas formas:
* Se conectar através do nosso painel de administrador
* Disponibilizar a experiência dentro da sua própria aplicação
Devido a novas atualizações feitas no WhatsApp, em alguns dispositivos, o WhatsApp passou a exigir uma verificação adicional ao tentar conectar ao WhatsApp, que seria a **[Chave de Acesso](/tips/extension-guide)**. Após a leitura do QR Code, poderá ser retornado um **[Challange](/instance/passkey-prologue)** para ser resolvido e finalizar a conexão.
Crie um método com intervalos entre 10 e 20 segundos para chamar a API e pegar o novo QRCode. Caso o usuário não leia o QRCode após 3 chamadas, interrompa o fluxo e exiba um botão para o usuário solicitar um novo QRCode. Isso evita chamadas desnecessárias ao WhatsApp.
WhatsApp invalida o QRCode a cada 20 segundos. Caso já esteja autenticado, a conexão irá falhar. Após a conexão, os métodos da Z-API estarão disponíveis.
# Renomear instância
Source: https://developer.z-api.io/instance/rename-instance
PUT /instances/{instanceId}/token/{token}/update-name
Renomeia uma instância na Z-API
## Conceituação
Método utilizado para renomear uma instância.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Body
Novo nome para a instância
***
## Request Body
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"value": "novo nome"
}
```
***
## Response
### 200
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"value": true
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou PUT conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Resetar o Challenge
Source: https://developer.z-api.io/instance/reset-passkey-challenge
POST /instances/{instanceId}/token/{token}/reset-passkey-challenge
Reseta o challenge de passkey vigente, permitindo a geração de um novo QR Code
## Conceituação
Em alguns dispositivos, o WhatsApp passou a exigir uma verificação adicional ao tentar conectar ao WhatsApp Web, chamada de **[Chave de Acesso (Passkey)](/tips/extension-guide)**. Devido a isso, esses dispositivos que tentar ler o QR Code via API podem ter o retorno do **Challenge**.
Este método faz parte do fluxo de conexão da instância via **Passkey (WebAuthn)**. Ele é utilizado quando o cliente deseja gerar um **novo** QR Code — por exemplo, para escanear com outro dispositivo.
Ao chamar este endpoint, o challenge atual é **resetado**. Na próxima chamada ao endpoint de **QR Code**, um novo QR Code é gerado.
Este endpoint invalida o fluxo de passkey vigente. Após o sucesso da chamada, é necessário chamar novamente o endpoint de **qr-code** para obter o novo QR Code.
***
## Atributos
### Obrigatórios
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
***
## Response
### 200
Retorna o resultado do processamento da instância. Existem duas variações possíveis:
**Sucesso — challenge resetado:**
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{ "success": true }
```
**Falha — não foi possível reiniciar a instância:**
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{ "success": false, "error": "Failed to restart instance after challenge reset" }
```
Em caso de sucesso, chame novamente o endpoint de **qr-code** para obter o novo QR Code.
### 400
Retornado nos seguintes casos:
* **Instância não encontrada** para o par `instanceId` + `token`:
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{ "error": "Instance not found", "value": null }
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Reiniciar instância
Source: https://developer.z-api.io/instance/restart
GET /instances/{instanceId}/token/{token}/restart
Reinicia a instância conectada à Z-API
## Conceituação
Se você como todo bom Dev pulou a introdução e ainda não tem bem claro o conceito de instância, sugiro fortemente que você dê um passo atrás e leia a [introdução deste tópico](/instance/introduction).
Esse recurso funciona como o botão de reiniciar do seu sistema operacional, útil para solucionar eventuais problemas.
Não! Você não precisa ler o QRCode se reiniciar a sua instância.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
***
## Response
### 200
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"value": true
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Status da instância
Source: https://developer.z-api.io/instance/status
GET /instances/{instanceId}/token/{token}/status
Verifica se a instância está conectada a uma conta de WhatsApp
## Conceituação
Este método te permite descobrir se sua instância está ou não conectada a uma conta de WhatsApp.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
***
## Response
### 200
Indica se seu número está conectado ao Z-API
Retorna detalhes do status, como "You are already connected", "You need to restore the session" ou "You are not connected"
Indica se o celular está conectado à internet
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"connected": true,
"error": "You are already connected",
"smartphoneConnected": true
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Ativar Proteção de Grupo de Avisos
Source: https://developer.z-api.io/instance/update-announcement-guard
PUT /instances/{instanceId}/token/{token}/update-announcement-guard
Proteja seus grupos de avisos contra mensagens de golpe, removendo automaticamente conteúdos enviados por participantes que não são administradores e recebendo os dados do autor via webhook.
Observações sobre este endpoint
* Funciona apenas em grupos de avisos onde a instância é administradora.
* Ignora administradores.
* Cada mensagem gera um evento no webhook.
* O autor não é removido automaticamente.
## Conceituação
A Proteção Anti-Golpe em Grupos de Avisos remove automaticamente, para todos os participantes, as mensagens enviadas por golpistas — ou seja, participantes que não são administradores — em grupos de avisos de comunidades, nos quais apenas administradores podem enviar mensagens. Sempre que uma mensagem é removida, você recebe um evento no webhook contendo os dados do autor. Assim, sua aplicação pode identificar o responsável e tomar as medidas necessárias, como removê-lo do grupo.
## Atributos
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Headers
| Header | Valor |
| :- | :- |
| `Client-Token` | Token de segurança da conta |
| `Content-Type` | `application/json` |
### Request Body
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"value": true
}
```
Valor que liga a proteção, TRUE ativa e FALSE desativa (Padrão = FALSE)
## Response
### 200
É retornado com o status informado na requisição (TRUE or FALSE)
# Leitura automática
Source: https://developer.z-api.io/instance/update-auto-read-message
PUT /instances/{instanceId}/token/{token}/update-auto-read-message
Ativa ou desativa a leitura automática de todas as mensagens recebidas pela API
## Conceituação
Esse método ativa a leitura automática de todas as mensagens recebidas pela API.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Body
`true` para ativar a leitura automática ou `false` para desativar
***
## Request Body
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"value": true
}
```
***
## Response
### 200
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"value": true
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou PUT conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Leitura automática de status
Source: https://developer.z-api.io/instance/update-auto-read-status
PUT /instances/{instanceId}/token/{token}/update-auto-read-status
Ativa ou desativa a leitura automática de todas as publicações de status recebidas pela API
## Conceituação
Esse método ativa a leitura automática de todas as publicações de status recebidas pela API.
Para que funcione você deve ter a **Leitura automática** habilitada.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Body
`true` para ativar a leitura automática de status ou `false` para desativar
***
## Request Body
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"value": true
}
```
***
## Response
### 200
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"value": true
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou PUT conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Rejeitar chamadas
Source: https://developer.z-api.io/instance/update-call-reject-auto
PUT /instances/{instanceId}/token/{token}/update-call-reject-auto
Ativa ou desativa a rejeição automática de chamadas de voz recebidas pela API
## Conceituação
Esse método ativa a opção de Rejeitar chamadas automático na sua API, com ela ativa todas as chamadas de voz recebidas pelo número conectado a API serão rejeitadas de forma automática.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Body
`true` para ativar a rejeição automática de chamadas ou `false` para desativar
***
## Request Body
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"value": true
}
```
***
## Response
### 200
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"value": true
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou PUT conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Mensagem de ligação
Source: https://developer.z-api.io/instance/update-call-reject-message
PUT /instances/{instanceId}/token/{token}/update-call-reject-message
Define a mensagem enviada após rejeitar automaticamente uma chamada de voz
## Conceituação
Através desse método você define a mensagem que será enviada após rejeitar a chamada de voz recebida pela API.
Para a mensagem ser enviada o método anterior ([Rejeitar chamadas](/instance/update-call-reject-auto)) precisa estar ativo!
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Body
Mensagem de resposta
***
## Request Body
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"value": "Mensagem de resposta"
}
```
***
## Response
### 200
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"value": true
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou PUT conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Como conectar
Source: https://developer.z-api.io/mcp/how-to-connect
Conecte sua conta Z-API ao servidor MCP e autorize seu app de IA
O servidor MCP da Z-API pode ser conectado a qualquer aplicativo de IA compatível com MCP (Claude, ChatGPT, agentes customizados, entre outros). O processo é sempre parecido: adicionar o servidor como um conector/ferramenta personalizada e autorizar o acesso à sua instância.
Abaixo mostramos o passo a passo usando o **Claude** como exemplo, por ser um dos apps de IA mais usados — mas a lógica é a mesma em qualquer cliente MCP.
### 1. Abra as configurações de Conectores
No Claude, vá em **Configurações → Conectores**. Clique no menu **Adicionar**, no canto superior direito, e selecione **Adicionar conector personalizado**.
### 2. Preencha nome e URL do servidor
Na janela **Adicionar conector personalizado**, informe:
* **Nome**: o nome que você preferir — usamos `Z-API` apenas como sugestão para facilitar a identificação depois
* **URL do servidor MCP**: `https://mcp.z-api.io/mcp`
Clique em **Adicionar**. O conector Z-API aparecerá na lista de conectores, ainda como **não conectado**.
### 3. Vincule sua instância
Abra o conector **Z-API** na lista e clique em **Vincular**.
Isso abre uma aba do navegador para autorizar a conexão. Você precisa estar **logado na plataforma da Z-API** para prosseguir — caso ainda não esteja, será solicitado o login antes de exibir a lista de instâncias.
Escolha qual **instância** da sua conta Z-API deseja autorizar. Localize a instância desejada na lista (você pode usar a busca) e clique em **Selecionar**.
Se a instância selecionada estiver **desconectada do WhatsApp** (sem o QR Code lido), vincular o conector MCP não conecta o WhatsApp automaticamente. Você ainda precisa acessar o painel da Z-API e ler o QR Code normalmente, para colocar a instância online.
Depois de selecionar a instância, confirme em **Abrir Claude** (ou **Abrir aplicativo para desktop**, caso esteja usando o app desktop) para retornar automaticamente ao Claude.
### 4. Pronto para usar
Ao selecionar a instância, a conexão é estabelecida automaticamente, disponibilizando todos os endpoints da Z-API compatíveis com o MCP, como envio de mensagens de texto, imagens, vídeos, gerenciamento de grupos e demais funcionalidades atualmente suportadas, para uso direto pelo Claude.
Para usar o conector em uma conversa, clique no ícone **+** ao lado do campo de mensagem, vá em **Conectores** e ative o toggle da **Z-API**.
Pronto! Agora a IA já está conectada à sua instância Z-API. Basta pedir, em linguagem natural, que ela envie uma mensagem, uma imagem, crie um grupo ou execute qualquer uma das ações disponíveis — ela vai identificar a ferramenta certa e fazer a requisição por você.
Depois de conectado, o app de IA passa a aparecer na aba **Apps conectados**, dentro do painel da instância na Z-API. É por lá que você pode acompanhar quando foi conectado, o último uso e remover o acesso quando quiser.
***
## Autenticação
A conexão é feita via **OAuth**, vinculando a instância Z-API escolhida diretamente ao conector no seu app de IA. A IA nunca acessa senha ou credenciais do WhatsApp diretamente — apenas os endpoints autorizados da instância selecionada.
Desconectar o **WhatsApp** da instância (ler o QR Code novamente) **não revoga** automaticamente o acesso do app de IA. As duas conexões são independentes.
Para revogar o acesso da IA, vá até a aba **Apps conectados** no painel da sua instância Z-API e remova o app por lá — isso encerra o acesso imediatamente, sem precisar mexer nas configurações do app de IA.
***
## Perguntas frequentes
Não. São duas conexões independentes. Desconectar o WhatsApp da instância não remove o app de IA nem revoga sua autorização — o acesso continua ativo até que você o remova manualmente na aba **Apps conectados**, no painel da instância.
Acesse o painel da sua instância na Z-API, vá até a aba **Apps conectados** e remova o app desejado por lá. Isso encerra o acesso imediatamente, sem afetar a conexão do WhatsApp.
**(1)** O conector Z-API está ativado para essa conversa? **(2)** A instância selecionada está conectada e ativa no painel da Z-API? **(3)** A vinculação/token expirou? Se sim, desvincule e vincule novamente o conector nas configurações do app de IA. Persistindo, acione o suporte técnico.
Não. Depois de adicionado e vinculado uma vez, o conector fica disponível para ser ativado em qualquer conversa nova através do menu de conectores.
# Introdução
Source: https://developer.z-api.io/mcp/introduction
Conecte sua IA ao WhatsApp usando o servidor MCP da Z-API
## O que é o MCP Z-API?
O MCP Z-API é um servidor que expõe operações do WhatsApp como ferramentas prontas para qualquer IA compatível com MCP — Claude, ChatGPT, agentes customizados, entre outros.
Em vez de chamar a API REST diretamente, a IA conversa com o servidor MCP e ele executa as ações na sua instância Z-API.
**Novo no MCP?** MCP (Model Context Protocol) é um padrão aberto que define como IAs se conectam a sistemas externos. Funciona como um "menu de habilidades": a IA pergunta o que o servidor sabe fazer, escolhe a ação e envia os dados necessários.
***
## O que dá pra fazer
Hoje o MCP Z-API expõe 9 ferramentas, divididas em dois grupos:
### Mensagens
| Ferramenta | O que faz |
| - | - |
| **Send-text** | Envia uma mensagem de texto para um número ou grupo |
| **Send-image** | Envia uma imagem (link ou Base64), com legenda opcional |
| **Send-video** | Envia um vídeo (link ou Base64), com legenda opcional |
### Grupos
| Ferramenta | O que faz |
| - | - |
| **Group-create** | Cria um novo grupo com os participantes informados |
| **Group-add-participant** | Adiciona novos membros a um grupo existente |
| **Group-remove-participant** | Remove membros de um grupo |
| **Group-add-admin** | Promove um ou mais participantes a administradores do grupo |
| **Group-remove-admin** | Remove a administração de um ou mais membros do grupo |
| **Group-metadata** | Retorna as informações do grupo (nome, participantes, admins, etc.) |
Novas ferramentas são adicionadas conforme o servidor evolui.
Ações sobre grupos e participantes têm efeito imediato no WhatsApp. Como qualquer ação executada por uma IA, revise o que o agente vai fazer antes de autorizar, principalmente em fluxos automatizados.
***
## Como funciona na prática
```
Usuário faz um pedido à IA
│
▼
IA consulta o MCP Z-API → recebe a lista de ferramentas disponíveis
│
▼
IA escolhe a ferramenta e envia os parâmetros (ex.: número + mensagem)
│
▼
MCP valida o token OAuth e aciona a Z-API
│
▼
Ação executada no WhatsApp → IA confirma ao usuário ✅
```
***
## Perguntas frequentes
Sim. O MCP é uma camada sobre a Z-API, não um substituto. A instância de WhatsApp precisa estar conectada normalmente na plataforma.
Do número conectado à instância Z-API do cliente — igual a qualquer envio pela API tradicional.
Sim. Hoje já é possível criar grupos, adicionar e remover participantes, e promover ou remover administradores diretamente pelas ferramentas do MCP.
# Deletar mensagens
Source: https://developer.z-api.io/message/delete-message
DELETE /instances/{instanceId}/token/{token}/messages
Apaga uma mensagem enviada ou recebida em um chat
## Conceituação
Método utilizado para apagar uma mensagem em um chat, você pode deletar tanto uma mensagem que enviou quanto uma mensagem enviada por um contato, para utilizar este recurso você só vai precisar do messageId da mensagem que quer apagar.
#### Exemplo no WhatsApp
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Query Parameters
ID original da mensagem
Telefone (ou ID do grupo para casos de envio para grupos) do destinatário/remetente no formato DDI DDD NÚMERO. Ex: 551199999999
Informe `true` caso você tenha enviado a mensagem ou `false` para casos onde seja uma mensagem recebida
Informe `true` para apagar a mensagem apenas para você ("Apagar para mim"), mantendo-a visível para o destinatário. Caso não seja informado ou seja `false`, a mensagem será apagada para todos.
## Exemplo de requisição
### URL exemplo
```bash theme={"theme":{"light":"github-light","dark":"poimandres"}}
DELETE https://api.z-api.io/instances/{instanceId}/token/{instanceToken}/messages?messageId=123&phone=5511999998888&owner=true
```
### Excluindo apenas para mim
Para excluir a mensagem apenas "para mim", basta adicionar o parâmetro `deleteForMe` na requisição do endpoint de deletar mensagem.
```bash theme={"theme":{"light":"github-light","dark":"poimandres"}}
DELETE https://api.z-api.io/instances/{instanceId}/token/{instanceToken}/messages?messageId=123&phone=5511999998888&owner=true&deleteForMe=true
```
***
## Response
### 200
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"value": true
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o DELETE conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Reencaminhar mensagem
Source: https://developer.z-api.io/message/forward-message
POST /instances/{instanceId}/token/{token}/forward-message
Reencaminha uma mensagem para um contato ou grupo
## Conceituação
Simples e objetivo, neste método você poderá reencaminhar as mensagens através da api precisando apenas do messageId da mensagem que deseja encaminhar, e o phone do chat onde esse messageId se encontra.
Para utilizar esse método é necessário configurar o webhook, caso ainda não tenha configurado, a mensagem não será reencaminhada.
#### Exemplo no WhatsApp
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Obrigatórios
Telefone (ou ID do grupo para casos de envio para grupos) do destinatário no formato DDI DDD NÚMERO. Ex: 551199999999
ID da mensagem que vai ser reencaminhada
Número do chat onde o messageId se encontra
### Opcionais
Delay adicionado na mensagem. Você pode decidir entre um range de 1 a 15 sec, significa quantos segundos ele vai esperar para enviar a próxima mensagem. (Ex.: "delayMessage": 5). O delay default caso não seja informado é de 1 a 3 sec
***
## Request Body
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"phone": "5511999999999",
"messageId": "3999984263738042930CD6ECDE9VDWSA",
"messagePhone": "5511888888888"
}
```
***
## Response
### 200
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"zaapId": "3999984263738042930CD6ECDE9VDWSA",
"messageId": "D241XXXX732339502B68",
"id": "D241XXXX732339502B68"
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Introdução
Source: https://developer.z-api.io/message/introduction
Entenda como funcionam as mensagens na Z-API
## Conceituação
Primeiramente, o que você precisa entender sobre as mensagens é que elas podem ser enviadas para um contato, um grupo ou lista de transmissão.
No tópico "contatos" vou voltar a relatar sobre isso, mas é importante você também saber que para o WhatsApp tudo é um chat, seja um contato, grupo ou uma lista de transmissão.
Para enviar qualquer mensagem ele precisa de ID do chat, sendo eles:
* Para **contatos** é o próprio número;
* Para **grupos** é a concatenação do número do fundador do grupo com um timestamp;
* Para **listas de transmissão** é a concatenação da string 'broadcast' com o timestamp.
Esses IDs são todos retornados pelo método get/chats, que você irá conhecer um pouco mais a frente.
Falando em ID, recomendamos fortemente que você armazene em sua aplicação o **messageId** que nosso response irá retornar, pois caso precise responder, marcar ou mesmo deletar uma mensagem, você precisará informar o messageId como atributo no método.
***
## Response padrão
Toda mensagem enviada com sucesso retorna os seguintes atributos:
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"zaapId": "3999984263738042930CD6ECDE9VDWSA",
"messageId": "D241XXXX732339502B68",
"id": "D241XXXX732339502B68"
}
```
***
## Formatação de texto
Você pode formatar seus textos, enviando caracteres de formatação e deixar sua mensagem mais elegante.
| Formato | Sintaxe | Exemplo |
| - | - | - |
| Negrito | `*texto*` | **texto** |
| Itálico | `_texto_` | *texto* |
| Tachado | `~texto~` | ~~texto~~ |
| Monoespaçado | ` ```texto``` ` | `texto` |
# Ler mensagens
Source: https://developer.z-api.io/message/read-message
POST /instances/{instanceId}/token/{token}/read-message
Marca uma mensagem em um chat como lida
## Conceituação
Método utilizado para marcar uma mensagem em um chat como lida.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Obrigatórios
Telefone (ou ID do grupo para casos de envio para grupos) do destinatário/remetente no formato DDI DDD NÚMERO. Ex: 551199999999. **IMPORTANTE** Envie somente números, sem formatação ou máscara
ID original da mensagem. No caso de mensagem enviada por você é o código que vem no seu response, caso seja uma mensagem enviada por um contato você vai receber este messageId pelo seu webhook de receive
***
## Request Body
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"phone": "5511999998888",
"messageId": "3999984263738042930CD6ECDE9VDWSA"
}
```
***
## Response
### 200
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"value": true
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Responder mensagem
Source: https://developer.z-api.io/message/reply-message
POST /instances/{instanceId}/token/{token}/send-text
Responde diretamente uma mensagem em um chat
## Conceituação
Nesse tópico falaremos um pouco sobre como responder uma mensagem diretamente! Quando você utiliza o método send-text existe um atributo opcional chamado messageId, esse é um atributo que recebe o Id de uma mensagem qualquer, quando esse atributo é passado, sua mensagem será diretamente relacionada a mensagem do Id informado.
#### Exemplo no WhatsApp
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Obrigatórios
Telefone (ou ID do grupo para casos de envio para grupos) do destinatário no formato DDI DDD NÚMERO. Ex: 551199999999
Texto a ser enviado
ID original da mensagem que deseja responder
### Opcionais
Delay adicionado na mensagem. Você pode decidir entre um range de 1 a 15 sec, significa quantos segundos ele vai esperar para enviar a próxima mensagem. (Ex.: "delayMessage": 5). O delay default caso não seja informado é de 1 a 3 sec
No caso de uma mensagem de grupo, define se a resposta será enviada para o grupo ou no particular do remetente (não pode ser você mesmo)
***
## Request Body
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"phone": "5511999999999",
"message": "Welcome to *Z-API*",
"messageId": "3999984263738042930CD6ECDE9VDWSA"
}
```
***
## Response
### 200
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"zaapId": "3999984263738042930CD6ECDE9VDWSA",
"messageId": "D241XXXX732339502B68",
"id": "D241XXXX732339502B68"
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Enviar botões de ação
Source: https://developer.z-api.io/message/send-button-actions
POST /instances/{instanceId}/token/{token}/send-button-actions
Envia uma mensagem com botões de ação (link, ligação ou resposta)
## Conceituação
Neste método você poderá enviar mensagens de texto com botões de ação que redirecionam para links, iniciam chamadas ou fornecem respostas padrão.
Envios de botões atualmente se encontram disponíveis, porém possui alguns fatores decisivos para o funcionamento. Consulte o tópico [status dos botões](/tips/button-status) para mais informações.
**ATENÇÃO**
Ao enviar os três tipos de botões simultaneamente, o WhatsApp Web gera um erro. Combine botões CALL e URL juntos, e envie botões REPLY separadamente.
***
#### Exemplo no WhatsApp
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Obrigatórios
Telefone (ou ID do grupo para casos de envio para grupos) do destinatário no formato DDI DDD NÚMERO. Ex: 551199999999
Texto da mensagem
Array de botões de ação
Identificador do botão
Tipo do botão: `CALL`, `URL` ou `REPLY`
Texto exibido no botão
Número de telefone (obrigatório para tipo CALL)
URL do link (obrigatório para tipo URL, deve começar com http\:// ou https\://).
**Dica:** O WhatsApp possui um link específico para copiar textos. Passando esse link no atributo `url`, o seu botão passa a ser um botão de copiar: `https://www.whatsapp.com/otp/code/?otp_type=COPY_CODE&code=otpseucodigo`
### Opcionais
Título da mensagem
Rodapé da mensagem
Link da imagem ou seu Base64
***
## Request Body
**Botões CALL e URL (juntos):**
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"phone": "551199999999",
"message": "uma mensagem",
"title": "se quiser vincular um titulo",
"footer": "se quiser vincular um rodape top",
"image": "https://app.z-api.io/logos/zapi-dark.png",
"buttonActions": [
{
"id": "1",
"type": "CALL",
"phone": "554498398733",
"label": "Fale conosco"
},
{
"id": "2",
"type": "URL",
"url": "https://z-api.io",
"label": "Visite nosso site"
}
]
}
```
**Botão REPLY (separado):**
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"phone": "551199999999",
"message": "uma mensagem",
"title": "se quiser vincular um titulo",
"footer": "se quiser vincular um rodape top",
"image": "https://app.z-api.io/logos/zapi-dark.png",
"buttonActions": [
{
"id": "3",
"type": "REPLY",
"label": "Falar com atendente"
}
]
}
```
***
## Response
### 200
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"zaapId": "3999984263738042930CD6ECDE9VDWSA",
"messageId": "D241XXXX732339502B68",
"id": "D241XXXX732339502B68"
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Enviar lista de botões
Source: https://developer.z-api.io/message/send-button-list
POST /instances/{instanceId}/token/{token}/send-button-list
Envia uma mensagem com botões de resposta rápida
## Conceituação
Neste método você poderá enviar mensagens de texto com botões de ação, o conteúdo do botão ex: SIM / Não, poderão ser escolhidos pelo usuário.
Envios de botões atualmente se encontram disponíveis, porém possui alguns fatores decisivos para o funcionamento. Para mais detalhes acesse o tópico [Funcionamento dos Botões](/tips/button-status).
O atributo **message** não pode ser enviado vazio!
#### Exemplo no WhatsApp
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Obrigatórios
Telefone (ou ID do grupo para casos de envio para grupos) do destinatário no formato DDI DDD NÚMERO. Ex: 551199999999
Texto a ser enviado
Objeto com a lista de botões
Array de botões
Texto para o botão
Identificador do botão
### Opcionais
Delay adicionado na mensagem. Você pode decidir entre um range de 1 a 15 sec, significa quantos segundos ele vai esperar para enviar a próxima mensagem. (Ex.: "delayMessage": 5). O delay default caso não seja informado é de 1 a 3 sec
***
## Request Body
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"phone": "5511999999999",
"message": "Z-API é Bom ?",
"buttonList": {
"buttons": [
{
"id": "1",
"label": "Ótimo"
},
{
"id": "2",
"label": "Excelente"
}
]
}
}
```
***
## Response
### 200
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"zaapId": "3999984263738042930CD6ECDE9VDWSA",
"messageId": "D241XXXX732339502B68",
"id": "D241XXXX732339502B68"
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Enviar botões com imagem
Source: https://developer.z-api.io/message/send-button-list-image
POST /instances/{instanceId}/token/{token}/send-button-list
Envia uma imagem com botões de resposta rápida
## Conceituação
Neste método você poderá enviar imagens com opções de botões de ação, o conteúdo do botão ex: SIM / Não, poderão ser escolhidos pelo usuário.
Envios de botões atualmente se encontram disponíveis, porém possui alguns fatores decisivos para o funcionamento. Para mais detalhes acesse o tópico [Funcionamento dos Botões](/tips/button-status).
O atributo **message** não pode ser enviado vazio!
#### Exemplo no WhatsApp
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Obrigatórios
Telefone (ou ID do grupo para casos de envio para grupos) do destinatário no formato DDI DDD NÚMERO. Ex: 551199999999
Texto a ser enviado
Objeto com imagem e lista de botões
URL da imagem
Array de botões
Texto para o botão
Identificador do botão
### Opcionais
Delay adicionado na mensagem. Você pode decidir entre um range de 1 a 15 sec, significa quantos segundos ele vai esperar para enviar a próxima mensagem. (Ex.: "delayMessage": 5). O delay default caso não seja informado é de 1 a 3 sec
***
## Request Body
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"phone": "5511999999999",
"message": "Z-API é Bom ?",
"buttonList": {
"image": "https://avatars.githubusercontent.com/u/60630101?s=280&v=4",
"buttons": [
{
"id": "1",
"label": "Ótimo"
},
{
"id": "2",
"label": "Excelente"
}
]
}
}
```
***
## Response
### 200
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"zaapId": "3999984263738042930CD6ECDE9VDWSA",
"messageId": "D241XXXX732339502B68",
"id": "D241XXXX732339502B68"
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Enviar botões com vídeo
Source: https://developer.z-api.io/message/send-button-list-video
POST /instances/{instanceId}/token/{token}/send-button-list
Envia um vídeo com botões de resposta rápida
## Conceituação
Neste método você poderá enviar vídeos com opções de botões de ação, o conteúdo do botão ex: SIM / Não, poderão ser escolhidos pelo usuário e será utilizado como resposta da mensagem enviada junto com os botões.
Envios de botões atualmente se encontram disponíveis, porém possui alguns fatores decisivos para o funcionamento. Para mais detalhes acesse o tópico [Funcionamento dos Botões](/tips/button-status).
O atributo **message** não pode ser enviado vazio!
#### Exemplo no WhatsApp
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Obrigatórios
Telefone (ou ID do grupo para casos de envio para grupos) do destinatário no formato DDI DDD NÚMERO. Ex: 551199999999
Texto a ser enviado
Objeto com vídeo e lista de botões
URL do vídeo ou Base64
Array de botões
Texto para o botão
Identificador do botão
### Opcionais
Delay adicionado na mensagem. Você pode decidir entre um range de 1 a 15 sec, significa quantos segundos ele vai esperar para enviar a próxima mensagem. (Ex.: "delayMessage": 5). O delay default caso não seja informado é de 1 a 3 sec
***
## Request Body
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"phone": "5511999999999",
"message": "Z-API é Bom ?",
"buttonList": {
"video": "https://exemplo.com/video.mp4",
"buttons": [
{
"id": "1",
"label": "Ótimo"
},
{
"id": "2",
"label": "Excelente"
}
]
}
}
```
***
## Response
### 200
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"zaapId": "3999984263738042930CD6ECDE9VDWSA",
"messageId": "D241XXXX732339502B68",
"id": "D241XXXX732339502B68"
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Enviar botão OTP
Source: https://developer.z-api.io/message/send-button-otp
POST /instances/{instanceId}/token/{token}/send-button-otp
Envia uma mensagem com botão para copiar um valor
## Conceituação
Neste método você poderá enviar mensagens de texto com botão para copiar um valor.
Envios de botões atualmente se encontram disponíveis, porém possui alguns fatores decisivos para o funcionamento. Para mais detalhes acesse o tópico [Funcionamento dos Botões](/tips/button-status).
#### Exemplo no WhatsApp
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Obrigatórios
Telefone (ou ID do grupo para casos de envio para grupos) do destinatário no formato DDI DDD NÚMERO. Ex: 551199999999
Texto da mensagem
Valor a ser copiado ao clicar no botão
### Opcionais
URL ou Base64 da imagem
Texto do botão (padrão: "Copiar código")
***
## Request Body
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"phone": "551199999999",
"message": "Texto da mensagem",
"code": "Valor a ser copiado"
}
```
***
## Response
### 200
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"zaapId": "3999984263738042930CD6ECDE9VDWSA",
"messageId": "D241XXXX732339502B68",
"id": "D241XXXX732339502B68"
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Enviar botão PIX
Source: https://developer.z-api.io/message/send-button-pix
POST /instances/{instanceId}/token/{token}/send-button-pix
Envia uma mensagem com chave PIX e botão para copiar
## Conceituação
Neste método você poderá enviar mensagens de chave pix com botão para copiar.
Envios de botões atualmente se encontram disponíveis, porém possui alguns fatores decisivos para o funcionamento. Para mais detalhes acesse o tópico [Funcionamento dos Botões](/tips/button-status).
Mensagens PIX recebidas no WhatsApp Web não alteram o estado do chat — não marcam como não lido nem movem para o topo da lista. As mensagens são renderizadas normalmente. Isso é um bug do WhatsApp Web.
#### Exemplo no WhatsApp
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Obrigatórios
Telefone (ou ID do grupo para casos de envio para grupos) do destinatário no formato DDI DDD NÚMERO. Ex: 551199999999
Chave PIX
Tipo da chave: `CPF`, `CNPJ`, `PHONE`, `EMAIL` ou `EVP`
### Opcionais
Título do botão (padrão: "Pix")
***
## Request Body
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"phone": "551199999999",
"pixKey": "chave pix",
"type": "EVP"
}
```
***
## Response
### 200
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"zaapId": "3999984263738042930CD6ECDE9VDWSA",
"messageId": "D241XXXX732339502B68",
"id": "D241XXXX732339502B68"
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Enviar carrossel
Source: https://developer.z-api.io/message/send-carousel
POST /instances/{instanceId}/token/{token}/send-carousel
Envia uma mensagem de carrossel com imagens, texto e botões de ação
## Conceituação
Neste método você poderá enviar mensagens de carrossel com imagens, texto e com botões de ação. A partir dos botões de ação, você conseguirá redirecionar para links, fazer chamadas, e também dar respostas padrões.
#### Exemplo no WhatsApp
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Obrigatórios
Telefone (ou ID do grupo para casos de envio para grupos) do destinatário no formato DDI DDD NÚMERO. Ex: 551199999999
Texto da mensagem
Array de cartões do carrossel
Texto do cartão
URL da imagem do cartão
Array de botões de ação
Identificador do botão
Texto exibido no botão
Tipo do botão: `CALL`, `URL` ou `REPLY`
URL do link (para tipo URL)
Número de telefone (para tipo CALL)
### Opcionais
Delay adicionado na mensagem. Você pode decidir entre um range de 1 a 15 sec, significa quantos segundos ele vai esperar para enviar a próxima mensagem. (Ex.: "delayMessage": 5). O delay default caso não seja informado é de 1 a 3 sec
***
## Request Body
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"phone": "551199999999",
"message": "Texto da mensagem",
"carousel": [
{
"text": "Texto do cartão",
"image": "https://firebasestorage.googleapis.com/v0/b/zaap-messenger-web.appspot.com/o/logo.png?alt=media",
"buttons": [
{
"id": "1",
"label": "Nome do botão",
"url": "https://z-api.io",
"type": "URL"
},
{
"id": "2",
"label": "Nome do botão",
"type": "REPLY"
}
]
},
{
"text": "Texto do cartão",
"image": "https://firebasestorage.googleapis.com/v0/b/zaap-messenger-web.appspot.com/o/logo.png?alt=media",
"buttons": [
{
"id": "1",
"label": "Nome do botão",
"url": "https://z-api.io",
"type": "URL"
},
{
"id": "2",
"label": "Nome do botão",
"type": "REPLY"
}
]
}
]
}
```
***
## Response
### 200
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"zaapId": "3999984263738042930CD6ECDE9VDWSA",
"messageId": "D241XXXX732339502B68",
"id": "D241XXXX732339502B68"
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Editar evento
Source: https://developer.z-api.io/message/send-edit-event
POST /instances/{instanceId}/token/{token}/send-edit-event
Edita um evento existente em um grupo
## Conceituação
Neste método você poderá enviar mensagens de edição de Evento.
Para editar o evento, é necessário reenviar os dados que já estão configurados no evento, mesmo que eles não possuam alteração.
#### Exemplo no WhatsApp
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Obrigatórios
ID do grupo destinatário
ID da mensagem original do evento
Dados do evento
Nome do evento
Data e hora do evento (sem timezone)
Descrição do evento
Localização do evento
Nome do lugar
Tipo de chamada do evento: `voice` ou `video`
Define se o evento está cancelado
***
## Request Body
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"phone": "120363019502650977-group",
"eventMessageId": "3EB058359730B7C2895C55",
"event": {
"name": "Novo nome do evento",
"description": "Descrição do evento",
"dateTime": "2024-04-29T09:30:53.309Z",
"location": {
"name": "Nome do lugar"
},
"callLinkType": "voice",
"canceled": false
}
}
```
***
## Response
### 200
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"zaapId": "3999984263738042930CD6ECDE9VDWSA",
"messageId": "D241XXXX732339502B68",
"id": "D241XXXX732339502B68"
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Enviar evento
Source: https://developer.z-api.io/message/send-event
POST /instances/{instanceId}/token/{token}/send-event
Envia uma mensagem do tipo evento em um grupo
## Conceituação
Neste método você poderá enviar mensagens do tipo Evento.
Só é possível enviar esse tipo de mensagem para um **grupo**.
#### Exemplo no WhatsApp
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Obrigatórios
ID do grupo destinatário
Dados do evento
Nome do evento
Data e hora do evento (sem timezone). Ex: 2024-04-29T09:30:53.309Z
Descrição do evento
Fuso horário UTC do evento. Ex: UTC-3
Localização do evento
Nome do lugar
Tipo de chamada do evento: `voice` ou `video`
Define se o evento está cancelado
***
## Request Body
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"phone": "120363019502650977-group",
"event": {
"name": "Nome do evento",
"description": "Descrição do evento",
"dateTime": "2024-04-29T09:30:53.309Z",
"timeZone": "UTC-3",
"location": {
"name": "Nome do lugar"
},
"callLinkType": "voice",
"canceled": false
}
}
```
***
## Response
### 200
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"zaapId": "3999984263738042930CD6ECDE9VDWSA",
"messageId": "D241XXXX732339502B68",
"id": "D241XXXX732339502B68"
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Responder evento
Source: https://developer.z-api.io/message/send-event-response
POST /instances/{instanceId}/token/{token}/send-event-response
Envia uma resposta de presença a um evento
## Conceituação
Neste método você poderá enviar mensagens de resposta a um evento.
Não é possível responder a um evento que você mesmo criou. Sua resposta sempre será marcada como "presença confirmada".
#### Exemplo no WhatsApp
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Obrigatórios
ID do grupo destinatário
ID da mensagem original do evento
Resposta ao evento: `GOING` (vou) ou `NOT_GOING` (não vou)
***
## Request Body
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"phone": "120363019502650977-group",
"eventMessageId": "D2D612289D9E8F62307D72409A8D9DC3",
"eventResponse": "GOING"
}
```
***
## Response
### 200
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"zaapId": "3999984263738042930CD6ECDE9VDWSA",
"messageId": "D241XXXX732339502B68",
"id": "D241XXXX732339502B68"
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Enviar áudio
Source: https://developer.z-api.io/message/send-message-audio
POST /instances/{instanceId}/token/{token}/send-audio
Envia um áudio para um contato ou grupo no WhatsApp
## Conceituação
Método responsável por enviar áudios para os seus chats. Você pode trabalhar com os áudios de 2 formas:
* **Por Link**: caso você tenha o áudio hospedado em algum lugar da internet, basta enviar somente o link;
* **Por Base64**: caso você queira enviar o áudio em formato Base64.
#### Exemplo no WhatsApp
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Obrigatórios
Telefone (ou ID do grupo para casos de envio para grupos) do destinatário no formato DDI DDD NÚMERO. Ex: 551199999999
Link do áudio ou seu Base64
### Opcionais
Delay adicionado na mensagem. Você pode decidir entre um range de 1 a 15 sec, significa quantos segundos ele vai esperar para enviar a próxima mensagem. (Ex.: "delayMessage": 5). O delay default caso não seja informado é de 1 a 3 sec
Delay adicionado na mensagem. Você pode decidir entre um range de 1 a 15 sec, significa quantos segundos ele vai ficar com o status "Gravando áudio...". O delay default caso não seja informado é de 0
Define se será uma mensagem de visualização única ou não
Se ativo, a request responderá imediatamente com sucesso e o processamento do arquivo será realizado em segundo plano
Define se o áudio será enviado com ondas sonoras ou não
***
## Request Body
**Por link:**
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"phone": "5511999999999",
"audio": "https://exemplo.com/audio.mp3",
"viewOnce": false,
"waveform": true
}
```
**Por Base64:**
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"phone": "5511999999999",
"audio": "data:audio/mpeg;base64,SUQzAwAAAAAAbVRYWFgAAAAgAAAA...",
"viewOnce": false,
"waveform": true
}
```
***
## Response
### 200
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"zaapId": "3999984263738042930CD6ECDE9VDWSA",
"messageId": "D241XXXX732339502B68",
"id": "D241XXXX732339502B68"
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Enviar catálogo
Source: https://developer.z-api.io/message/send-message-catalog
POST /instances/{instanceId}/token/{token}/send-catalog
Envia uma mensagem com o link do catálogo para um contato ou grupo no WhatsApp
## Conceituação
Neste método você poderá enviar mensagens com o link para o seu catálogo. O recurso de catálogo está disponível apenas para contas **business** do WhatsApp que possuam produtos cadastrados.
#### Exemplo no WhatsApp
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Obrigatórios
Telefone (ou ID do grupo para casos de envio para grupos) do destinatário no formato DDI DDD NÚMERO. Ex: 551199999999
Telefone da conta business a qual pertence o catálogo
### Opcionais
Idioma da mensagem (EN ou PT)
Mensagem enviada junto com o card do catálogo
Título do card do catálogo
Descrição no card do catálogo
***
## Request Body
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"phone": "5511999999999",
"catalogPhone": "5511999999999"
}
```
***
## Response
### 200
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"zaapId": "3999984263738042930CD6ECDE9VDWSA",
"messageId": "D241XXXX732339502B68",
"id": "D241XXXX732339502B68"
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Enviar contato
Source: https://developer.z-api.io/message/send-message-contact
POST /instances/{instanceId}/token/{token}/send-contact
Envia um contato para um destinatário no WhatsApp
## Conceituação
Neste método você poderá compartilhar informações de um contato sem a necessidade que o destinatário o possua em seus contatos. Basta preencher os atributos do método com os dados do contato e enviar.
#### Exemplo no WhatsApp
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Obrigatórios
Telefone (ou ID do grupo para casos de envio para grupos) do destinatário no formato DDI DDD NÚMERO. Ex: 551199999999
Nome do contato
Número do telefone a ser compartilhado
### Opcionais
Breve descrição do contato (não é exibida no WhatsApp Web)
Atributo utilizado para responder uma mensagem do chat, basta adicionar o messageId da mensagem que queira responder neste atributo
Delay adicionado na mensagem. Você pode decidir entre um range de 1 a 15 sec, significa quantos segundos ele vai esperar para enviar a próxima mensagem. (Ex.: "delayMessage": 5). O delay default caso não seja informado é de 1 a 3 sec
***
## Request Body
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"phone": "5511999999999",
"contactName": "Z-API Contato",
"contactPhone": "554498398733"
}
```
***
## Response
### 200
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"zaapId": "3999984263738042930CD6ECDE9VDWSA",
"messageId": "D241XXXX732339502B68",
"id": "D241XXXX732339502B68"
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Enviar documento
Source: https://developer.z-api.io/message/send-message-document
POST /instances/{instanceId}/token/{token}/send-document/{extension}
Envia um documento para um contato ou grupo no WhatsApp
## Conceituação
Método responsável por enviar documentos aos seus contatos, ele é simples e objetivo. Você pode trabalhar com os documentos de 2 formas:
* **Por Link**: caso você tenha o documento hospedado em algum lugar da internet, basta enviar somente o link;
* **Por Base64**: caso você queira enviar o documento em formato Base64.
#### Exemplo no WhatsApp
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Path
Extensão do arquivo que está sendo enviado (ex: pdf, xlsx, docx)
### Obrigatórios
Telefone (ou ID do grupo para casos de envio para grupos) do destinatário no formato DDI DDD NÚMERO. Ex: 551199999999
Link do documento ou seu Base64
### Opcionais
Nome do documento para exibição
Descrição do arquivo
Atributo utilizado para responder uma mensagem do chat, basta adicionar o messageId da mensagem que queira responder neste atributo
Delay adicionado na mensagem. Você pode decidir entre um range de 1 a 15 sec, significa quantos segundos ele vai esperar para enviar a próxima mensagem. (Ex.: "delayMessage": 5). O delay default caso não seja informado é de 1 a 3 sec
Permite editar a descrição de um documento enviado anteriormente através do campo caption. É necessário configurar o webhook antes de utilizar
***
## Request Body
**Por link:**
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"phone": "5511999999999",
"document": "https://expoforest.com.br/wp-content/uploads/2017/05/exemplo.pdf",
"fileName": "Meu PDF"
}
```
**Por Base64:**
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"phone": "5511999999999",
"document": "data:application/pdf;base64,JVBERiN0YXJ0eHJlZg0KMjg3NDINCiUlRU9G0xLj...",
"fileName": "Meu PDF"
}
```
***
## Response
### 200
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"zaapId": "3999984263738042930CD6ECDE9VDWSA",
"messageId": "D241XXXX732339502B68",
"id": "D241XXXX732339502B68"
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Enviar GIF
Source: https://developer.z-api.io/message/send-message-gif
POST /instances/{instanceId}/token/{token}/send-gif
Envia um GIF para um contato ou grupo no WhatsApp
## Conceituação
Método responsável por enviar GIFs para os seus chats através da API.
O arquivo a ser enviado precisa ser um **MP4**.
#### Exemplo no WhatsApp
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Obrigatórios
Telefone (ou ID do grupo para casos de envio para grupos) do destinatário no formato DDI DDD NÚMERO. Ex: 551199999999
Link do arquivo do seu GIF (O arquivo precisa ser um MP4)
### Opcionais
Mensagem que desejar enviar junto com o GIF
Atributo utilizado para responder uma mensagem do chat, basta adicionar o messageId da mensagem que queira responder neste atributo
Delay adicionado na mensagem. Você pode decidir entre um range de 1 a 15 sec, significa quantos segundos ele vai esperar para enviar a próxima mensagem. (Ex.: "delayMessage": 5). O delay default caso não seja informado é de 1 a 3 sec
***
## Request Body
**Por link:**
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"phone": "5511999999999",
"gif": "https://exemplo.com/arquivo.mp4",
"caption": ""
}
```
**Por Base64:**
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"phone": "5511999999999",
"gif": "data:video/mp4;base64,AAYXJ0...",
"caption": ""
}
```
***
## Response
### 200
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"zaapId": "3999984263738042930CD6ECDE9VDWSA",
"messageId": "D241XXXX732339502B68",
"id": "D241XXXX732339502B68"
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Enviar imagem
Source: https://developer.z-api.io/message/send-message-image
POST /instances/{instanceId}/token/{token}/send-image
Envia uma imagem para um contato ou grupo no WhatsApp
## Conceituação
Método responsável por enviar imagens para os seus chats. Você pode trabalhar com as imagens de 2 formas:
* **Por Link**: caso você tenha a imagem hospedada em algum lugar da internet, basta enviar somente o link da imagem;
* **Por Base64**: caso você queira enviar a imagem em formato Base64.
Se optar por Base64, antes do binário você precisa adicionar a seguinte expressão: **data:image/png;base64,** seguido do seu código Base64.
Ferramentas para converter imagens em Base64:
* [base64-image.de](https://www.base64-image.de/)
* [base64.guru](https://base64.guru/converter/encode/image)
#### Exemplo no WhatsApp
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Obrigatórios
Telefone (ou ID do grupo para casos de envio para grupos) do destinatário no formato DDI DDD NÚMERO. Ex: 551199999999
Link da imagem ou seu Base64
### Opcionais
Mensagem a ser enviada junto com a imagem
Atributo utilizado para responder uma mensagem do chat, basta adicionar o messageId da mensagem que queira responder neste atributo
Delay adicionado na mensagem. Você pode decidir entre um range de 1 a 15 sec, significa quantos segundos ele vai esperar para enviar a próxima mensagem. (Ex.: "delayMessage": 5). O delay default caso não seja informado é de 1 a 3 sec
Define se será uma mensagem de visualização única ou não
Permite editar o caption da mensagem de imagem enviada anteriormente. É necessário configurar o webhook antes de utilizar.
***
## Request Body
**Por link:**
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"phone": "5511999999999",
"image": "https://www.z-api.io/wp-content/themes/z-api/dist/images/logo.svg",
"caption": "Logo",
"viewOnce": false
}
```
**Por Base64:**
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"phone": "5511999999999",
"image": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAyAAAAMgCAIAAABUEpE...",
"caption": "Logo",
"viewOnce": false
}
```
***
## Response
### 200
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"zaapId": "3999984263738042930CD6ECDE9VDWSA",
"messageId": "D241XXXX732339502B68",
"id": "D241XXXX732339502B68"
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Enviar link
Source: https://developer.z-api.io/message/send-message-link
POST /instances/{instanceId}/token/{token}/send-link
Envia um link com preview para um contato ou grupo no WhatsApp
## Conceituação
Método responsável por enviar um link aos seus contatos, muito utilizado para compartilhar links para que os usuários sejam direcionados a um site.
É importante você saber que o link só fica clicável caso o destinatário já tenha seu telefone nos contatos, ou se o mesmo iniciar uma conversa com você.
#### Exemplo no WhatsApp
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Obrigatórios
Telefone (ou ID do grupo para casos de envio para grupos) do destinatário no formato DDI DDD NÚMERO. Ex: 551199999999. **IMPORTANTE** Envie somente números, sem formatação ou máscara
Texto sobre seu link. **Não esqueça de informar o mesmo valor do linkURL no final deste texto.**
Link da imagem
URL do seu link
Título para o link
Descrição do link
### Opcionais
Atributo utilizado para definir o tamanho da mensagem de visualização do link enviado (SMALL, MEDIUM ou LARGE). O tamanho default caso não seja informado é SMALL.
Atributo utilizado para responder uma mensagem do chat, basta adicionar o messageId da mensagem que queira responder neste atributo
Delay adicionado na mensagem. Você pode decidir entre um range de 1 a 15 sec, significa quantos segundos ele vai esperar para enviar a próxima mensagem. (Ex.: "delayMessage": 5). O delay default caso não seja informado é de 1 a 3 sec
Delay adicionado na mensagem. Você pode decidir entre um range de 1 a 15 sec, significa quantos segundos ele vai ficar com o status "Digitando...". O delay default caso não seja informado é de 0
***
## Request Body
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"phone": "5511999998888",
"message": "Aqui você coloca um texto sobre o site, atenção esse texto precisa ter o link que será enviado no final da mensagem! Assim: https://z-api.io",
"image": "https://firebasestorage.googleapis.com/v0/b/zaap-messenger-web.appspot.com/o/logo.png?alt=media",
"linkUrl": "https://z-api.io",
"title": "Z-API",
"linkDescription": "Integração com o whatsapp"
}
```
***
## Response
### 200
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"zaapId": "3999984263738042930CD6ECDE9VDWSA",
"messageId": "D241XXXX732339502B68",
"id": "D241XXXX732339502B68"
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Enviar localização
Source: https://developer.z-api.io/message/send-message-location
POST /instances/{instanceId}/token/{token}/send-location
Envia uma localização fixa para um contato ou grupo no WhatsApp
## Conceituação
Método responsável por enviar uma localização fixa aos seus contatos.
#### Exemplo no WhatsApp
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Obrigatórios
Telefone (ou ID do grupo para casos de envio para grupos) do destinatário no formato DDI DDD NÚMERO. Ex: 551199999999
Título da localização
Endereço completo com rua, número, bairro, cidade, estado e CEP
Latitude da localização
Longitude da localização
### Opcionais
Atributo utilizado para responder uma mensagem do chat, basta adicionar o messageId da mensagem que queira responder neste atributo
Delay adicionado na mensagem. Você pode decidir entre um range de 1 a 15 sec, significa quantos segundos ele vai esperar para enviar a próxima mensagem. (Ex.: "delayMessage": 5). O delay default caso não seja informado é de 1 a 3 sec
***
## Request Body
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"phone": "5511999998888",
"title": "Google Brasil",
"address": "Av. Brg. Faria Lima, 3477 - Itaim Bibi, São Paulo - SP, 04538-133",
"latitude": "-23.0696347",
"longitude": "-50.4357913"
}
```
***
## Response
### 200
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"zaapId": "3999984263738042930CD6ECDE9VDWSA",
"messageId": "D241XXXX732339502B68",
"id": "D241XXXX732339502B68"
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Enviar múltiplos contatos
Source: https://developer.z-api.io/message/send-message-multiple-contacts
POST /instances/{instanceId}/token/{token}/send-contacts
Envia múltiplos contatos para um destinatário no WhatsApp
## Conceituação
Simples e objetivo este método permite você enviar vários contatos, você não precisa ter ele em seus contatos, basta preencher os atributos do método com informações do contato e enviar.
#### Exemplo no WhatsApp
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Obrigatórios
Telefone (ou ID do grupo para casos de envio para grupos) do destinatário no formato DDI DDD NÚMERO. Ex: 551199999999
Array de contatos a serem enviados
Nome do contato
Array de números de telefone do contato
Breve descrição do contato
### Opcionais
Atributo utilizado para responder uma mensagem do chat
Delay adicionado na mensagem. Você pode decidir entre um range de 1 a 15 sec. O delay default caso não seja informado é de 1 a 3 sec
***
## Request Body
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"phone": "5511999999999",
"contacts": [
{
"name": "Nome do contato",
"phones": ["5544999999999", "5544888888888"]
},
{
"name": "Nome do contato",
"phones": ["5544999999999"]
},
{
"name": "Nome do contato",
"businessDescription": "Uma empresa do Grupo Irrah",
"phones": ["5544999999999"]
}
]
}
```
***
## Response
### 200
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"zaapId": "3999984263738042930CD6ECDE9VDWSA",
"messageId": "D241XXXX732339502B68",
"id": "D241XXXX732339502B68"
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Enviar pedido
Source: https://developer.z-api.io/message/send-message-order
POST /instances/{instanceId}/token/{token}/send-order
Envia uma mensagem de pedido com produtos do catálogo ou customizados
## Conceituação
Neste método você poderá enviar mensagens de pedidos, contendo produtos do seu catálogo ou customizados no momento do envio. Esta mensagem é a mesma que é enviada quando você clica no botão "Aceitar pedido" ou "Enviar cobrança".
Disponível apenas para contas **business** do WhatsApp. Produtos sem `productId` são tratados como itens customizados.
#### Exemplo no WhatsApp
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Obrigatórios
Telefone do destinatário no formato DDI DDD NÚMERO. Ex: 551199999999
Dados do pedido
Código da moeda (ex: BRL)
Informações dos produtos relacionados ao pedido
Nome do produto
Valor do produto
Quantidade
ID do produto do catálogo
Valor de desconto
Valor de imposto
Valor de frete
### Opcionais
Configurações de pagamento
Configurações do PIX
Chave PIX
Tipo da chave: `cpf`, `cnpj`, `phone`, `email` ou `randomKey`
Nome da chave
Configurações de cartão
Habilitar pagamento por cartão
***
## Request Body
**Com produtos do catálogo e pagamento:**
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"phone": "554499999999",
"order": {
"currency": "BRL",
"discount": 10,
"tax": 10,
"shipping": 5,
"products": [
{
"productId": "23940797548900636",
"name": "Nome do produto",
"value": 10,
"quantity": 2
}
]
},
"paymentSettings": {
"pix": {
"key": "Chave PIX",
"keyType": "cpf",
"name": "Nome da chave"
},
"card": {
"enabled": true
}
}
}
```
**Apenas campos obrigatórios (produto customizado):**
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"phone": "554499999999",
"order": {
"currency": "BRL",
"products": [
{
"name": "Nome do produto",
"value": 150,
"quantity": 1
}
]
}
}
```
***
## Response
### 200
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"zaapId": "3999984263738042930CD6ECDE9VDWSA",
"messageId": "D241XXXX732339502B68",
"id": "D241XXXX732339502B68"
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Enviar produto
Source: https://developer.z-api.io/message/send-message-product
POST /instances/{instanceId}/token/{token}/send-product
Envia uma mensagem de produto para um contato ou grupo no WhatsApp
## Conceituação
Neste método você poderá enviar mensagens de seus produtos. O recurso de produtos está disponível apenas para contas **business** do WhatsApp.
É necessário que a conta tenha produtos cadastrados. As operações de produtos estão documentadas na seção [WhatsApp Business](/business/get-products).
#### Exemplo no WhatsApp
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Obrigatórios
Telefone (ou ID do grupo para casos de envio para grupos) do destinatário no formato DDI DDD NÚMERO. Ex: 551199999999
Telefone da conta business a qual pertence o produto
ID do produto. Pode ser obtido na API de [listar produtos](/business/get-products)
***
## Request Body
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"phone": "5511999999999",
"catalogPhone": "5511999999999",
"productId": "7190654897637620"
}
```
***
## Response
### 200
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"zaapId": "3999984263738042930CD6ECDE9VDWSA",
"messageId": "D241XXXX732339502B68",
"id": "D241XXXX732339502B68"
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
***
## Webhook Response
Link para a response do webhook (ao receber)
[Webhook](/webhooks/on-message-received)
# Enviar PTV
Source: https://developer.z-api.io/message/send-message-ptv
POST /instances/{instanceId}/token/{token}/send-ptv
Envia um vídeo circular (PTV) para um contato ou grupo no WhatsApp
## Conceituação
Método responsável por enviar PTV (Pre-Recorded Transfer Video) para os seus chats. Você pode trabalhar com os vídeos de 2 formas:
* **Por Link**: caso você tenha o vídeo hospedado em algum lugar da internet, basta enviar somente o link;
* **Por Base64**: caso você queira enviar o vídeo em formato Base64.
#### Exemplo no WhatsApp
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Obrigatórios
Telefone (ou ID do grupo para casos de envio para grupos) do destinatário no formato DDI DDD NÚMERO. Ex: 551199999999
Link do vídeo ou seu Base64
### Opcionais
Atributo utilizado para responder uma mensagem do chat, basta adicionar o messageId da mensagem que queira responder neste atributo
Delay adicionado na mensagem. Você pode decidir entre um range de 1 a 15 sec, significa quantos segundos ele vai esperar para enviar a próxima mensagem. (Ex.: "delayMessage": 5). O delay default caso não seja informado é de 1 a 3 sec
***
## Request Body
**Por link:**
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"phone": "5511999999999",
"ptv": "https://exemplo.com/video.mp4"
}
```
**Por Base64:**
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"phone": "5511999999999",
"ptv": "data:video/mp4;base64,AAYXJ0eKEF..."
}
```
***
## Response
### 200
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"zaapId": "3999984263738042930CD6ECDE9VDWSA",
"messageId": "D241XXXX732339502B68",
"id": "D241XXXX732339502B68"
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Enviar reação
Source: https://developer.z-api.io/message/send-message-reaction
POST /instances/{instanceId}/token/{token}/send-reaction
Envia uma reação com emoji em uma mensagem
## Conceituação
Neste método você poderá enviar uma reação com emoji em uma mensagem.
#### Exemplo no WhatsApp
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Obrigatórios
Telefone (ou ID do grupo para casos de envio para grupos) do destinatário no formato DDI DDD NÚMERO. Ex: 551199999999
Emoji da reação
ID da mensagem que será reagida
### Opcionais
Delay adicionado na mensagem. Você pode decidir entre um range de 1 a 15 sec, significa quantos segundos ele vai esperar para enviar a próxima mensagem. (Ex.: "delayMessage": 5). O delay default caso não seja informado é de 1 a 3 sec
***
## Request Body
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"phone": "5511999999999",
"reaction": "❤️",
"messageId": "3999984263738042930CD6ECDE9VDWSA"
}
```
***
## Response
### 200
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"zaapId": "3999984263738042930CD6ECDE9VDWSA",
"messageId": "D241XXXX732339502B68",
"id": "D241XXXX732339502B68"
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Enviar sticker
Source: https://developer.z-api.io/message/send-message-sticker
POST /instances/{instanceId}/token/{token}/send-sticker
Envia um sticker para um contato ou grupo no WhatsApp
## Conceituação
Método responsável por enviar stickers para os seus chats. Você pode trabalhar com os stickers de 2 formas:
* **Por Link**: caso você tenha o sticker hospedado em algum lugar da internet, basta enviar somente o link;
* **Por Base64**: caso você queira enviar o sticker em formato Base64.
Se optar por Base64, antes do binário você precisa adicionar a seguinte expressão: **data:image/png;base64,** seguido do seu código Base64.
Você pode verificar se o Base64 está correto colando-o na barra de endereços do seu navegador.
#### Exemplo no WhatsApp
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Obrigatórios
Telefone (ou ID do grupo para casos de envio para grupos) do destinatário no formato DDI DDD NÚMERO. Ex: 551199999999
Link do sticker ou seu Base64
### Opcionais
Atributo utilizado para responder uma mensagem do chat, basta adicionar o messageId da mensagem que queira responder neste atributo
Delay adicionado na mensagem. Você pode decidir entre um range de 1 a 15 sec, significa quantos segundos ele vai esperar para enviar a próxima mensagem. (Ex.: "delayMessage": 5). O delay default caso não seja informado é de 1 a 3 sec
Nome do autor do sticker
***
## Request Body
**Por link:**
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"phone": "5511999999999",
"sticker": "https://exemplo.com/sticker.png"
}
```
**Por Base64:**
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"phone": "5511999999999",
"sticker": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAyAAAAMgCAIAAABUEpE..."
}
```
***
## Response
### 200
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"zaapId": "3999984263738042930CD6ECDE9VDWSA",
"messageId": "D241XXXX732339502B68",
"id": "D241XXXX732339502B68"
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Enviar vídeo
Source: https://developer.z-api.io/message/send-message-video
POST /instances/{instanceId}/token/{token}/send-video
Envia um vídeo para um contato ou grupo no WhatsApp
## Conceituação
Método responsável por enviar vídeos para os seus chats. Você pode trabalhar com os vídeos de 2 formas:
* **Por Link**: caso você tenha o vídeo hospedado em algum lugar da internet, basta enviar somente o link;
* **Por Base64**: caso você queira enviar o vídeo em formato Base64.
Para um funcionamento mais previsível da API, recomendamos utilizar vídeos com CODEC **H.264**, que é o formato aceito pelo WhatsApp. Vídeos em outros CODECs passam por uma conversão interna para H.264, o que pode gerar intermitências no envio ou aumentar o tamanho final do arquivo, podendo ultrapassar o limite aceito pelo WhatsApp.
O tamanho do arquivo não deve ultrapassar **100MB**.
#### Exemplo no WhatsApp
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Obrigatórios
Telefone (ou ID do grupo para casos de envio para grupos) do destinatário no formato DDI DDD NÚMERO. Ex: 551199999999
Link do vídeo ou seu Base64
### Opcionais
Mensagem a ser enviada junto com o vídeo
Atributo utilizado para responder uma mensagem do chat, basta adicionar o messageId da mensagem que queira responder neste atributo
Delay adicionado na mensagem. Você pode decidir entre um range de 1 a 15 sec, significa quantos segundos ele vai esperar para enviar a próxima mensagem. (Ex.: "delayMessage": 5). O delay default caso não seja informado é de 1 a 3 sec
Define se será uma mensagem de visualização única ou não
Se ativo, a request responderá imediatamente com sucesso e o processamento do arquivo será realizado em segundo plano
Permite editar o caption da mensagem de vídeo enviado anteriormente. É necessário configurar o webhook antes de utilizar.
***
## Request Body
**Por link:**
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"phone": "5511999999999",
"video": "https://exemplo.com/video.mp4",
"caption": "",
"viewOnce": false
}
```
**Por Base64:**
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"phone": "5511999999999",
"video": "data:video/mp4;base64,AAYXJ0eKEF...",
"caption": "",
"viewOnce": false
}
```
***
## Response
### 200
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"zaapId": "3999984263738042930CD6ECDE9VDWSA",
"messageId": "D241XXXX732339502B68",
"id": "D241XXXX732339502B68"
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Enviar convite de admin do canal
Source: https://developer.z-api.io/message/send-newsletter-admin-invite
POST /instances/{instanceId}/token/{token}/send-newsletter-admin-invite
Envia um convite para administrar um canal no WhatsApp
## Conceituação
Neste método você poderá enviar mensagens convidando pessoas para serem administradoras dos seus canais no WhatsApp.
#### Exemplo no WhatsApp
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Obrigatórios
Telefone do destinatário no formato DDI DDD NÚMERO. Ex: 551199999999. **IMPORTANTE** Envie somente números, sem formatação ou máscara
Dados do convite
ID do canal ao qual pertence o convite. Ex: 120363166555745933\@newsletter
Texto da mensagem de convite
***
## Request Body
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"phone": "5511999999999",
"adminInviteMessage": {
"newsletterId": "120363166555745933@newsletter",
"caption": "Quero convidar você para ser admin do meu canal no WhatsApp."
}
}
```
***
## Response
### 200
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"zaapId": "3999984263738042930CD6ECDE9VDWSA",
"messageId": "D241XXXX732339502B68",
"id": "D241XXXX732339502B68"
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Enviar lista de opções
Source: https://developer.z-api.io/message/send-option-list
POST /instances/{instanceId}/token/{token}/send-option-list
Envia uma mensagem com lista de opções selecionáveis
## Conceituação
Neste método você poderá enviar mensagens de texto com uma lista de opções, onde o usuário poderá selecionar uma das opções enviadas.
A funcionalidade de lista de opções não funciona mais em grupos.
#### Exemplo no WhatsApp
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Obrigatórios
Telefone (ou ID do grupo para casos de envio para grupos) do destinatário no formato DDI DDD NÚMERO. Ex: 551199999999
Texto a ser enviado
Configuração da lista
Título da listagem
Texto do botão que abre a lista
Lista de opções
Título da opção
Descrição da opção
Identificador da opção
### Opcionais
Delay adicionado na mensagem. Você pode decidir entre um range de 1 a 15 sec, significa quantos segundos ele vai esperar para enviar a próxima mensagem. (Ex.: "delayMessage": 5). O delay default caso não seja informado é de 1 a 3 sec
***
## Request Body
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"phone": "5511999999999",
"message": "Selecione a melhor opção:",
"optionList": {
"title": "Opções disponíveis",
"buttonLabel": "Abrir lista de opções",
"options": [
{
"id": "1",
"description": "Z-API Asas para sua imaginação",
"title": "Z-API"
},
{
"id": "2",
"description": "Não funcionam",
"title": "Outros"
}
]
}
}
```
***
## Response
### 200
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"zaapId": "3999984263738042930CD6ECDE9VDWSA",
"messageId": "D241XXXX732339502B68",
"id": "D241XXXX732339502B68"
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Atualizar pagamento do pedido
Source: https://developer.z-api.io/message/send-order-payment-update
POST /instances/{instanceId}/token/{token}/order-payment-update
Envia uma atualização de pagamento do pedido
## Conceituação
Neste método você poderá enviar mensagens de atualização do pagamento dos pedidos enviados.
Este método está disponível apenas para contas **Business** do WhatsApp.
#### Exemplo no WhatsApp
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Obrigatórios
Telefone do destinatário no formato DDI DDD NÚMERO. Ex: 551199999999
ID da mensagem original do pedido no WhatsApp
ID de referência do pedido (obtido via webhook)
ID de referência da requisição do pedido (obtido via webhook)
Status do pedido: `pending`, `processing`, `shipped`, `completed` ou `canceled`
Status do pagamento: `pending` ou `paid`
Dados do pedido
Código da moeda (ex: BRL)
Produtos do pedido
Nome do produto
Valor do produto
Quantidade
ID do produto
Define se é um item customizado
Valor de desconto
Valor de imposto
Valor de frete
### Opcionais
Mensagem de texto da atualização do pedido
***
## Request Body
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"phone": "554499999999",
"messageId": "3EB0F91BBA791BB0A787FC",
"message": "Mensagem de texto da atualização do pedido",
"referenceId": "4N8FCTW1WM6",
"orderRequestId": "4N8FCTW22W4",
"orderStatus": "processing",
"paymentStatus": "paid",
"order": {
"currency": "BRL",
"discount": 10,
"tax": 10,
"shipping": 5,
"products": [
{
"value": 150,
"quantity": 2,
"name": "order 1",
"isCustomItem": true,
"productId": "custom-item-4N8FCTW23N7"
},
{
"productId": "23940797548900636",
"value": 150,
"quantity": 2,
"name": "order 2",
"isCustomItem": false
}
]
}
}
```
***
## Response
### 200
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"zaapId": "3999984263738042930CD6ECDE9VDWSA",
"messageId": "D241XXXX732339502B68",
"id": "D241XXXX732339502B68"
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Atualizar status do pedido
Source: https://developer.z-api.io/message/send-order-status-update
POST /instances/{instanceId}/token/{token}/order-status-update
Envia uma atualização de status do pedido
## Conceituação
Neste método você poderá enviar mensagens de atualização de status dos pedidos enviados.
Este método está disponível apenas para contas **Business** do WhatsApp. Todos os dados do pedido original devem ser reenviados com os parâmetros adicionais obrigatórios retornados via webhook.
#### Exemplo no WhatsApp
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Obrigatórios
Telefone do destinatário no formato DDI DDD NÚMERO. Ex: 551199999999
ID da mensagem original do pedido no WhatsApp
ID de referência do pedido (obtido via webhook)
ID de referência da requisição do pedido (obtido via webhook)
Novo status do pedido: `pending`, `processing`, `shipped`, `completed` ou `canceled`
Status do pagamento: `pending` ou `paid`
Dados do pedido
Código da moeda (ex: BRL)
Produtos do pedido
Nome do produto
Valor do produto
Quantidade
ID do produto (para itens customizados, prefixo "custom-item-")
Define se é um item customizado
Valor de desconto
Valor de imposto
Valor de frete
### Opcionais
Mensagem de texto da atualização do pedido
***
## Request Body
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"phone": "554499999999",
"messageId": "3EB0F91BBA791BB0A787FC",
"message": "Mensagem de texto da atualização do pedido",
"referenceId": "4N8FCTW1WM6",
"orderRequestId": "4N8FCTW22W4",
"orderStatus": "processing",
"paymentStatus": "pending",
"order": {
"currency": "BRL",
"discount": 10,
"tax": 10,
"shipping": 5,
"products": [
{
"value": 150,
"quantity": 2,
"name": "order 1",
"isCustomItem": true,
"productId": "custom-item-4N8FCTW23N7"
},
{
"productId": "23940797548900636",
"value": 150,
"quantity": 2,
"name": "order 2",
"isCustomItem": false
}
]
}
}
```
***
## Response
### 200
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"zaapId": "3999984263738042930CD6ECDE9VDWSA",
"messageId": "D241XXXX732339502B68",
"id": "D241XXXX732339502B68"
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Fixar / Desafixar mensagens
Source: https://developer.z-api.io/message/send-pin-message
POST /instances/{instanceId}/token/{token}/pin-message
Fixa ou desafixa uma mensagem em um chat privado ou grupo
## Conceituação
Neste método você poderá fixar mensagens de uma conversa, seja chats privados ou grupos.
#### Exemplo no WhatsApp
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Obrigatórios
Telefone (ou ID do grupo para casos de envio para grupos) do destinatário no formato DDI DDD NÚMERO. Ex: 551199999999
ID da mensagem que será fixada ou desafixada
Ação que será executada para a mensagem: `pin` (fixar) ou `unpin` (desafixar)
Tempo em que a mensagem ficará fixada: `24_hours`, `7_days` ou `30_days`. Não tem efeito no caso de desafixar uma mensagem.
***
## Request Body
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"phone": "5511999999999",
"messageId": "77DF5293EBC176FFA6A88838E7A6AD83",
"messageAction": "pin",
"pinMessageDuration": "7_days"
}
```
***
## Response
### 200
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"zaapId": "3999984263738042930CD6ECDE9VDWSA",
"messageId": "D241XXXX732339502B68",
"id": "D241XXXX732339502B68"
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Enviar enquete
Source: https://developer.z-api.io/message/send-poll
POST /instances/{instanceId}/token/{token}/send-poll
Envia uma mensagem do tipo enquete
## Conceituação
Neste método você poderá enviar mensagens do tipo enquete.
O envio de enquetes está disponível **apenas para grupos**, seguindo o comportamento do WhatsApp Web.
#### Exemplo no WhatsApp
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Obrigatórios
ID do grupo destinatário. Esse ID pode ser obtido através do método get/chats
Texto a ser enviado na enquete
Lista de opções da enquete
Nome da opção
### Opcionais
Delay adicionado na mensagem. Você pode decidir entre um range de 1 a 15 sec, significa quantos segundos ele vai esperar para enviar a próxima mensagem. (Ex.: "delayMessage": 5). O delay default caso não seja informado é de 1 a 3 sec
Número máximo de votos por pessoa na enquete
***
## Request Body
**Múltiplas escolhas:**
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"phone": "120363019502650977-group",
"message": "Qual a melhor API para WhatsApp?",
"poll": [
{ "name": "Z-API" },
{ "name": "Outras" }
]
}
```
**Escolha única:**
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"phone": "120363019502650977-group",
"message": "Qual a melhor API para WhatsApp?",
"pollMaxOptions": 1,
"poll": [
{ "name": "Z-API" },
{ "name": "Outras" }
]
}
```
***
## Response
### 200
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"zaapId": "3999984263738042930CD6ECDE9VDWSA",
"messageId": "D241XXXX732339502B68",
"id": "D241XXXX732339502B68"
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
***
## Webhook Response
Link para a response do webhook (ao receber)
[Webhook](/webhooks/on-message-received)
# Enviar voto para enquete
Source: https://developer.z-api.io/message/send-poll-vote
POST /instances/{instanceId}/token/{token}/send-poll-vote
Envia um voto em uma enquete
## Conceituação
Neste método você poderá votar em uma determinada enquete.
O envio de votos em enquetes está disponível **apenas para grupos**, seguindo o comportamento do WhatsApp Web.
#### Exemplo no WhatsApp
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Obrigatórios
ID do grupo destinatário. Esse ID pode ser obtido através do método get/chats
ID da mensagem de enquete
Lista de opções votadas
Nome da opção
***
## Request Body
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"phone": "120363019502650977-group",
"pollMessageId": "3999984263738042930CD6ECDE9VDWSA",
"pollVote": [
{ "name": "Z-API" }
]
}
```
***
## Response
### 200
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"zaapId": "3999984263738042930CD6ECDE9VDWSA",
"messageId": "D241XXXX732339502B68",
"id": "D241XXXX732339502B68"
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Remover reação
Source: https://developer.z-api.io/message/send-remove-reaction
POST /instances/{instanceId}/token/{token}/send-remove-reaction
Remove a reação de uma mensagem enviada ou recebida
## Conceituação
Neste método você removerá a reação das mensagens enviadas ou recebidas.
#### Exemplo no WhatsApp
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Obrigatórios
Telefone (ou ID do grupo para casos de envio para grupos) do destinatário no formato DDI DDD NÚMERO. Ex: 551199999999
ID da mensagem que terá a reação removida
### Opcionais
Delay adicionado na mensagem. Você pode decidir entre um range de 1 a 15 sec, significa quantos segundos ele vai esperar para enviar a próxima mensagem. (Ex.: "delayMessage": 5). O delay default caso não seja informado é de 1 a 3 sec
***
## Request Body
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"phone": "5511999999999",
"messageId": "3999984263738042930CD6ECDE9VDWSA"
}
```
***
## Response
### 200
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"zaapId": "3999984263738042930CD6ECDE9VDWSA",
"messageId": "D241XXXX732339502B68",
"id": "D241XXXX732339502B68"
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Enviar texto simples
Source: https://developer.z-api.io/message/send-text
POST /instances/{instanceId}/token/{token}/send-text
Envia uma mensagem de texto simples para um contato ou grupo no WhatsApp.
## Conceituação
Neste método você poderá enviar mensagens de texto simples, mas você pode incrementá-las utilizando a formatação de texto e emojis, por exemplo. Caso você ainda não saiba como fazer isso, clique nos links abaixo e siga as instruções:
* Para saber como formatar fontes no WhatsApp [clique aqui](https://faq.whatsapp.com/general/chats/how-to-format-your-messages/?lang=pt_br)
* Você também pode utilizar **quebra de linhas** em suas mensagens, porém isso pode ser feito de formas diferentes, isso muda por fatores como a plataforma que sua aplicação está rodando e linguagem de programação utilizada. Até o momento, indentificamos as seguintes formas:
> * \n
> * \r
> * \r\n
> * %0a
Verifique a que mais se adequa ao seu caso.
**Se descobrir uma maneira nova de fazer quebra de linhas, por favor nos avise :)**
* Outro recurso que você pode explorar é a utilização de emojis. Se você precisar pegar alguns emojis use este [link](https://fsymbols.com/pt/emoji/).
**Sobre emojis**
Um emoji é um caracter ASCII normal, assim como existe a fonte Times New Roman por exemplo, existem fontes de emojis, pense que você pode criar sua própria galeria de emojis.
Para fazer o teste, basta copiar um emoji e colar em seu texto! Você pode utilizar este aqui 🤪 se quiser.
#### Exemplo no WhatsApp
***
## Atributos
### Obrigatórios
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
Telefone (ou ID do grupo para casos de envio para grupos) do destinatário no formato DDI DDD NÚMERO Ex: 551199999999. **IMPORTANTE** Envie somente números, sem formatação ou máscara
Texto a ser enviado
### Opcionais
Nesse atributo um delay é adicionado na mensagem. Você pode decidir entre um range de 1 a 15 seg, que significa quantos segundos ele vai esperar para enviar a próxima mensagem. (Ex.: "delayMessage": 5). O delay default caso não seja informado é de 1 a 3 sec
Nesse atributo um delay é adicionado na mensagem. Você pode decidir entre um range de 1 a 15 sec, significa quantos segundos ele vai ficar com o status "Digitando...". (Ex "delayTyping": 5). O delay default caso não seja informado é de 0
Esse atributo permite editar mensagens enviadas anteriormente no WhatsApp. Use o ID da mensagem e o novo conteúdo no JSON para fazer alterações. É necessário configurar o webhook antes de editar.
***
## Request Body
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"phone": "5511999999999",
"message": "Welcome to *Z-API*"
}
```
***
## Response
### 200
id no z-api
id no whatsapp
Adicionado para compatibilidade com zapier, ele tem o mesmo valor do messageId
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"zaapId": "3999984263738042930CD6ECDE9VDWSA",
"messageId": "D241XXXX732339502B68",
"id": "D241XXXX732339502B68"
}
```
### 405
Neste caso certifique que esteja enviando o corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no inicio deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json"
***
## Webhook Response
Link para a response do webhook (ao receber)
[Webhook](/webhooks/on-message-received)
# Responder captcha
Source: https://developer.z-api.io/mobile/captcha-confirm
POST /instances/{instanceId}/token/{token}/mobile/respond-captcha
Responde ao captcha necessário para envio do código de confirmação
## Conceituação
Método utilizado para responder ao captcha necessário para envio do código de confirmação.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Body
Código captcha para confirmação. Esse captcha é exibido na imagem retornada na solicitação do código de confirmação.
***
## Request Body
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"captcha": "123456"
}
```
***
## Response
### 200
Retorna true caso o captcha tenha sido respondido corretamente. Sendo assim, aguarde o recebimento do código de confirmação e utilize-o na API de confirmar código.
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"success": true
}
```
### 400
Requisição inválida. Verifique se os dados que você está enviando estão de acordo com o documentado.
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Confirmar código
Source: https://developer.z-api.io/mobile/confirm-code
POST /instances/{instanceId}/token/{token}/mobile/confirm-registration-code
Confirma o código de confirmação recebido para registro do número
## Conceituação
Método utilizado para confirmar o código que você recebeu. Para utilizar esse método, você precisa concluir as etapas de registro anteriores, que envolvem verificar a disponibilidade de registro do número e solicitar o código de confirmação.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Body
Código de confirmação
***
## Request Body
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"code": "123456"
}
```
***
## Response
### 200
Retorna true caso o código tenha sido confirmado corretamente. Feito isso, a instância estará conectada.
Retorna true se for necessário a confirmação do código de verificação em duas etapas.
Retorna true se for necessário confirmar a transferência do WhatsApp no celular onde ele está registrado. Enquanto a confirmação não for feita no aparelho, a conexão não será transferida para a instância.
**Sucesso:**
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"success": true
}
```
**Necessário confirmar código de segurança:**
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"success": false,
"confirmSecurityCode": true
}
```
**Necessário confirmar transferência no celular:**
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"success": false,
"deviceConfirm": true
}
```
### 400
Requisição inválida. Verifique se os dados que você está enviando estão de acordo com o documentado.
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Confirmar código PIN
Source: https://developer.z-api.io/mobile/confirm-security-code
POST /instances/{instanceId}/token/{token}/mobile/confirm-pin-code
Confirma o código PIN da verificação em duas etapas do WhatsApp
## Conceituação
Método utilizado para confirmar código PIN da sua conta. Esse método somente é necessário caso você tenha configurado a verificação em duas etapas no WhatsApp.
Sem essa confirmação, o número não poderá ser conectado em uma instância mobile.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Body
Código PIN da verificação em duas etapas
***
## Request Body
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"code": "123456"
}
```
***
## Response
### 200
Retorna true caso o código PIN tenha sido confirmado corretamente
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"success": true
}
```
### 400
Requisição inválida. Verifique se os dados que você está enviando estão de acordo com o documentado.
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Confirmar transferência no celular
Source: https://developer.z-api.io/mobile/device-transfer-confirmed
GET /instances/{instanceId}/token/{token}/mobile/device-transfer-confirmed
Finaliza a transferência do WhatsApp do celular para a instância após confirmação no aparelho
## Conceituação
Método utilizado para finalizar a transferência do WhatsApp do celular para a instância. Ele deve ser utilizado após o endpoint de [Confirmar código](/mobile/confirm-code) retornar `deviceConfirm: true` no response.
**Confirme a transferência no celular antes de fazer a requisição.**
Ao receber `deviceConfirm: true`, o WhatsApp exibirá uma notificação no celular onde está registrado solicitando a confirmação da transferência. **Somente após aceitar essa confirmação no aparelho** é que você deve chamar este endpoint. Caso contrário, a conexão não será transferida para a instância.
***
## Fluxo esperado
1. O endpoint **Confirmar código** retorna `"deviceConfirm": true`
2. O usuário **confirma a transferência no celular** onde o WhatsApp está registrado
3. Após a confirmação no aparelho, chame este endpoint
4. A conexão do WhatsApp é transferida do celular para a instância
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
***
## Response
### 200
Retorna true caso a transferência tenha sido confirmada com sucesso e a instância esteja conectada.
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"success": true
}
```
### 400
Requisição inválida. Verifique se a confirmação no celular foi realizada antes de chamar este endpoint.
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Recuperar código PIN
Source: https://developer.z-api.io/mobile/forgot-security-code
POST /instances/{instanceId}/token/{token}/mobile/recovery-pin-code
Solicita e-mail para recuperação do código PIN da verificação em duas etapas
## Conceituação
Método utilizado para solicitar email para recuperação do código PIN da sua conta. Esse será útil caso você tenha configurado a verificação em duas etapas no WhatsApp e não se lembre mais desse código. Dessa forma, o WhatsApp enviará um link para redefinição de código PIN no email que você vinculou à sua conta do WhatsApp.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
***
## Response
### 200
Retorna true caso o e-mail de recuperação tenha sido enviado com sucesso
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"success": true
}
```
### 400
Requisição inválida. Verifique se os dados que você está enviando estão de acordo com o documentado.
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Buscar e-mail da conta
Source: https://developer.z-api.io/mobile/get-account-email
GET /instances/{instanceId}/token/{token}/security/email
Retorna o e-mail configurado na conta WhatsApp da instância mobile
## Conceituação
Método utilizado para buscar o e-mail configurado na conta WhatsApp de uma instância mobile.
Essa API está disponível apenas para instâncias mobile.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
***
## Response
### 200
Retorna true caso a execução tenha sido bem-sucedida
Indica se a conta possui e-mail configurado
Endereço de e-mail configurado
Status de verificação do e-mail
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"success": true,
"hasEmail": true,
"email": "example@email.com",
"verified": true
}
```
### 400
Requisição inválida. Verifique se os dados que você está enviando estão de acordo com o documentado.
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Verificar código PIN
Source: https://developer.z-api.io/mobile/get-has-security-code
GET /instances/{instanceId}/token/{token}/security/two-fa-code
Verifica se a conta possui código PIN de segurança cadastrado
## Conceituação
Método utilizado para verificar se a conta possui um código PIN de segurança cadastrado.
Essa API está disponível apenas para instâncias mobile.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
***
## Response
### 200
Retorna true caso a execução tenha sido bem-sucedida
Indica se a conta possui código PIN cadastrado
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"success": true,
"hasCode": true
}
```
### 400
Requisição inválida. Verifique se os dados que você está enviando estão de acordo com o documentado.
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Introdução
Source: https://developer.z-api.io/mobile/introduction
Entenda o que são instâncias mobile e como registrar um número
## Instâncias Mobile
As instâncias mobile funcionam como um celular real para o WhatsApp — sem precisar de emulador ou dispositivo físico. Ao invés de ser conectada como um dispositivo secundário, como no caso da instância web, ela é o dispositivo primário.
Isso significa que, ao utilizar uma instância mobile, o número ficará desvinculado do WhatsApp no celular físico. No entanto, é possível integrar normalmente com serviços, sistemas e automações para acompanhar e gerenciar as conversas.
***
## Vantagens
Configuração de e-mail e códigos PIN para proteção da conta.
A instância atua como dispositivo principal, sem precisar de emulador ou celular físico.
Configuração e verificação de e-mail vinculado à conta.
Funcionalidade de código PIN para segurança adicional da conta.
***
## Fluxo de registro
Para registrar um número em uma instância mobile, siga o fluxo abaixo:
Verifique a elegibilidade do número e se ele não está banido.
Solicite o código de confirmação via SMS, chamada de voz ou app.
Complete a verificação de captcha caso seja solicitado.
Informe o código de confirmação recebido.
Informe o PIN de segurança, caso tenha sido configurado anteriormente.
Opção de recuperar o código de segurança caso tenha esquecido.
Lembrando que as demais API's relacionadas ao WhatsApp - como de envio de mensagens e interações na conta - funcionam da mesma forma como para as instâncias web. Ou seja, os métodos são totalmente compatíveis entre instâncias.
# Verificar disponibilidade
Source: https://developer.z-api.io/mobile/registration-available
POST /instances/{instanceId}/token/{token}/mobile/registration-available
Verifica a disponibilidade de registro de um número no WhatsApp
## Conceituação
Método utilizado para verificar disponibilidade de registro de um número. Este endpoint verifica se o número está disponível para registro e realiza o setup de onboarding do WhatsApp. Deve ser chamado antes de solicitar o código de confirmação.
**ATENÇÃO**
Não utilize esse método se você não tem acesso ao celular onde o número está atualmente vinculado. Este método é útil para agilizar o processo de confirmação do código, sem ter que esperar o recebimento de um SMS ou chamada de voz, porém necessita que você tenha o dispositivo em mãos e com o aplicativo do WhatsApp aberto.
**Caso de número banido**
Existem alguns cenários onde o número é impedido de ser conectado até mesmo no aplicativo oficial do WhatsApp. Nesse caso, a API de verificar disponibilidade do número não é capaz de identificar isso, e acaba sendo retornado que o número está bloqueado somente no momento de solicitar o código. Infelizmente, até o momento não há nada que possamos fazer a esse respeito, pois, diferente do banimento padrão, não é disponibilizado um token (appealToken) para realizar uma solicitação de desbanimento.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Body
Código do país
Número do telefone com DDD, sem formatação
***
## Request Body
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"ddi": "55",
"phone": "4499999999"
}
```
***
## Response
### 200
Retorna true caso o número esteja disponível para registro
Define se o número está banido ou bloqueado por algum outro motivo
Token para solicitação de desbanimento (quando bloqueado)
Tempo que deve ser aguardado para solicitação de SMS
Tempo que deve ser aguardado para solicitação de chamada de voz
Tempo que deve ser aguardado para solicitação de pop-up no aplicativo
Define se o método de solicitação do código via pop-up está disponível
Em caso de erro, esse atributo diz a razão pela qual o erro aconteceu
**Número disponível:**
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"available": true,
"smsWaitSeconds": 0,
"voiceWaitSeconds": 0,
"waOldWaitSeconds": 0,
"waOldEligible": true
}
```
**Número bloqueado:**
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"available": false,
"blocked": true,
"appealToken": "Ae0B_6FfVfyB8on0v76ALf1RkWXFFsfvliOdh02JyXTFcbnlTAwO5_h5Ju4L5zfa..."
}
```
### 400
Requisição inválida. Verifique se os dados que você está enviando estão de acordo com o documentado.
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Remover e-mail da conta
Source: https://developer.z-api.io/mobile/remove-account-email
POST /instances/{instanceId}/token/{token}/security/email/remove
Remove o e-mail cadastrado na conta WhatsApp da instância mobile
## Conceituação
Método utilizado para remover o e-mail cadastrado na sua conta do WhatsApp.
Essa API está disponível apenas para instâncias mobile.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
***
## Response
### 200
Retorna true caso o e-mail tenha sido removido com sucesso
Retorna `REMOVED` confirmando a remoção do e-mail
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"success": true,
"message": "REMOVED"
}
```
### 400
Requisição inválida. Verifique se os dados que você está enviando estão de acordo com o documentado.
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Remover código PIN
Source: https://developer.z-api.io/mobile/remove-security-code
POST /instances/{instanceId}/token/{token}/security/two-fa-code/remove
Remove o código PIN de segurança da conta WhatsApp
## Conceituação
Método utilizado para remover o código PIN de segurança da conta.
Essa API está disponível apenas para instâncias mobile.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
***
## Response
### 200
Define se a requisição foi executada com sucesso
Em caso de falha, retorna uma mensagem a respeito do erro
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"success": true
}
```
### 400
Requisição inválida. Verifique se os dados que você está enviando estão de acordo com o documentado.
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Solicitar código de confirmação
Source: https://developer.z-api.io/mobile/request-code
POST /instances/{instanceId}/token/{token}/mobile/request-registration-code
Solicita o envio do código de confirmação para registro do número
## Conceituação
Método utilizado para solicitar o envio do código de confirmação.
Não se esqueça que o número de telefone que você deve enviar nesta requisição é o mesmo que você verificou na API anterior.
Caso receba um captcha na resposta, confirme-o via API de captcha antes de receber o código.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Body
Código do país
Número do telefone com DDD (ex: 4499999999)
Método de envio do código: `sms`, `voice` ou `wa_old`
***
## Request Body
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"ddi": "55",
"phone": "4499999999",
"method": "sms"
}
```
***
## Response
### 200
Retorna true caso a solicitação do código tenha sido enviada com sucesso
Base64 de imagem com código captcha
Define se o número está banido ou não
Tempo em segundos que deve ser aguardado para nova solicitação do código
Tempo que deve ser aguardado para solicitação de SMS
Tempo que deve ser aguardado para solicitação de chamada de voz
Tempo que deve ser aguardado para solicitação de pop-up no aplicativo
Método de envio do código
**Sucesso:**
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"success": true,
"retryAfter": 165,
"smsWaitSeconds": 125,
"voiceWaitSeconds": 125,
"waOldWaitSeconds": 125,
"method": "sms"
}
```
**Número bloqueado:**
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"success": false,
"blocked": true
}
```
### 400
Requisição inválida. Verifique se os dados que você está enviando estão de acordo com o documentado.
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Solicitar desbanimento
Source: https://developer.z-api.io/mobile/request-unbanning
POST /instances/{instanceId}/token/{token}/mobile/request-unbanning
Solicita o desbanimento de um número no WhatsApp
## Conceituação
Método utilizado para solicitar desbanimento de um número.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Body
Token de apelação para desbanimento do número
Motivo da solicitação de desbanimento, que será analisado pelo WhatsApp
***
## Request Body
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"appealToken": "Ae1CIGl4Mq7kQ09OQzUnnCx2mTPHxZCjPesdRc8Z1lNFV9d6gvtd5LDW0r7ukVAgtMOP2AxckQM6QeyVp7bL0RbbVac6GQUtMd4tYAZsPOwSIQKlVIoTZs2akgcRd-jvhLKh32roOd0KFPg7hAaYURpIuDXhkaZ_gLJLhmzADNp3lxUNdsIg10q92w",
"description": "Estava conversando normalmente e fui banido"
}
```
***
## Response
### 200
Retorna true caso a solicitação tenha ocorrido com sucesso
Status da solicitação: `IN_REVIEW` (em análise) ou `UNBANNED` (desbanido)
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"success": true,
"status": "IN_REVIEW"
}
```
### 400
Requisição inválida. Verifique se os dados que você está enviando estão de acordo com o documentado.
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Cadastrar e-mail na conta
Source: https://developer.z-api.io/mobile/set-account-email
POST /instances/{instanceId}/token/{token}/security/email
Cadastra um e-mail na conta WhatsApp da instância mobile
## Conceituação
Método utilizado para cadastrar um email na sua conta do WhatsApp. Esse email pode ser utilizado mais tarde para recuperação do código PIN de segurança da sua conta.
Essa API está disponível apenas para instâncias mobile.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Body
Email a ser cadastrado
***
## Request Body
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"email": "example@email.com"
}
```
***
## Response
### 200
Retorna true caso a solicitação tenha sido realizada com sucesso
Retorna `VERIFY_EMAIL` indicando que um e-mail de verificação foi enviado para o endereço fornecido, contendo um código necessário para completar o registro através da API de verificação.
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"success": true,
"message": "VERIFY_EMAIL"
}
```
### 400
Requisição inválida. Verifique se os dados que você está enviando estão de acordo com o documentado.
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Cadastrar código PIN
Source: https://developer.z-api.io/mobile/set-security-code
POST /instances/{instanceId}/token/{token}/security/two-fa-code
Cadastra um código PIN de segurança na conta WhatsApp
## Conceituação
Método utilizado para cadastrar um código PIN de segurança na sua conta do WhatsApp.
Essa API está disponível apenas para instâncias mobile.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Body
Código PIN a ser cadastrado
***
## Request Body
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"code": "123456"
}
```
***
## Response
### 200
Retorna true caso o código PIN tenha sido cadastrado com sucesso
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"success": true
}
```
### 400
Requisição inválida. Verifique se os dados que você está enviando estão de acordo com o documentado.
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Verificar e-mail da conta
Source: https://developer.z-api.io/mobile/verify-account-email
POST /instances/{instanceId}/token/{token}/security/verify-email
Verifica o e-mail cadastrado na conta WhatsApp da instância mobile
## Conceituação
Método utilizado para verificar o e-mail cadastrado na sua conta do WhatsApp. O código de verificação é enviado para o e-mail que foi cadastrado através da API de cadastro de e-mail.
Essa API está disponível apenas para instâncias mobile.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Body
Código de verificação enviado para o email que foi cadastrado na conta
***
## Request Body
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"verificationCode": "123456"
}
```
***
## Response
### 200
Retorna true caso o e-mail tenha sido verificado com sucesso
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"success": true
}
```
### 400
Requisição inválida. Verifique se os dados que você está enviando estão de acordo com o documentado.
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Conexão via extensão para parceiros
Source: https://developer.z-api.io/partner/extension-token
Como implementar o fluxo de geração de token de extensão na sua plataforma
## Visão geral
Em alguns dispositivos, o WhatsApp passou a exigir uma verificação de segurança com chave de acesso para autorizar novas conexões ao WhatsApp Web. Quando isso acontece, o cliente final **não consegue conectar** a instância Z-API pelo fluxo tradicional de QR Code.
Esse comportamento **não ocorre em todos os dispositivos**. Por isso, não substitua o fluxo de conexão padrão — implemente a conexão via extensão como uma **opção alternativa**, exibida apenas quando o cliente relatar dificuldades para conectar.
**Limitações conhecidas (fora do nosso controle):** o pareamento via passkey depende de recursos da própria plataforma (Windows/Bluetooth), e não da Z-API.
* **Windows 10 (ou inferior):** não há suporte a pareamento de passkey via Bluetooth nem sincronização de passkeys em nuvem. Nesses casos, o sistema solicita uma "chave de segurança USB" física e o fluxo não avança. Como o Windows 10 saiu de suporte em out/2025, não há previsão de correção pela Microsoft. Esse recurso é exclusivo do **Windows 11**.
* **Dispositivos sem Bluetooth:** independentemente do sistema operacional, o pareamento com o celular não é possível sem Bluetooth.
A recomendação é seguir o mesmo padrão do painel Z-API: exibir um aviso ou banner de "problemas ao conectar" que, ao ser clicado, inicia o fluxo de geração do código de extensão. Veja o exemplo abaixo:
Dessa forma, clientes que conseguem conectar normalmente não são impactados, e os que precisam da extensão têm um caminho claro para resolver.
***
## Responsabilidade do parceiro
O fluxo de responsabilidades é o seguinte:
1. **Parceiro** → chama o endpoint [`extension-token`](/instance/extension-token) da Z-API para gerar o código
2. **Parceiro** → exibe o código gerado na própria interface para o cliente
3. **Cliente final** → usa o código na extensão [Z-API Conector](https://chromewebstore.google.com/detail/iopmkohngoecmepoheapifkafbeomphn) para conectar a instância
A geração do token é de responsabilidade do parceiro. O cliente final nunca deve ter acesso direto às credenciais da instância (instanceId e token).
***
## Como gerar o token
Faça uma requisição autenticada ao endpoint de geração de token da instância do seu cliente:
```bash theme={"theme":{"light":"github-light","dark":"poimandres"}}
curl --location 'https://api.z-api.io/instances/{instanceId}/token/{instanceToken}/extension-token' \
--header 'Client-Token: SEU_CLIENT_TOKEN'
```
**Resposta:**
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"token": "FA48-HS63",
"expiresAt": 1782851138085
}
```
Código de conexão a ser exibido para o cliente final (formato `XXXX-XXXX`)
Timestamp Unix (em milissegundos) com a data de expiração do código
O token possui validade limitada. Exiba o tempo restante para o cliente e ofereça a opção de gerar um novo código caso ele expire antes de ser utilizado.
Documentação completa do endpoint: [Gerar token para extensão](/instance/extension-token)
***
## O que exibir para o cliente
Abaixo está o exemplo de como o próprio painel Z-API exibe o código para o cliente — use como referência para implementar na sua plataforma:
Sua interface deve apresentar ao cliente:
* O **código de conexão** gerado (ex: `FA48-HS63`) com opção de copiar
* Um **contador regressivo** com o tempo restante de validade
* O **link para instalar a extensão** [Z-API Conector](https://chromewebstore.google.com/detail/iopmkohngoecmepoheapifkafbeomphn)
* Os **passos** que o cliente deve seguir após receber o código:
1. Instalar a extensão Z-API Conector no Chrome
2. Acessar [https://web.whatsapp.com/](https://web.whatsapp.com/) logado com o número a conectar
3. Clicar no ícone da extensão e digitar o código
4. Confirmar na tela da extensão para finalizar a conexão
***
## O que o cliente faz com o código
Após receber o código gerado pela sua plataforma, o cliente deve seguir os passos abaixo:
### 1. Instalar a extensão Z-API Conector
Caso ainda não tenha instalado, o cliente acessa a Chrome Web Store e instala a extensão [Z-API Conector](https://chromewebstore.google.com/detail/iopmkohngoecmepoheapifkafbeomphn).
### 2. Abrir o WhatsApp Web logado com o número a conectar
O cliente acessa **[web.whatsapp.com](https://web.whatsapp.com/)** no Chrome, já conectado com o número que deve ser vinculado à instância Z-API.
O número aberto no WhatsApp Web deve ser o mesmo que será conectado na instância. A extensão detecta automaticamente o número logado.
### 3. Inserir o código na extensão
Com o WhatsApp Web aberto, o cliente clica no ícone da extensão **Z-API Conector** na barra do Chrome. A extensão detecta o número logado e exibe os campos para digitar o código de conexão (formato `XXXX-XXXX`):
### 4. Confirmar e conectar na Z-API
Após digitar o código, a extensão exibe uma tela de confirmação com o nome da instância, o número detectado e um contador regressivo. O cliente clica em **"Conectar na Z-API"**:
A sessão ativa do WhatsApp Web é encerrada e o número passa a estar conectado na instância Z-API.
***
## Considerações finais
* O backend do parceiro deve ser o único a chamar o endpoint [`extension-token`](/instance/extension-token); nunca exponha essa chamada no frontend
* Oriente seu cliente a ter o WhatsApp Web aberto e logado **antes** de inserir o código na extensão
# SDK de conexão
Source: https://developer.z-api.io/partner/sdk-connector
Modal pronto de conexão do WhatsApp para embutir no seu software
## Visão geral
O **SDK de conexão** é um modal pronto que você embute no seu próprio software. O seu cliente clica em "conectar", escaneia o QR Code (ou usa o número de telefone) e a instância Z-API dele conecta — tudo sem você construir nenhuma tela.
* Carrega com uma única tag `
```
Isso expõe `window.ZAPIConnector` globalmente.
***
## 3. Abra o conector
Quando o cliente clicar em conectar, busque o token no seu backend e chame `open()`. Ele devolve uma `Promise` que fica pendente até o modal fechar e resolve `true` se o canal conectou:
```js theme={"theme":{"light":"github-light","dark":"poimandres"}}
async function conectar(instanceId) {
const { token } = await fetch(`/sdk-token/${instanceId}`).then((r) =>
r.json(),
);
const conectado = await ZAPIConnector.open({ token });
if (conectado) {
atualizarInstancias();
}
}
```
***
## Opções
`ZAPIConnector.open(options)` aceita:
| Opção | Tipo | Descrição |
| - | - | - |
| `token` | `string` **(obrigatório)** | Token de sessão retornado pelo seu backend. Passe como veio — o SDK escolhe a experiência de conexão a partir dele. |
| `theme` | `"light" \| "dark" \| ThemeOptions` | Tema de cores. Padrão: `"light"`. Veja [Temas](#temas). |
| `locale` | `"pt" \| "en" \| string` | Idioma da interface. Detectado do navegador quando omitido. |
| `messages` | `Partial` | Sobrescreve textos individuais ou traduz para outro idioma. Veja [Mensagens](#mensagens). |
| `methods` | `{ qr?, phone?, migrate? }` | Quais opções de conexão exibir. Cada uma é `true` por padrão. Veja [Métodos de conexão](#métodos-de-conexão). |
| `showQueue` | `boolean` | Mostra o aviso de mensagens na fila (com opção de limpar). Padrão `true`. Veja [Fila de mensagens](#fila-de-mensagens). |
| `onSubscribe` | `() => void` | Callback chamado ao clicar em "Assinar novamente" na tela de instância expirada. Veja [Instância expirada](#instância-expirada). |
| `container` | `string \| HTMLElement` | Onde montar o modal. Padrão: `document.body`. |
***
## Temas
Passe um modo (`"light"` ou `"dark"`), ou um objeto `ThemeOptions` para sobrescrever cores específicas por modo:
```js theme={"theme":{"light":"github-light","dark":"poimandres"}}
ZAPIConnector.open({
token,
theme: {
mode: "dark",
light: { accent: "#25d366" },
dark: { accent: "#00a884", surface: "#111b21" },
},
});
```
Tokens de cor (`ThemeColors`, todos opcionais):
| Token | Descrição |
| - | - |
| `overlay` | Cor do fundo escurecido atrás do modal |
| `surface` | Cor de fundo do cartão do modal |
| `surfaceAlt` | Fundo secundário (abas, campos, caixas) |
| `text` | Cor do texto principal |
| `textMuted` | Cor do texto secundário |
| `border` | Cor das bordas |
| `accent` | Cor de destaque (botões, links, realces) |
| `accentContrast` | Cor do texto sobre a cor de destaque |
***
## Idioma
Idiomas nativos: **`pt`** e **`en`** (detectados de `navigator.language`). Force um com `locale`:
```js theme={"theme":{"light":"github-light","dark":"poimandres"}}
ZAPIConnector.open({ token, locale: "pt" });
```
Para ajustar textos ou traduzir para um idioma que não seja nativo, use `messages` — um mapa parcial mesclado sobre o idioma selecionado. Passe só as chaves que quer mudar:
```js theme={"theme":{"light":"github-light","dark":"poimandres"}}
ZAPIConnector.open({
token,
messages: {
title: "Conecte seu número",
subtitle: "Aponte a câmera do WhatsApp para o código.",
},
});
```
***
## Métodos de conexão
Por padrão o modal mostra QR Code, número de telefone e o link de migração. Use `methods` para exibir só o que quiser:
```js theme={"theme":{"light":"github-light","dark":"poimandres"}}
ZAPIConnector.open({ token, methods: { phone: false, migrate: false } });
```
| Chave | Descrição |
| - | - |
| `qr` | Aba do QR Code. Padrão `true`. |
| `phone` | Aba do número de telefone. Padrão `true`. |
| `migrate` | Link para migrar uma sessão do WhatsApp Web existente. Padrão `true`. |
Quando só um método fica ativo, as abas não aparecem (vai direto para ele). Se
você desativar QR e telefone ao mesmo tempo, o SDK reativa os dois para não
deixar o modal sem forma de conectar.
**Limitações conhecidas (fora do nosso controle):** o pareamento via passkey depende de recursos da própria plataforma (Windows/Bluetooth), e não da Z-API.
* **Windows 10 (ou inferior):** não há suporte a pareamento de passkey via Bluetooth nem sincronização de passkeys em nuvem. Nesses casos, o sistema solicita uma "chave de segurança USB" física e o fluxo não avança. Como o Windows 10 saiu de suporte em out/2025, não há previsão de correção pela Microsoft. Esse recurso é exclusivo do **Windows 11**.
* **Dispositivos sem Bluetooth:** independentemente do sistema operacional, o pareamento com o celular não é possível sem Bluetooth.
***
## Fila de mensagens
Uma instância pode ter mensagens **na fila** (acumuladas enquanto esteve desconectada). Ao conectar, todas são enviadas de uma vez. Por isso, **antes de conectar**, o modal mostra quantas mensagens estão na fila e oferece a opção de **limpar** — evitando um disparo em massa no momento da conexão.
A contagem é atualizada automaticamente a cada 10 segundos enquanto o modal está aberto. Para esconder esse aviso, passe `showQueue: false`:
```js theme={"theme":{"light":"github-light","dark":"poimandres"}}
ZAPIConnector.open({ token, showQueue: false });
```
***
## Instância expirada
Se o período de uso da instância acabar, o WhatsApp deixa de aceitar a conexão. Nesse caso, em vez de um QR Code que não carrega, o modal mostra uma tela de **instância expirada**.
Reassinar é uma ação do **seu backend** (billing), então o botão **"Assinar novamente"** só aparece se você passar um callback `onSubscribe`. Ao clicar, o modal chama o seu callback — nele você dispara o seu fluxo de assinatura (chamar o seu backend, redirecionar para a página de planos, etc.):
```js theme={"theme":{"light":"github-light","dark":"poimandres"}}
ZAPIConnector.open({
token,
onSubscribe: () => {
window.location.href = "/planos";
},
});
```
Sem `onSubscribe`, a tela mostra apenas a mensagem de expiração. Em ambos os casos, o evento `status` é emitido com `"expired"`. Se a instância for reassinada com o modal ainda aberto, ele se reconecta sozinho.
***
## Eventos
Acompanhe o ciclo de vida da conexão com `on` / `off`:
```js theme={"theme":{"light":"github-light","dark":"poimandres"}}
ZAPIConnector.on("connected", () => atualizarInstancias());
ZAPIConnector.on("status", ({ status }) => console.log(status));
ZAPIConnector.off("connected", handler);
```
| Evento | Payload | Disparado quando |
| - | - | - |
| `connected` | `{ phone? }` | o canal conectou |
| `disconnected` | `{ reason? }` | caiu ou foi desconectado |
| `qr` | `{ base64 }` | um novo QR Code foi renderizado |
| `status` | `{ status }` | o status mudou (`"qr"`, `"connected"`, `"disconnected"` ou `"expired"`) |
| `error` | `{ error }` | ocorreu um erro |
| `close` | – | o usuário fechou o modal |
***
## Métodos
| Método | Retorno | Descrição |
| - | - | - |
| `open(options)` | `Promise` | Abre o modal; resolve quando ele fecha (`true` se conectou). |
| `close()` | `void` | Fecha o modal programaticamente. |
| `on(event, handler)` | `void` | Inscreve em um evento. |
| `off(event, handler)` | `void` | Cancela a inscrição. |
***
## Mensagens
Todo texto do modal pode ser sobrescrito por `messages`. Abaixo, cada chave, o valor padrão em português e para que serve. Passe apenas as chaves que quiser alterar.
### Tela inicial e QR Code
| Chave | Padrão | Descrição |
| - | - | - |
| `title` | Conecte seu WhatsApp | Título do modal |
| `subtitle` | Escaneie o QR code com seu celular para conectar. | Subtítulo abaixo do título |
| `step1` | Abra o **WhatsApp** no seu celular | Passo 1 das instruções do QR |
| `step2` | Toque em **Configurações** e depois em **Aparelhos conectados** | Passo 2 das instruções do QR |
| `step3` | Toque em **Conectar um aparelho** e escaneie este código | Passo 3 das instruções do QR |
| `qrLoading` | Gerando QR code… | Texto enquanto o QR carrega |
| `qrError` | Não foi possível carregar o QR code. Tente novamente. | Erro ao carregar o QR |
| `close` | Fechar | Rótulo (aria) do botão de fechar |
| `tabQr` | QR code | Rótulo da aba de QR Code |
| `tabPhone` | Número de telefone | Rótulo da aba de número de telefone |
### Conexão por número (web)
| Chave | Padrão | Descrição |
| - | - | - |
| `phoneHint` | Digite seu número do WhatsApp para receber um código de pareamento. | Instrução da aba de telefone |
| `countrySearch` | Buscar país | Placeholder da busca de país |
| `phonePlaceholder` | Número de telefone | Placeholder do campo de número |
| `submit` | Continuar | Botão para gerar o código |
| `phoneSending` | Gerando código… | Estado do botão enquanto gera |
| `codeHint` | Digite este código no WhatsApp: | Instrução acima do código de pareamento |
| `codeStep3` | Toque em **Conectar com número de telefone** e digite o código | Passo para inserir o código no WhatsApp |
| `codeBack` | Usar outro número | Voltar para digitar outro número |
### Fluxo de conexão por número (instâncias mobile)
| Chave | Padrão | Descrição |
| - | - | - |
| `mVerifying` | Verificando número… | Verificando o número informado |
| `mMethodHint` | Como quer receber o código? | Escolha do método de envio do código |
| `mSms` | SMS | Opção de receber por SMS |
| `mCall` | Ligação | Opção de receber por ligação |
| `mWhatsapp` | WhatsApp | Opção de receber pelo WhatsApp |
| `mSending` | Enviando… | Enviando o código |
| `mCodeHint` | Digite o código que você recebeu | Instrução para digitar o código recebido |
| `mWaOldHint` | Abra o WhatsApp no seu celular — você vai receber o código por lá. Digite-o abaixo. | Instrução do método WhatsApp |
| `mConfirm` | Confirmar | Botão de confirmar o código |
| `mConfirming` | Confirmando… | Estado enquanto confirma |
| `mCaptchaHint` | Digite os caracteres da imagem | Instrução do captcha |
| `mSecurityHint` | Digite seu PIN (verificação em duas etapas) | Instrução do PIN de duas etapas |
| `mForgotPin` | Esqueci o PIN | Link de recuperação de PIN |
| `mConfirmOnPhone` | Confirme no seu celular e toque em Confirmar | Confirmação no aparelho |
| `mError` | Algo deu errado. Tente novamente. | Erro genérico |
| `mWrongCode` | Código incorreto. Tente de novo. | Código digitado incorreto |
| `mBlocked` | Este número está bloqueado pelo WhatsApp. | Número bloqueado |
| `mUnblock` | Solicitar desbloqueio | Botão para solicitar desbloqueio |
| `mNoRoutes` | Não conseguimos enviar o código agora. Verifique o número e tente outro método. | Nenhuma rota de envio disponível |
| `mRateLimit` | Muitas tentativas. Aguarde um pouco antes de tentar de novo. | Limite de tentativas atingido |
| `mBanned` | Este número está banido. | Número banido |
| `mBannedText` | Descreva por que este número deve ser desbanido: | Texto do formulário de apelação |
| `mSend` | Enviar | Botão de enviar a apelação |
| `mInReview` | Seu pedido está em análise pelo WhatsApp. | Apelação em análise |
| `mPinSent` | Enviamos as instruções de recuperação do PIN. | Instruções de recuperação enviadas |
| `mPhoneOffline` | Celular offline — as mensagens podem atrasar. | Aviso de celular offline |
### Migração de sessão
| Chave | Padrão | Descrição |
| - | - | - |
| `migrateOr` | ou | Separador antes do link de migração |
| `migrateLink` | Clique aqui e migre uma conexão do WhatsApp Web já conectada pra cá | Botão que abre o fluxo de migração |
| `migrateHint` | Migre sua sessão do WhatsApp Web com a extensão. Use este código: | Instrução da tela de migração |
| `migrateStep1` | Instale a extensão **Z-API Conector** | Passo 1 da migração |
| `migrateStep2` | Abra o **web.whatsapp.com** já conectado no seu computador | Passo 2 da migração |
| `migrateStep3` | Abra a extensão e digite o **código acima** | Passo 3 da migração |
| `migrateBack` | Voltar | Voltar da tela de migração |
### Conectado
| Chave | Padrão | Descrição |
| - | - | - |
| `connectedTitle` | Conectado | Título da tela de sucesso |
| `disconnect` | Desconectar | Botão de desconectar a instância |
| `disconnecting` | Desconectando… | Estado enquanto desconecta |
### Autenticação por chave de acesso (extensão)
| Chave | Padrão | Descrição |
| - | - | - |
| `challengeText` | Confirme a autenticação no seu dispositivo para conectar esta instância. | Instrução da tela de autenticação |
| `challengeButton` | Resolver autenticação | Botão para resolver a autenticação |
| `challengeSolving` | Autenticando… | Estado enquanto autentica |
| `challengeCancel` | Cancelar | Cancelar a autenticação |
| `installTitle` | Autenticação por chave de acesso | Título da tela de instalação da extensão |
| `installText` | A extensão confirma sua biometria neste dispositivo para conectar. | Descrição da extensão |
| `installStep1` | Instale a extensão e adicione ao seu navegador | Passo 1 da instalação |
| `installStep2` | Volte para esta janela — a conexão segue **automaticamente** | Passo 2 da instalação |
| `installButton` | Instalar extensão | Botão genérico de instalar |
| `installChrome` | Instalar no Chrome | Botão de instalar no Chrome |
| `installFirefox` | Instalar no Firefox | Botão de instalar no Firefox |
| `unsupportedBrowser` | Abra esta página no Chrome ou no Firefox para conectar com chave de acesso. | Aviso em navegador sem suporte |
### Fila de mensagens
| Chave | Padrão | Descrição |
| - | - | - |
| `queueCountOne` | mensagem na fila | Rótulo quando há 1 mensagem na fila |
| `queueCountMany` | mensagens na fila | Rótulo quando há várias mensagens na fila |
| `queueClear` | Limpar fila | Botão para limpar a fila |
| `queueClearing` | Limpando… | Estado enquanto limpa a fila |
### Instância expirada
| Chave | Padrão | Descrição |
| - | - | - |
| `expiredTitle` | Instância expirada | Título da tela de instância expirada |
| `expiredText` | O período de uso desta instância acabou. Assine novamente para reconectar. | Texto da tela |
| `expiredButton` | Assinar novamente | Botão (aparece só com `onSubscribe`) |
***
## Teste no playground
Abra o [playground do SDK](https://app.z-api.io/demo.html) para gerar um token, ajustar tema, idioma e métodos, e ver o conector real funcionando.
# Introdução
Source: https://developer.z-api.io/quickstart/introduction
## Z-API - Asas para sua imaginação!
**Z-API** foi desenvolvido por **programadores para programadores**, por isso prezamos pela simplicidade e objetividade de tudo que nos propomos a fazer, sendo assim chega de conversa fiada e \*\* Let's Bora!\*\*
***
## Mas o que é Z-API?
Você provavelmente já deve saber, mas vamos reafirmar!
**Z-API** é um serviço RestFul que provê uma API que permite que você interaja com seu WhatsApp através de uma API simples e intuitiva, além de webhooks para te avisar sobre interações com seu número.
**Importante**
O Z-API reafirma que não é destinada para prática de SPAM e envio de mensagens indesejadas ou qualquer ação que viole os termos de serviço do WhatsApp.
Utilize a API com sabedoria criando funcionalidades que gere valor aos seus clientes e aos usuários do WhatsApp.
***
## Quem pode utilizar Z-API?
Não temos restrições quanto a utilização, mas geralmente são 2 públicos bem distintos que utilizam nossos serviços. São eles:
* Programadores com conhecimentos em API's RestFul. Se você não é, mas conhece alguém com estas competências, já serve :)
* Utilizadores de soluções de terceiros que permitam integração com Z-API
***
## Tá bom! Mas o que dá para fazer com ele?
De forma bem direta, tudo que você faz com WhatsApp Web você poderá fazer utilizando nosso serviço. Para isso basta ler o QRcode do Z-API e utilizar nosso serviço!
***
## Tecnicamente, como funciona o fluxo de envio?
Para exemplificar, segue os passos de envio de uma mensagem de texto simples:
1. Você envia via API uma mensagem para o Z-API;
2. O Z-API adiciona em uma fila e te retorna o ID da mensagem;
3. Sua instância processa a fila enviando para o WhatsApp;
4. Seu Webhook de delivery é chamado quando a mensagem é processada, te avisando que foi enviada ou que houve falha.
5. Assim que o destinatário receber a mensagem, o Webhook de message-status é chamado informando RECEIVED.
6. Por fim quando o destinatário ler a mensagem o messages-status é chamado informando READ
***
## Limites
Iniciei por este tópico porque é bem comum as pessoas perguntarem sobre quais os limites de envios com Z-API. Nós **NÃO TEMOS LIMITE** para número de mensagens enviadas! Mas é importante você entender que esta utilizando uma sessão do WhatsApp Web, então o padrão de utilização precisa ser compatível, além disso sempre recomendamos que você leia atentamente as políticas estabelecidas pelo proprio WhatsApp em sua pagina oficial [https://www.whatsapp.com/legal](https://www.whatsapp.com/legal).
***
**NÃO ARMAZENAMOS MENSAGENS!**
Todas as mensagens enviadas para nossa API serão encaminhadas para uma fila de mensageria e após o envio as mesmas são apagadas.
**Lembre-se**
O Facebook tem comportamentos diferentes para cada uma das versões do WhatsApp, nossa API disponibiliza métodos compativeis com a versão WEB.
# Token de segurança da conta
Source: https://developer.z-api.io/security/client-token
Utilize a validação por token para adicionar uma camada de proteção às suas instâncias
## Token de Segurança da Conta
Esse método de segurança da Z-API utiliza a validação por token, proporcionando uma camada adicional de proteção para suas instâncias, garantindo que apenas solicitações autorizadas tenham acesso aos seus recursos.
***
## Ativando o recurso
Para habilitar o recurso de validação por token, siga estas etapas simples:
Acesse o painel da Z-API com suas credenciais.
Localize o módulo "Token de Segurança da Conta".
Isso gerará um token, que inicialmente estará desabilitado para evitar interrupções na operação da sua aplicação.
***
## Funcionamento básico
O funcionamento do método de segurança por token é direto:
1. Após a geração do token, ele deve ser incluído na header de todas as suas requisições HTTP.
2. O token deve ser passado da seguinte forma:
* **Atributo:** `Client-Token`
* **Valor:** `[token]`
3. Após configurar seu ambiente para enviar o token nas requisições, você pode clicar em "Ativar Token".
4. A partir deste momento, todas as instâncias da sua aplicação só aceitarão requisições que contenham o token na header.
### Comportamento do token não cadastrado
Caso uma requisição seja feita sem o token configurado, a API responderá com um erro, conforme o exemplo abaixo:
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"error": "null not allowed"
}
```
***
## Benefícios da validação por token
A validação por token garante que apenas requisições autorizadas acessem suas instâncias, adicionando uma barreira extra contra acessos indevidos.
Você decide quando ativar o token, podendo configurar todo o seu ambiente antes de habilitar a validação, evitando interrupções.
# Proteção Anti-Golpe em Grupos de Avisos
Source: https://developer.z-api.io/security/fraud-protection
A Proteção anti-golpe em grupos de avisos apaga automaticamente, para todos, as mensagens enviadas por golpistas (participantes que não são administradores) nos seus grupos de avisos de comunidade — aqueles em que só administradores podem enviar mensagens. Quando a proteção apaga uma mensagem, você recebe um aviso no seu webhook com os dados de quem enviou, para decidir o que fazer com o autor (por exemplo, removê-lo do grupo).
* É configurável por instância e vem desligada por padrão.
* Para funcionar, a instância precisa ser administradora do grupo.
## 1. Habilitar / desabilitar via API (novo endpoint)
Na Proteção Anti-Golpe em Grupos de Avisos, a habilitação ou desabilitação do recurso também pode ser realizada via API, utilizando o endpoint específico disponibilizado para essa configuração.
Para mais detalhes sobre a utilização do endpoint, consulte a documentação abaixo.
🔗 [https://developer.z-api.io/instance/update-announcement-guard](https://developer.z-api.io/instance/update-announcement-guard)
## 2. Consultar o estado atual (endpoint existente /me)
Após realizar a configuração da Proteção Anti-Golpe, você pode consultar o estado atual da funcionalidade diretamente pela API. Essa consulta permite verificar as configurações aplicadas à instância e identificar se a proteção está devidamente habilitada.
```
GET https://api.z-api.io/instances/{instanceId}/token/{token}/me
```
A resposta agora inclui o campo novo:
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"announcementGuard": true
}
```
O campo retorna TRUE quando o recurso está ativo e FALSE quando a funcionalidade está desabilitada.
## 3. Habilitar via painel
No painel da instância, na seção “Segurança nos grupos de avisos”, está disponível a opção “Proteção anti-golpe em grupos de avisos”.
A ativação ou desativação dessa chave possui o mesmo efeito da utilização do endpoint descrito nesta documentação anteriormente, permitindo gerenciar o recurso diretamente pelo painel. Após realizar a alteração, basta utilizar o botão padrão de salvar da tela para aplicar a nova configuração.
## 4. O que você recebe quando a proteção age (webhook)
Quando a Proteção Anti-Golpe remove uma mensagem identificada como tentativa de golpe, um evento é enviado normalmente pelo webhook de recebimento (**ReceivedCallback**), utilizando o evento já existente de “mensagem revogada/apagada”.
Para identificar que a mensagem foi removida especificamente pela proteção, basta verificar o campo **NotificationParameters** presente no payload do webhook.
Como identificar:
* notificationParameters: **\["ANNOUNCEMENT\_GUARD"]** → a mensagem do golpista foi apagada com sucesso pela proteção.
* notificationParameters: **\["ANNOUNCEMENT\_GUARD\_FAILED", "\[MOTIVO]"]** → a proteção tentou apagar, mas falhou (a mensagem pode continuar visível). Possíveis motivos:
| Motivo | Significado |
| :- | :- |
| `TIMEOUT_EXCEEDED` | Tempo esgotado ao tentar apagar a mensagem. |
| `MISSING_GROUP_PERMISSION` | A instância não é administradora do grupo ou não possui permissão para apagar mensagens. |
| `GROUP_SUSPENDED` | O grupo está suspenso. |
| `SOMETHING_WENT_WRONG` | Ocorreu uma falha genérica durante a tentativa de remoção. |
## Retorno do webhook
Atributos do retorno
Todos os retornos deste webhook possuem os seguintes atributos:
Indica o tipo de notificação recebida. Para mensagens apagadas, o valor será `"REVOKE"`.
Identifica que a remoção da mensagem foi realizada pela Proteção Anti-Golpe.
Identifica o grupo onde ocorreu a remoção da mensagem.
Nome do grupo onde ocorreu a remoção.
Identificador da mensagem que foi apagada.
Número de telefone do autor da mensagem removida.
Identificador LID do autor da mensagem.
Nome do autor da mensagem, quando disponível.
Indica se a mensagem pertencia à própria instância. Neste caso, o valor será false.
Indica que a ação foi realizada pela plataforma. Neste caso, o valor será true.
Exemplo de payload:
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"isGroup": true,
"instanceId": "SEU_INSTANCE_ID",
"messageId": "3EB0...",
"phone": "120363XXXXXXXXXXX-group",
"connectedPhone": "5544XXXXXXXXX",
"fromMe": false,
"fromApi": true,
"momment": 199999999,
"status": "RECEIVED",
"chatName": "Nome do Grupo de Avisos",
"senderName": "Nome do Autor",
"participantPhone": "5544XXXXXXXXX",
"participantLid": "XXXXXXXXXXXXXXX@lid",
"type": "ReceivedCallback",
"notification": "REVOKE",
"notificationParameters": ["ANNOUNCEMENT_GUARD"]
}
```
## 5. O que fazer com o evento
Com o participantPhone (ou participantLid) recebido no evento, você pode utilizar o endpoint de remoção de participante do grupo, já disponível na API, para remover o autor da mensagem.
A Proteção Anti-Golpe não remove o participante automaticamente. A decisão de remover ou não o autor fica sob seu controle, permitindo que você defina o comportamento da sua aplicação de acordo com a sua necessidade.
## 6. Observações
* A proteção atua somente quando a instância está conectada e possui privilégios de administradora no grupo.
* O recurso é aplicável exclusivamente a grupos de avisos de comunidades, nos quais apenas administradores podem enviar mensagens. Ele não atua em grupos comuns nem em conversas individuais.
* Mensagens enviadas por administradores não são afetadas pela proteção.
* Cada mensagem é processada individualmente. Portanto, cada revogação gera um evento próprio no webhook. Caso o mesmo autor envie várias mensagens, cada mensagem será revogada e gerará um novo evento.
* O autor da mensagem não é removido automaticamente do grupo. Enquanto permanecer no grupo, ele poderá enviar novas mensagens. Cada nova tentativa identificada pela proteção será tratada individualmente, gerando uma nova revogação e um novo evento no webhook.
***
# ID e Token
Source: https://developer.z-api.io/security/introduction
Entenda como funciona a autenticação na Z-API
## O que é e para que serve?
Para comunicação entre API's vamos precisar estabelecer um protocolo de segurança entre as partes, sendo assim toda interação que você fizer com a Z-API vai precisar informar seus atributos de autenticação. Esses atributos vão compor a URL de integração com a Z-API, como no exemplo abaixo:
```
https://api.z-api.io/instances/SUA_INSTANCIA/token/SEU_TOKEN/send-text
```
***
## Como consigo meu ID e Token?
Após criar sua conta na Z-API e criar uma instância, você terá duas informações que identificam e protegem a comunicação entre sua aplicação e a Z-API. Para acessar e visualizar os dados da sua instância, basta clicar em editar na instância desejada dentro do painel administrativo. Você pode ter múltiplas instâncias, cada uma com credenciais únicas.
Nunca compartilhe o seu ID e token com ninguém, pois qualquer pessoa que tiver essas informações poderá enviar mensagens em seu nome. Suas chamadas de API devem ser feitas a partir de um servidor, nunca do frontend, para evitar a exposição dos seus dados de autenticação.
# Restrição de chamadas por IP
Source: https://developer.z-api.io/security/ip-block
Restrinja as chamadas feitas à API com base nos endereços IP dos solicitantes
## Restrição de IPs
O método de segurança de bloqueio por IP introduz uma camada adicional de proteção, permitindo aos usuários restringir as chamadas feitas à API com base nos endereços IP dos solicitantes.
Isso significa que você pode controlar quais IPs têm permissão para acessar sua API e quais são bloqueados.
***
## Ativando o recurso
Para ativar esse recurso, siga os passos simples abaixo:
Acesse o painel de controle da Z-API com suas credenciais de administrador.
No painel da Z-API, encontre a opção "Segurança" no menu de navegação ou na área de configurações.
***
## Funcionamento básico
Quando o módulo de Restrição de IPs não está ativado, a API funciona normalmente e permite o acesso de qualquer endereço IP que faça uma solicitação.
### Comportamento de IP não cadastrado
Quando uma solicitação é feita a partir de um endereço IP que não está na lista de IPs permitidos, a API responde com uma mensagem de erro clara:
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"error": "[IP da chamada] not allowed"
}
```
***
## Benefícios do bloqueio por IP
Com essa funcionalidade, você tem controle total sobre quem pode acessar a sua API.
A restrição de IPs ajuda a proteger sua API contra acessos não autorizados.
Para empresas que precisam cumprir regulamentos rigorosos de segurança.
# Autenticação de dois fatores
Source: https://developer.z-api.io/security/twofactor
Adicione uma camada extra de segurança ao painel da Z-API com autenticação de dois fatores
## Segurança de Dois Fatores
A implementação de uma etapa adicional de autenticação, conhecida como autenticação de dois fatores (2FA), é uma camada vital de segurança para proteger o painel da Z-API contra acessos não autorizados e ameaças cibernéticas.
***
## Ativando o recurso
Faça login no painel da Z-API com suas credenciais.
No painel da Z-API, encontre a opção "Segurança" no menu de navegação.
Localize a opção "Autenticação de Dois Fatores" e clique em "Configurar Agora". Um QR code será gerado para sincronização com aplicativos autenticadores como 1Password, Google Authenticator ou Microsoft Authenticator.
***
## Funcionamento
Após configurar, siga o fluxo abaixo para autenticar:
1. Abra o aplicativo autenticador no seu celular.
2. Adicione a conta manualmente ou escaneie o QR code gerado.
3. Vincule a conta da Z-API ao seu dispositivo.
4. Cada vez que você fizer login no painel Z-API, será solicitado que você forneça um código de uso único gerado pelo aplicativo autenticador.
5. O código se regenera a cada poucos segundos e é único por conta.
***
## Benefícios do uso do 2FA
A senha sozinha não é suficiente para acessar o painel. Mesmo que alguém descubra sua senha, ainda precisará do código gerado pelo autenticador.
O acesso requer a posse do dispositivo móvel vinculado, dificultando significativamente tentativas de acesso não autorizado.
Protege informações confidenciais armazenadas no painel da Z-API com uma camada extra de verificação.
Atende aos requisitos de segurança exigidos pela indústria e regulamentações vigentes.
# Z-API vs API Oficial
Source: https://developer.z-api.io/tips/Z-APIvsAPI-OFICIAL
## As Diferenças do Z-API e o WhatsApp Business API.
Qual é a melhor alternativa para você?
Exemplificando o uso da API do WhatsApp: O WhatsApp no início da ferramenta como uma das suas decisões estratégicas optou por manter sua API fechada, bem diferente do que aconteceu com outros players mundiais do segmento. Ou seja, os desenvolvedores não tinham a oportunidade de integrar suas soluções e tecnologias de softwares ao WhatsApp.
Principalmente nesse cenário estamos falando de empresas com soluções diversas no mercado, como por exemplo: Sistemas CRM e ERP, criação de bots de chat populares e até empresas de e-commerce ou do varejo para o serviço de notificação em tempo real do status de compras de um cliente. Nesse período também muitos DEV'S criavam ou procuravam gateways personalizados que poderiam fornecer esse acesso ao WhatsApp API. Essas soluções ainda podem ser encontradas no github. O problema com o uso dessas bibliotecas é que WhatsApp faz atualizações no qual torna as soluções desatualizadas e, como regra, ao usar essas bibliotecas os números eram imediatamente banidos.
Com o tempo, as empresas estão cada vez mais conscientes do quanto utilizar de uma API como essa pode facilitar e alavancar muito o seu negócio, sem contar as inúmeras possibilidades de criação.
Todos sabem que esse mercado é gigantesco, mas vamos nos aprofundar em números, além do mensageiro mais utilizado no mundo com 1,7 bilhão de usuários hoje a grande parte dos negócios acontece na ferramenta. Algumas das razões pelo qual muitos negócios estão utilizando, o usuário pode centralizar tudo em um só canal, mais praticidade, agilidade para gerir seus negócios em um só lugar, contato mais próximos e muita praticidade. As empresas começaram a surgir no mercado oferecendo sua API para funcionar com WhatsApp. Como regra, todos funcionam com base no protocolo WhatsApp WEB. E claro, o Z-API também fornece WhatsApp API. Desenvolvemos nossa solução em 2019, quando nos integramos a uma solução Brasileira, logo inúmeros DEV'S e parceiros de negócios em diversos lugares do mundo também iniciaram o processo de integração conosco.
O propósito da nossa solução sempre deixamos bem claro e temos levado para todos os lugares "Z-Api, Asas para a sua imaginação". Nós queremos dar a possibilidade para DEV'S, soluções tecnológicas e Software houses a desenvolverem produtos e negócios extraordinários com a melhor tecnologia do mercado, um atendimento de qualidade, uma solução brasileira, paga em real e que te dá liberdade para criar.
Em 2017, WhatsApp abriu o acesso à sua API oficial. No início, WhatsApp API oficial foi testada a portas fechadas e apenas algumas empresas globais podiam pagá-la. Mas, com o tempo, mais e mais organizações obtiveram acesso ao WhatsApp API oficial.
A ordem de cooperação é tal que, para se conectar à API oficial, você precisará coordenar a conexão com os parceiros oficiais do WhatsApp. Ou seja, você precisará trabalhar com intermediários que são projetados para fornecer uma API e moderar suas atividades sob os regulamentos atuais do WhatsApp. Isso implica um grande número de restrições, que serão exibidas na tabela na parte inferior. Você pode conferir a lista de parceiros oficiais atuais aqui: [https://www.facebook.com/business/partner-directory/search?solution\_type=messaging](https://www.facebook.com/business/partner-directory/search?solution_type=messaging). Isso é muito importante porque agora algumas empresas estão enganando seus clientes, chamando-se de parceiros oficiais do WhatsApp.
Nesse caso então o correto é usar a API Oficial? Vamos analisar com calma. A primeira coisa a decidir é: para que você precisa de uma API? Ambas as opções terão vantagens e desvantagens. WhatsApp API claramente tem mais notoriedade, principalmente com sua "oficialidade" e segurança. No entanto, existem várias limitações significativas devido às quais nem todas as empresas poderão trabalhar com a API oficial. Nós os destacaremos separadamente:
***
## Desvantagens da API Oficial:
A taxa de adesão pode chegar de centenas a milhares de dólares, sem contar os custos de conexão e taxas por mensagem individual — ditados pelo próprio WhatsApp em moeda corrente.
É necessário volume mínimo de 15.000 mensagens mensais, o que não é viável para todas as empresas.
O WhatsApp não aprova parcerias com determinados setores. Empresas que vendem vitaminas ou medicamentos, por exemplo, não obtêm aprovação.
Coletar documentos, aprovar inspeções e desenvolver modelos pode levar tempo significativo — e ainda terminar em falha.
Dependência do dispositivo físico para funcionamento.
Suspensão e bloqueio do número, além de atraso em receber atualizações da plataforma.
***
## Vantagens da API Oficial:
O WhatsApp permite responder rapidamente às mensagens, com aumento no retorno e engajamento por parte dos consumidores.
As empresas conseguem enviar mensagens personalizadas, aviso de promoções, informações e novidades.
A integração do app com outros sistemas inclui todas as informações presentes em cada um deles, evitando a perda de dados importantes.
Dependendo do programa integrado, é possível extrair dados relevantes sobre o atendimento na plataforma.
***
**Já pensou, ser banido pelo WhatsApp?**
Segundo algumas estatísticas do WhatsApp, o messenger bloqueia cerca de 2.000.000 de usuários por mês que violam os termos da política do WhatsApp.
Mas isso não significa que API's não oficiais sejam irresponsáveis com seus clientes. Por exemplo, o Z-API para segurança do usuário fornece aos clientes IPs individuais, executa autorização segura e insere um sistema de protetores artificiais, como uma fila para enviar mensagens para evitar envios em massa e protegê-los de banimento.
Também existem sistemas para emular um telefone em um computador para que o trabalho não dependa de um dispositivo físico. Claro, esses métodos não ajudarão se o usuário negligenciar as regras para trabalhar com clientes de WhatsApp e spam. Mesmo com a API oficial, é possível ser banido por violar as políticas do WhatsApp. Mas se você combinar as ferramentas de segurança da Z-API com o uso dentro das recomendações do WhatsApp.
Depois de analisar os pontos principais, você pode ir direto ao mais interessante, ou seja, a análise, e comparar qual a solução te atende melhor com o WhatsApp. Vamos começar com os benefícios do Z-API:
***
## Comparativo
| Característica | ✅ Z-API | ❌ Business API |
| :- | :- | :- |
| **Números** | Funciona com qualquer número pessoal ou comercial existente | Só funciona com novos números dedicados |
| **Início de uso** | Pode começar imediatamente após registrar o número | O número deve funcionar pelo menos 3-4 semanas |
| **Disponibilidade** | Disponível para todas as categorias de clientes | Disponível apenas para empresas de médio e grande porte |
| **Conteúdo** | Você pode enviar qualquer conteúdo (sem infringir a lei) | Os modelos de postagem devem ser pré-aprovados |
| **Custo** | Mensagens ilimitadas por uma taxa fixa | O custo das mensagens pode chegar a \~\$0,07 por mensagem |
| **Registro** | Sem condições e registro fácil | Conformidade estrita e processo de implementação abrangente |
| **Integração** | API JSON simples e Webhooks, integração em apenas 10 minutos | Requer servidor dedicado e arquitetura complexa, mínimo 2-4 semanas |
| **Permissão** | A permissão não é necessária, você pode escrever primeiro | A permissão do assinante é necessária para recebimento de mensagens |
| **Burocracia** | Você pode começar imediatamente | Processo burocrático que pode demorar pelo menos um mês |
| **Quantidade de números** | Você pode usar números em qualquer quantidade | Apenas um número por empresa verificada |
| **Suporte** | Suporte direto 24/7 via e-mail e chats com nossa equipe | Suporte limitado (suporte pago por meio de parceiros) |
| **Personalização** | Possibilidade de fazer qualquer modificação e integração | Incapacidade de influenciar e adicionar funcionalidade |
| **Nome da conta** | Qualquer nome da sua conta | Nome imutável (por nome comercial) |
| **Cobertura** | Pode trabalhar em todo o mundo | Não disponível em alguns países (ex: Crimeia, Irã) |
| **Moeda** | Pagamento em Reais | Pagamento em dólar |
| **Origem** | Ferramenta totalmente Brasileira +5 milhões de mensagens diárias | Ferramenta Americana, comunicação em inglês |
# Guia de Boas Práticas para Uso do WhatsApp via API
Source: https://developer.z-api.io/tips/best-practices
## Introdução
Este guia reúne recomendações práticas para reduzir o risco de bloqueios, restrições ou banimentos ao utilizar o WhatsApp por meio de integrações via API. Seguir essas boas práticas é fundamental para manter a saúde do número, melhorar a entregabilidade das mensagens e reduzir os riscos de bloqueios ou restrições por parte do WhatsApp.
É importante destacar que não existe uma configuração que garanta 100% de proteção contra bloqueios, pois as políticas e algoritmos do WhatsApp são internos e podem mudar ao longo do tempo. O objetivo dessas práticas é reduzir riscos e melhorar o comportamento do número na plataforma.
### 1. Mantenha comportamento natural do número
Um dos principais fatores analisados pelo WhatsApp é o comportamento do número.
Números que aparentam ser utilizados apenas para automação ou disparos têm maior risco de restrições.
**Boas práticas:**
* Utilizar o número ocasionalmente no celular
* Realizar conversas reais com contatos
* Participar de grupos
* Enviar e responder mensagens manualmente de vez em quando
* Realizar chamadas de voz e videochamadas
* Enviar mídias (imagens, vídeos, áudios e documentos)
* Evitar que o número seja utilizado apenas por automações
Esse comportamento ajuda a plataforma a identificar o número como um usuário real, e não apenas um sistema automatizado, demonstrando que ele está sendo utilizado de forma legítima por uma pessoa ou empresa real.
### 2. Evite grandes volumes de envio sem interação
O WhatsApp analisa o equilíbrio entre:
* Mensagens enviadas
* Mensagens recebidas
Quando um número envia muitas mensagens e recebe poucas respostas, esse comportamento pode ser identificado como spam.
**Boas práticas:**
* Estimular respostas do usuário
* Criar mensagens que incentivem interação
* Evitar envios unidirecionais constantes
* Não enviar mais mensagens do que o número costuma receber
**Limite o volume diário:**
Como referência, se o número recebe cerca de 50 mensagens por dia, limite os envios ativos a aproximadamente 40 mensagens diárias. Aumente o volume gradualmente conforme o histórico e a reputação do número evoluem.
### 3. Incentive a interação dos clientes
Criar oportunidades para o cliente interagir com a mensagem ajuda a reduzir o risco de bloqueios.
**Estratégias:**
* Incluir perguntas nas mensagens
* Oferecer botões de resposta
* Pedir confirmação
* Solicitar feedback
* Facilitar a resposta do cliente
Cada interação recebida contribui para manter o equilíbrio entre envio e recebimento de mensagens.
### 4. Ofereça opção de descadastro
Sempre que possível, permita que o cliente informe que não deseja mais receber mensagens.
**Exemplo:**
"Caso não queira mais receber mensagens, responda SAIR."
**Benefícios:**
* Reduz denúncias de spam
* Evita bloqueios diretos do número
* Melhora a qualidade da base de contatos
### 5. Varie o conteúdo das mensagens
Evite enviar sempre o mesmo texto para todos os contatos.
Alterar apenas variáveis como:
* Nome
* Data
* Valor
não é suficiente.
**Boas práticas:**
* Crie pelo menos cinco variações diferentes da mesma mensagem (ex.: Mensagem A, B, C, D e E), mantendo o mesmo objetivo mas alterando a estrutura e a redação dos textos
* Utilize blocos de randomização nos fluxos para que os contatos não recebam exatamente o mesmo conteúdo
* Mude a estrutura das frases e varie o vocabulário
* Sempre se apresente logo no início da mensagem, informando o nome da pessoa ou da empresa
* Personalize a comunicação utilizando o nome do contato sempre que possível
* Utilize diferentes formatos de comunicação (texto, imagem, áudio, vídeo)
**Exemplo:**
❌ "Olá! Temos uma oferta para você."
✅ "Olá, João! Aqui é a equipe da Empresa X. Gostaríamos de apresentar uma oportunidade que pode ajudar seu negócio."
Em vez de repetir sempre a mesma mensagem, utilize diferentes formas de transmitir a mesma informação. Isso torna as mensagens mais naturais, reduz a repetição de conteúdo e diminui o risco de o WhatsApp identificar comportamento automatizado.
### 6. Utilize intervalos entre mensagens
Envios contínuos e rápidos, ou disparos em massa com grande volume simultâneo, aumentam o risco de bloqueio.
**Boas práticas:**
* Utilizar intervalos entre mensagens, distribuindo os envios ao longo do tempo
* Como ponto de partida, recomenda-se um intervalo mínimo de 5 minutos entre os disparos
* Conforme o número ganha histórico e reputação, os intervalos podem ser reduzidos gradualmente
* Evitar disparos muito rápidos
Em alguns casos observados, intervalos maiores (como alguns minutos entre mensagens) apresentam melhor estabilidade. Isso reduz o risco de bloqueios, melhora a taxa de entrega e torna o comportamento do número mais natural.
### 7. Simule comportamento humano nas mensagens
Algumas práticas ajudam a tornar o envio mais natural.
**Exemplos:**
* Simular indicador de digitação
* Evitar respostas sempre instantâneas
* Aplicar delays entre ações
Esse tipo de comportamento reduz a percepção de automação total.
### 8. Defina horários adequados de funcionamento
Configure os envios para ocorrerem dentro de horários comerciais ou em períodos adequados ao seu público.
**Evite:**
* Madrugada
* Horários de baixa interação
* Períodos que possam gerar desconforto ao destinatário
**Benefícios:**
* Melhor experiência para os contatos
* Maior taxa de resposta
* Menor probabilidade de denúncias e bloqueios
### 9. Separe números de atendimento e disparo
Uma estratégia comum é separar funções entre números.
**Exemplo:**
* Número 1: Atendimento ao cliente
* Número 2: Envio de notificações ou campanhas
**Benefícios:**
* Protege o número principal da empresa
* Reduz o impacto em caso de restrições
* Melhora a organização do uso do canal
### 10. Mantenha a maturação do número
Números recém ativados ou pouco utilizados podem ter maior sensibilidade a restrições.
**Boas práticas:**
* Iniciar o uso de forma gradual
* Aumentar o volume aos poucos
* Manter conversas reais ao longo do tempo
* Trocar mensagens manualmente com contatos reais
* Participar de grupos de WhatsApp
* Compartilhar imagens, vídeos e áudios
* Responder conversas de forma natural
Esse processo é conhecido como aquecimento ou maturação do número.
Se o número possui aproximadamente 50 conversas frequentes, recomenda-se iniciar com cerca de 10 envios ativos por dia e aumentar gradualmente.
Para números recém desbanidos, recomendamos realizar a maturação por cerca de 3 a 5 dias antes de conectar novamente à API, simulando comportamento humano: interagir em grupos, enviar e receber mensagens, salvar contatos, entre outros.
### 11. Entenda que bloqueios podem ocorrer mesmo seguindo boas práticas
Mesmo aplicando todas as recomendações, bloqueios ainda podem acontecer.
Isso ocorre porque:
* O WhatsApp utiliza algoritmos internos
* As políticas podem mudar
* O comportamento dos usuários também influencia
Por esse motivo, o foco deve ser sempre reduzir riscos e manter um uso saudável da plataforma.
### Resumo das principais recomendações
* Mantenha o número com comportamento natural (conversas reais, grupos, chamadas)
* Equilibre mensagens enviadas e recebidas; não envie mais do que o número costuma receber
* Ofereça sempre uma opção de descadastro
* Crie pelo menos 5 variações de cada mensagem e utilize randomização nos fluxos
* Personalize as mensagens com o nome do contato e identifique a empresa
* Configure intervalos entre os envios (mínimo recomendado: 5 minutos)
* Limite o volume diário de mensagens e aumente gradualmente
* Envie mensagens em horários apropriados, evitando madrugada
* Separe números de atendimento e de disparo/campanhas
* Faça o aquecimento (maturação) do número antes de iniciar campanhas
### Conclusão
O uso sustentável do WhatsApp depende principalmente de boas práticas de comunicação e do comportamento do número.
Os principais pilares para reduzir bloqueios são:
* Comportamento natural do número
* Equilíbrio entre envio e recebimento
* Variação de conteúdo
* Estímulo à interação do cliente
* Uso responsável de automações
* Aquecimento e maturação do número
Seguindo essas práticas, é possível reduzir significativamente a frequência de bloqueios e melhorar a estabilidade das operações no WhatsApp.
# Bloqueios e Banimentos
Source: https://developer.z-api.io/tips/blockednumber
**Existe alguma possibilidade do WhatsApp bloquear meu número?**
**SIM, A POSSIBILIDADE EXISTE, E É REAL.**
***
## Introdução
### Boas práticas!
Criamos este tópico para compartilhar um pouco de tudo que aprendemos sobre boas práticas afim de evitar aborrecimentos com bloqueios e banimentos no WhatsApp.
Gostaríamos de iniciar fazendo a seguinte reflexão com você: É bem provável que você receba diariamente vários SMS com publicidades de lojas, promoções, operadoras de telefonia e por aí vai.
Agora pense, e pelo WhatsApp quantas mensagens deste tipo você recebe? Provavelmente nenhuma ou pouquíssimas não é mesmo? Mesmo assim caso você receba o WhatsApp permite você marcar como spam e até mesmo bloquear o contato.
# O WHATSAPP NÃO PERMITE SPAM!
O WhatsApp é muito rigoroso quando o assunto é envio de spam e por isso damos mais atenção para ele do que para o SMS. Por que deixamos vários SMS acumularem e não conseguimos deixar de olhar para o celular imediatamente ao receber um WhatsApp? Pois sabemos que recebemos um WhatsApp de algum contato conhecido e raramente recebemos promoções pelo mesmo.
***
## Quantas mensagens posso enviar?
Quantidade é algo importante sim, mas não é só sobre a quantidade enviada, o fator *PARA QUEM* muitas vezes é o ponto chave.
Sempre em nossas conversas utilizamos o case de um dos nossos clientes mais antigos, que hoje envia mensagens promocionais pelo WhatsApp para mais de 80 mil pessoas diariamente e nunca teve seu número bloqueado. Quando o procuramos e indagamos sobre como ele conseguia tal façanha, ele gentilmente compartilhou a seguinte técnica:
1. Fazer maturação do chip: Isso significa usar o número de telefone no WhatsApp de maneira normal antes de começar a enviar muitas mensagens através do Z-API.
2. Interagir pelo celular ou WhatsApp Web antes de conectar na Z-API: Isso ajuda a mostrar para o WhatsApp que você é um usuário real e não um bot.
3. Ter um texto que induza o usuário a responder as mensagens: Isso ajuda a mostrar para o WhatsApp que você está tendo conversas reais com as pessoas.
4. Oferecer uma opção para o usuário não receber mais as mensagens caso não queira: Isso é importante para respeitar a privacidade dos usuários e evitar denúncias.
5. Ter os dados do perfil preenchidos no WhatsApp: Isso ajuda a mostrar para o WhatsApp que você é um usuário legítimo.
6. Ler o QR code após 24 horas de registrar no WhatsApp: Isso ajuda a confirmar que você é um usuário real.
Forma de envio:
* Primeiro: Para receber mensagem com promoções o destinatário precisa adicionar o número da empresa nos contatos e enviar uma mensagem dizendo "quero promoções". Esta simples ação diminui significantemente o risco de bloqueios, pois com o seu número na agenda e iniciando a conversa os botões de bloqueio e denúncia de spam não aparecem;
* Segundo: Ele personaliza as mensagens com dados do destinatário, para que todas mensagens não fiquem exatamente iguais;
* Terceiro: sempre dê uma opção para o destinatário deixar de receber as mensagens. Exemplo: "Digite 2 para não receber mais estas mensagens", com isso ele monitora os webhooks para retirar os números que não querem mais receber da lista de envios.
**Resumo**
* Evite enviar mensagens para quem não tem seu número nos contatos;
* Personalize as mensagens com informações do destinatário. Se não for possível, use atributos aleatórios para diferenciar cada mensagem;
* Tente convencer o destinatário a interagir com seu número, principalmente se você souber que ele não possui seu número na agenda;
* Ofereça a opção do destinatário não receber mais mensagens e monitore os webhooks para tratar essas interações.
**Cuidado**
Se 3% dos destinatários marcarem sua mensagem como spam seu número será banido!
# Bloqueios e Banimentos (2026)
Source: https://developer.z-api.io/tips/blockednumbernew
## Introdução
A discussão sobre banimentos no WhatsApp envolvendo IPs, ASN e números de telefone é complexa e envolve múltiplas variáveis. Nos últimos quatro anos, realizamos diversos testes tanto com o WhatsApp Web (gerador do QR Code) quanto com o dispositivo conectado a esse QR Code.
O que aprendemos nesse período é que, embora o IP e ASN tenham alguma relevância, eles não são os principais fatores que determinam um banimento. Tanto que já implementamos uma estratégia de rotação de IPs em ciclos de 15, 30, 45 e 60 dias, e essa ação isolada não apresentou impacto significativo na redução de bloqueios.
## Principais Fatores que Influenciam o Banimento
### 1. Eventos Globais e Volume de Fake News
Momentos de alta repercussão midiática, como eleições, crises políticas e disseminação de fake news, impactam diretamente na taxa de banimentos. Sempre que há um grande evento na mídia, notamos um aumento percentual na quantidade de contas banidas, independentemente do IP, ASN ou método de conexão. Isso sugere que o WhatsApp intensifica a moderação nesses períodos.
### 2. Conteúdo da Mensagem e Palavras-Chave Sensíveis
O WhatsApp possui um algoritmo avançado que analisa padrões de conteúdo. Mensagens cujo teor é de interesse exclusivo do remetente (ou seja, que não geram interações naturais) são alvos de análise.
Tópicos financeiros têm um risco maior de bloqueio, especialmente quando contêm palavras-chave como "boleto", "PIX", "cartão", e outras associadas a golpes financeiros. A recorrência dessas palavras pode ativar mecanismos automáticos de verificação, aumentando o risco de restrições.
### 3. Uso de Números Recentes e Envio em Massa
Números novos enviando mensagens para muitos destinatários diferentes em um curto período são facilmente identificados como suspeitos. Esse comportamento pode ser simulado diretamente no app do WhatsApp, sem necessidade de APIs ou plataformas externas. Diversos relatos indicam que números recém-ativados estão sendo banidos rapidamente, mesmo sem uso de ferramentas automatizadas.
### 4. Reciclagem de Números e Histórico de Uso
A alta rotatividade de números reciclados pode ser benéfica ou prejudicial, dependendo do histórico do número. Se o número já foi utilizado para atividades suspeitas no passado, pode ser rapidamente banido logo após a leitura do QR Code ou com um volume reduzido de mensagens enviadas.
### 5. Volume de Mensagens x Número de Destinatários
O fator mais relevante para o banimento é a quantidade de destinatários únicos, e não apenas a quantidade total de mensagens enviadas. Quanto mais contatos diferentes um número tentar alcançar em um curto período, maior a chance de ser classificado como spam.
### 6. Reutilização de Padrões em Números Substitutos
Uma prática comum após um banimento é configurar um novo número exatamente da mesma forma que o anterior. O WhatsApp consegue identificar isso, principalmente se o novo número mantiver o mesmo nome, foto, descrição e padrões de mensagens.
Para mitigar esse risco, recomenda-se:
* ✅ Alterar a foto de perfil antes de ativar o número.
* ✅ Modificar a descrição e o nome do contato antes de iniciar o uso.
* ✅ Fazer pequenas mudanças no comportamento inicial do envio para evitar padrões repetitivos.
Isso pode ajudar a evitar que o WhatsApp associe o novo número ao número anteriormente banido, reduzindo o risco de um bloqueio imediato.
## Testes e Comparação com Anos Anteriores
Trabalhamos tanto com a API oficial do WhatsApp quanto com a versão web para nossos testes. O mais surpreendente é que, em muitos casos, apenas conectar um número novo à plataforma já pode gerar banimento. Além disso, há casos em que o bloqueio ocorre depois de apenas 10 mensagens enviadas para destinatários diferentes.
Em comparação com os anos anteriores, a taxa de banimentos permanece relativamente estável, mas o impacto é desigual entre os clientes. Alguns segmentos estão sofrendo mais do que outros, e isso pode estar diretamente ligado ao conteúdo das mensagens e ao perfil dos destinatários.
## Shadowban (Banimento Temporário do WhatsApp Web)
Durante a utilização da API, pode ocorrer um tipo de restrição conhecido como **shadowban**.
Esse tipo de banimento é diferente do bloqueio tradicional do WhatsApp. Ele é aplicado no contexto do WhatsApp Web, e não representa um banimento definitivo do número.
### Como o shadowban se manifesta
Quando um número está sob shadowban, podem ocorrer os seguintes comportamentos:
* Falha no envio de mensagens (notificado via [webhook de envio](/webhooks/on-message-send))
* Impedimento ao iniciar novas conversas
* Falha ao enviar mensagens para conversas muito antigas (mesmo que ainda existam)
* O problema pode ocorrer tanto com contatos salvos quanto não salvos
### Como identificar o shadowban
É possível identificar esse tipo de restrição através do webhook de [Ao enviar](/webhooks/on-message-send).
Ao tentar enviar uma mensagem, você pode receber erros como:
* `"The message was not sent due to a likely shadow ban"`
* `"Whatsapp rejected sending this message"`
Esses retornos indicam que o número está temporariamente impedido de enviar mensagens.
Ao conectar o número no WhatsApp Web e tentar iniciar uma nova conversa, pode aparecer um aviso informando o tempo restante da restrição, que pode variar de acordo com cada caso.
Não é necessário desconectar a instância, criar uma nova instância ou solicitar desbloqueio ao WhatsApp. Na maioria dos casos, o ideal é apenas aguardar.
#### Exemplo do possível aviso no WhatsApp Web:
### Considerações sobre Shadowban
O shadowban reforça a importância de manter boas práticas de uso, especialmente:
* Evitar envios em massa sem interação
* Manter comportamento natural do número
* Estimular respostas dos usuários
Mesmo sendo temporário, esse tipo de restrição pode impactar operações, principalmente em ambientes com alto volume de envio.
## Conclusão: O Que Realmente Importa?
O algoritmo do WhatsApp muda constantemente, tornando inviável uma estratégia única e infalível para evitar bloqueios. No passado, era mais fácil afirmar que "contas passivas não são banidas" e que "contas muito ativas são", mas hoje essa distinção não é mais tão clara.
Os dois principais fatores que determinam banimentos são:
* ✅ Número de destinatários diferentes que um número tenta alcançar.
* ✅ Conteúdo da mensagem (palavras-chave, contexto e padrão de envio).
Fatores secundários, como histórico do número, IP/ASN e método de conexão (Web ou Oficial), ainda têm impacto, mas são menos decisivos do que os fatores acima.
Não existe uma boa prática 100% eficaz para evitar banimentos. O algoritmo do WhatsApp está cada vez mais dinâmico, e a única abordagem viável é monitorar, adaptar estratégias continuamente e trabalhar dentro dos limites aceitáveis da plataforma.
# Funcionamento dos Botões
Source: https://developer.z-api.io/tips/button-status
## Introdução
Nas ultimas semanas as mensagens contendo botões estão sofrendo uma instabilidade em seu funcionamento.
**É importante lembrar que isso não se trata de um problema exclusivo da Z-API.**
Este tópico descreve como está o comportamento dos botões no WhatsApp em diferentes cenários.
***
**Atenção**
Essa documentação foi atualizada no dia 27/08/2024 então os fatos sobre o funcionamento dos botões estão baseados na realidade deste dia. Importante lembrar que a cada atualização do whatsapp os botões podem sofrer alterações.
## Fatores decisivos:
#### Para o funcionamento dos botões no WhatsApp, são dois fatores decisivos:
* Se o WhatsApp que está disparando a mensagem é business ou normal
* Se a mensagem está sendo enviada para chat normal ou para um grupo.
* Aceitar os termos de uso dos botões
## Aceite dos termos de uso dos botões
Para utilizar a funcionalidade dos botões, é necessário que você aceite os termos de uso, reconhecendo que está ciente de que futuras atualizações do WhatsApp podem causar instabilidades nessa funcionalidade.
## Tipos de botões
#### Existem sete tipos de botões no WhatsApp:
* Botão simples com texto (/send-button-list)
* Botão simples com imagem (/send-button-list-image)
* Botão simples com video (/send-button-list-video)
* Lista de opções (/send-option-list)
* Botões de ações (/send-button-actions)
* Botão de cópia (/send-button-otp)
* Botão PIX (/send-button-pix)
***
## Comportamento dos botões:
### [Botão simples com texto:](https://developer.z-api.io/message/send-button-list)
* Enviando de WhatsApp Normal para Grupo: **FUNCIONA**
* Enviando de WhatsApp Normal para Chat Normal: **FUNCIONA**
* Enviando de WhatsApp Business para Chat Normal: **FUNCIONA**
* Enviando de WhatsApp Business para Grupo: **FUNCIONA**
### [Botão simples com imagem:](https://developer.z-api.io/message/send-button-list-image)
* Enviando de WhatsApp Normal para Chat Normal: **FUNCIONA**
* Enviando de WhatsApp Normal para Grupo: **FUNCIONA**
* Enviando de WhatsApp Business para Chat Normal: **FUNCIONA**
* Enviando de WhatsApp Business para Grupo: **FUNCIONA**
### [Botão simples com video:](https://developer.z-api.io/message/send-button-list-video)
* Enviando de WhatsApp Normal para Chat Normal: **FUNCIONA**
* Enviando de WhatsApp Normal para Grupo: **FUNCIONA**
* Enviando de WhatsApp Business para Chat Normal: **FUNCIONA**
* Enviando de WhatsApp Business para Grupo: **FUNCIONA**
### [Lista de opções:](https://developer.z-api.io/message/send-option-list)
* Enviando de WhatsApp Normal para Chat Normal: **FUNCIONA**
* Enviando de WhatsApp Normal para Grupo: **FUNCIONA**
* Enviando de WhatsApp Business para Chat Normal: **FUNCIONA**
* Enviando de WhatsApp Business para Grupo: **FUNCIONA**
### [Botões de ações:](https://developer.z-api.io/message/send-button-actions)
* Enviando de WhatsApp Normal para Chat Normal: **FUNCIONA**
* Enviando de WhatsApp Normal para Grupo: **FUNCIONA**
* Enviando de WhatsApp Business para Chat Normal: **FUNCIONA**
* Enviando de WhatsApp Business para Grupo: **FUNCIONA**
### [Botão de cópia:](https://developer.z-api.io/message/send-button-otp)
* Enviando de WhatsApp Normal para Chat Normal: **FUNCIONA**
* Enviando de WhatsApp Normal para Grupo: **FUNCIONA**
* Enviando de WhatsApp Business para Chat Normal: **FUNCIONA**
* Enviando de WhatsApp Business para Grupo: **FUNCIONA**
### [Botão de chave PIX:](https://developer.z-api.io/message/send-button-pix)
* Enviando de WhatsApp Normal para Chat Normal: **FUNCIONA**
* Enviando de WhatsApp Normal para Grupo: **FUNCIONA**
* Enviando de WhatsApp Business para Chat Normal: **FUNCIONA**
* Enviando de WhatsApp Business para Grupo: **FUNCIONA**
## Resumo
Em resumo, o uso dos recursos de botões no WhatsApp está sujeito a problemas. tffTanto para o WhatsApp normal quanto para o WhatsApp Business, há dificuldades no envio desses tipos de botões em chats normais e grupos. Lista de opções para chat normal funcionam. Se você estiver usando o WhatsApp Business, a única coisa que está funcionando é a lista de opções para chat normal, com problemas para grupos.
# Ligações no Z-API Guia Completo
Source: https://developer.z-api.io/tips/calls-guide
## Introdução
Este guia apresenta tudo o que você precisa para utilizar o recurso de ligações do Z-API, abordando as três formas de integração disponíveis: API , SDK e protocolo SIP.
As ligações via WhatsApp permitem interações em tempo real, de forma simples e integrada ao fluxo de atendimento já existente. Com o Z-API, você pode realizar e gerenciar ligações de diferentes formas:
* Via API: Envio de arquivos de audio via requisições no Z-API
* Via SDK: Conjunto de ferramentas, bibliotecas e métodos prontos que o Z-API disponibiliza para facilitar a integração nas suas aplicações.
* Via SIP: Conexão de infraestrutura de telefonia como PABX, VOIP com o Whatsapp
É importante destacar que cada método possui características, requisitos e casos de uso específicos. O objetivo deste guia é apresentar cada abordagem de forma clara e prática, ajudando desenvolvedores e equipes técnicas a escolherem e implementarem a solução mais adequada para o seu cenário.
## 1. Via API
O recurso de ligações via API permite o envio de áudios pré-gravados como ligação no WhatsApp, possibilitando a automação de chamadas por meio de requisições HTTP simples, sem necessidade de bibliotecas adicionais.
A documentação completa do endpoint está disponível em:
🔗 [https://developer.z-api.io/calls/send-call](https://developer.z-api.io/calls/send-call)
## 2. Via SDK (Software Development Kit)
O SDK (Software Development Kit) é um conjunto de bibliotecas e métodos disponibilizados pelo Z-API para facilitar a integração nas suas aplicações. Em vez de montar manualmente as requisições HTTP, o SDK abstrai essa complexidade, oferecendo funções prontas e intuitivas para realizar ações como iniciar uma ligação, monitorar eventos e tratar erros.
Para o recurso de ligações, o SDK vai além do envio de áudios pré-gravados — ele permite realizar **ligações de vídeo e ligações ao vivo**, com suporte a até **3 chamadas simultâneas**, tornando-o ideal para cenários de atendimento em tempo real e comunicação mais rica com o cliente.
Importante: para utilizar o recurso de ligações via SDK, é necessário
primeiramente solicitar o token de ligação e realizar a inicialização do SDK
antes de efetuar qualquer chamada.
A documentação sobre como solicitar o token efêmero:
🔗 [https://developer.z-api.io/calls/call-token](https://developer.z-api.io/calls/call-token)
### Após gerar o token, siga exemplo de inicialização do SDK:
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
import { init } from "@z-api/call";
const client = init({
instanceId: "SUA_INSTANCE_ID",
getToken: async () => {
// Chama SEU backend, que por sua vez chama a Z-API para obter o token efêmero
const res = await fetch("https://seu-backend.com/call-token");
const data = await res.json();
return data.token;
},
});
// Ouvir eventos
client.on("call:incoming", (call) => {
console.log("Chamada recebida de", call.from);
});
client.on("connected", () => {
console.log("Conectado ao servidor");
});
```
Para mais comandos de SDK segue a documentação:
🔗 [https://www.npmjs.com/package/@z-api/call](https://www.npmjs.com/package/@z-api/call)
## 3. Via SIP (Session Initiation Protocol)
O SIP (Session Initiation Protocol) é um protocolo de comunicação padrão da indústria de telefonia, utilizado para iniciar, manter e encerrar sessões de voz e vídeo via internet (VoIP).
No contexto do Z-API, a integração via SIP permite que empresas que já possuem infraestrutura de telefonia como PABX IP, softphones ou provedores VoIP conectem essa estrutura ao WhatsApp, realizando ligações diretamente pela sua plataforma sem depender de um dispositivo físico.
### Exemplo de integração com a plataforma MicroSIP:
O MicroSIP é um softphone gratuito compatível com o protocolo SIP, que pode ser utilizado para realizar ligações pelo WhatsApp através do Z-API.
* **Passo 1 — Obtendo as credenciais no painel Z-API:**
Acesse: Painel Z-API → Instância Web → Selecione a instância → Aba "Ligações" → Seção "Via SIP"
Copie os três dados exibidos:
* HOST: sip.z-api.io
* USUÁRIO: É o instanceID onde você pode buscar no painel da instancia
* TOKEN: senha gerada — exibida apenas uma vez
Salve o TOKEN antes de sair da página, pois ele não será exibido novamente.
Caso perca, clique em "Gerar nova senha" para criar um novo.
* **Passo 2 — Configurando o MicroSIP:**
Após instalar o MicroSIP, acesse o menu principal → "Adicionar conta" e preencha os campos:
| Campo | Valor |
| - | - |
| Servidor SIP | `sip.z-api.io` |
| Usuário | InstanceID |
| Domínio | `sip.z-api.io` |
| Login | InstanceID |
| Senha | TOKEN copiado do painel |
| Transporte | UDP |
| Criptografia | Desabilitado |
| Endereço Público | Auto |
| Atualizar Registro | 300 |
| Manter Ativo | 15 |
* **Passo 3 — Verificando a conexão:**
Após salvar, o ícone do MicroSIP ficará verde, indicando que o registro foi realizado com sucesso e a integração está pronta para uso.
***
### Considerações Finais
O recurso de ligações do Z-API foi desenvolvido para atender diferentes perfis de integração, desde automações simples até operações mais complexas de telefonia. A escolha do método ideal depende das necessidades do seu projeto e da estrutura técnica disponível.
# Emuladores Android
Source: https://developer.z-api.io/tips/emulators
## Introdução
Para realmente ter um serviço de qualidade rodando "liso" recomendamos caso possível a utilização de emuladores Android, não é requisito mas, sabemos que utilizar-se deste recurso pode ajudar e muito na boa qualidade do serviço. No mercado existem diversas soluções, inclusive Clouds preparados para fornecer como serviço a hospedagem do seu número, abaixo vamos listar algumas soluções cujas quais temos clientes operando com sucesso.
## Emuladores
[BlueStacks]
[Nox]
[Memu]
[LDPlayer]
[Cloud Emulator]
Mas fique a vontade em procurar outras opções :)
**Números VOIP**
Para dar um toque final você ainda pode conciliar o emulador com um número VOIP, para saber como ativar leia o tópico Habilitando um número fixo nesta mesma sessão :)
[bluestacks]: https://www.bluestacks.com/pt-br/bluestacks-5.html
[nox]: https://nox-app-player.br.uptodown.com/windows
[memu]: https://www.memuplay.com
[ldplayer]: https://pt.ldplayer.net/ldy/pt2071.html
[cloud emulator]: https://www.cloudemulator.net
# Habilitando um número fixo
Source: https://developer.z-api.io/tips/enable-fix-number
## Introdução
Para habilitar um número fixo, você vai precisar ter um aparelho celular para hospedar seu número fixo. (esta opção fica disponível no WhatsApp Business). No passo a passo que criamos utilizamos um celular com Android.
### Primeiro passo
Baixe o aplicativo WhatsApp Business em um celular
[Android]
[IOS]
[android]: https://play.google.com/store/apps/details?id=com.whatsapp.w4b&hl=pt_BR&gl=US
[ios]: https://apps.apple.com/us/app/whatsapp-business/id1386412985
***
### Segundo passo
O WhatsApp Business vai pedir autorização para acessar os arquivos do celular, escolha a opção continuar para liberar o acesso. Na tela seguinte, escolha o país e informe o número do seu telefone fixo.
***
### Terceiro passo
Você receberá um código, mas como não é possível receber um SMS em um telefone fixo, aguarde até que a contagem e escolha a opção **Me ligue**.
E pronto você receberá uma ligação do WhatsApp Business que falará o código de ativação, aí é só digitar no campo indicado ;)
***
### Quarto passo
Seja Feliz!
Faça as configurações no app WhatsApp Bussines e leia o QrCode Z-API para dar Asas para sua imaginação!
# Conexão via Extensão Z-API Conector
Source: https://developer.z-api.io/tips/extension-guide
## Introdução
Em alguns dispositivos, o WhatsApp passou a exigir uma verificação adicional ao tentar conectar ao WhatsApp Web. Quando isso ocorre, você verá um destes dois sinais:
**No navegador** — a tela de verificação de segurança com chave de acesso:
**No celular** — uma notificação pedindo confirmação da nova conexão:
Esse comportamento **não ocorre em todos os dispositivos** — apenas naqueles em que o WhatsApp exige a validação pelo celular para autorizar uma nova conexão ao WhatsApp Web.
**Limitações conhecidas (fora do nosso controle):** o pareamento via passkey depende de recursos da própria plataforma (Windows/Bluetooth), e não da Z-API.
* **Windows 10 (ou inferior):** não há suporte a pareamento de passkey via Bluetooth nem sincronização de passkeys em nuvem. Nesses casos, o sistema solicita uma "chave de segurança USB" física e o fluxo não avança. Como o Windows 10 saiu de suporte em out/2025, não há previsão de correção pela Microsoft. Esse recurso é exclusivo do **Windows 11**.
* **Dispositivos sem Bluetooth:** independentemente do sistema operacional, o pareamento com o celular não é possível sem Bluetooth.
Se você se deparar com qualquer uma dessas telas ao tentar conectar sua instância Z-API, utilize a extensão **[Z-API Conector](https://chromewebstore.google.com/detail/iopmkohngoecmepoheapifkafbeomphn)** para o Google Chrome. Por meio dela, é possível autenticar a conexão de forma segura, sem precisar escanear um QR Code.
***
## Como funciona
O fluxo de conexão via extensão envolve três etapas principais:
1. **Instalar a extensão** [Z-API Conector](https://chromewebstore.google.com/detail/iopmkohngoecmepoheapifkafbeomphn) no Chrome
2. **Obter o token** de extensão — via painel ou via API
3. **Inserir o token** na extensão para autenticar a instância
***
## Passo 1 — Instalar a extensão
Acesse a Chrome Web Store e instale a extensão **[Z-API Conector](https://chromewebstore.google.com/detail/iopmkohngoecmepoheapifkafbeomphn)**.
Após instalar, o ícone da extensão aparecerá na barra de ferramentas do Chrome.
***
## Passo 2 — Obter o token de extensão
O token pode ser obtido de duas formas:
### Opção A — Via painel Z-API
Segue vídeo com passo a passo para conexão via painel Z-API:
Quando a instância está desconectada, o painel exibe o banner:
> **"Problemas com chave de acesso? Clique aqui e conecte via extensão da Z-API, sem precisar de QR Code."**
Clique em **"Clique aqui"** — o painel irá exibir a tela **"Conectar via extensão"** com o **Código de Conexão** gerado:
Após clicar, a tela será atualizada exibindo o código a ser inserido na extensão:
O próprio painel já orienta os próximos passos:
1. Baixe a extensão Z-API Conector
2. Abra o WhatsApp Web e clique na extensão
3. Digite o código exibido na extensão
### Opção B — Via API
Faça uma requisição ao endpoint de geração de token:
```bash theme={"theme":{"light":"github-light","dark":"poimandres"}}
curl --location 'https://api.z-api.io/instances/{instanceId}/token/{token}/extension-token' \
--header 'Client-Token: SEU_CLIENT_TOKEN'
```
A resposta será:
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"token": "FA48-HS63",
"expiresAt": 1782851138085
}
```
Código de acesso a ser inserido na extensão
Timestamp Unix (em milissegundos) com a data de expiração do token
O token possui validade limitada. Utilize-o antes que expire. Após a expiração, gere um novo token e repita o processo.
Documentação completa do endpoint: [Gerar token para extensão](/instance/extension-token)
***
## Passo 3 — Inserir o código na extensão
1. Acesse **[web.whatsapp.com](https://web.whatsapp.com/)** no Chrome, estando logado com o número que deseja conectar à instância Z-API
2. Clique no ícone da extensão **Z-API Conector** na barra do Chrome
3. A extensão irá detectar automaticamente o número logado e exibir os campos para o código de conexão
4. Digite o código obtido no painel ou via API (formato: `XXXX-XXXX`) e clique em **Continuar**
A extensão irá validar o código e avançar para a tela de confirmação.
## Passo 4 — Confirmar e conectar na Z-API
Após digitar o código, a extensão exibirá uma tela de confirmação com:
* O nome da **instância** que será conectada
* O **número detectado** no WhatsApp Web
* Um **contador regressivo** com o tempo restante de validade do token
Clique em **"Conectar na Z-API"**. A sessão ativa do WhatsApp Web será encerrada e o número passará a estar conectado à instância Z-API.
***
## Considerações Finais
Essa nova autenticação foi desenvolvida para se adequar à exigência de autenticação via chave de acesso imposta pelo WhatsApp. A extensão Z-API Conector garante que esse processo seja feito de forma segura e integrada à sua instância, sem expor credenciais sensíveis.
O token de extensão tem validade de até **5 minutos**. Após esse período, é necessário gerar um novo.
# Prazo de expiração dos arquivos
Source: https://developer.z-api.io/tips/file-expiration
## Como funciona
**Qual o prazo de validade dos arquivos do z-api?**
Todos os arquivos de midia recebidos do z-api através do seu webhook tem o prazo de expiração de **30 dias**. Após esse período todos os arquivos, seja audio, pdf, imagem, etc, serão excluídos do storage.
O z-api oferece a funcionalidade de webhooks para receber textos e arquivos diretamente em sua aplicação, sem a necessidade de armazenar essas informações em nossos servidores. Isso significa que sua aplicação tem total controle sobre os dados recebidos, o que é especialmente importante para cumprir as exigências da Lei Geral de Proteção de Dados (LGPD).
Caso o cliente deseje armazenar todas as mídias recebidas, é importante que ele implemente um sistema de armazenamento interno em sua própria aplicação, para que possa gerenciar esses dados de acordo com suas próprias políticas de privacidade e segurança. Dessa forma, nossa solução de webhooks ajuda a garantir a segurança dos dados dos seus clientes, ao mesmo tempo em que simplifica o processo de recebimento de informações em sua aplicação.
***
Para fazer esse armazenamento ele pode implementar um sistema de armazenamento interno em sua aplicação. Isso pode ser feito por meio de diversas tecnologias disponíveis no mercado, como serviços de armazenamento em nuvem, bancos de dados, sistemas de gerenciamento de arquivos. Existem diversas ferramentas e serviços que podem ser utilizados para isso, incluindo:
* Amazon S3
* Google Cloud Storage
# Lid
Source: https://developer.z-api.io/tips/lid
## Introdução
O `@lid` (Linked ID) é um *identificador único e privado* criado pelo WhatsApp para representar contatos sem expor diretamente o número de telefone.
Essa mudança faz parte das *atualizações de privacidade* do WhatsApp, permitindo que o usuário oculte seu número em determinados contextos.
Em alguns casos, o WhatsApp está enviando o `@lid` como identificação primária do usuário, mesmo que ele não tenha ativado nenhuma opção para esconder o número.
***
### Diferença entre `@lid` e `phone`
O WhatsApp pode retornar os identificadores de contato de diferentes formas, dependendo do tipo de conversa, grupo ou configuração de privacidade:
* `phone`: Pode conter o número real (`"554499999999"`) ou o próprio `@lid` (`"999999999999999@lid"`).
* `chatLid`: É o identificador único mais estável.
***
### Exemplo de Webhook
Nos webhooks da Z-API, o WhatsApp pode retornar o identificador do contato de diferentes formas, dependendo do tipo de interação e das configurações de privacidade do usuário.
#### Exemplo – Retorno completo com número e `@lid`:
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"chatLid": "999999999999999@lid",
"phone": "554499999999"
}
```
#### Exemplo – Retorno apenas com o `@lid`:
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"chatLid": "65998849469@lid",
"phone": "65998849469@lid"
}
```
***
### Envio de mensagens usando o `@lid`
É possível *enviar mensagens diretamente para um `@lid`*, substituindo o número de telefone no corpo da requisição:
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"phone": "999999999999999@lid",
"message": "Olá! Essa mensagem foi enviada usando o identificador @lid."
}
```
O envio funciona normalmente, pois o `@lid` *já é suportado* pela API da Z-API na maioria dos endpoints.
***
### Boas práticas de implementação
* Priorize o uso de `@lid` para identificar contatos — esse atributo tende a ser o mais estável.
* Evite depender apenas de `phone`, pois ele pode conter o número ou o próprio `@lid`.
* Armazene e relacione o `@lid` em sua base de dados para manter consistência.
***
### Conversão de `@lid` para número
Não é possível converter um `@lid` em número de telefone (`phone`).
Essa limitação existe *por motivos de privacidade definidos pelo WhatsApp*.
Permitir essa conversão invalidaria o propósito do recurso de ocultação de número.
O mapeamento direto entre `@lid` e `phone` *não é disponibilizado pelo WhatsApp nem pela Z-API*.
***
### Conversão de número (`phone`) para `@lid`
Por outro lado, é possível obter o `@lid` correspondente a um número de telefone utilizando o método ["Número com Whatsapp ?"](https://developer.z-api.io/contacts/get-iswhatsapp).
Esse endpoint permite verificar se um número possui conta no WhatsApp e, quando aplicável, retorna também o *identificador `@lid`* associado a esse número.
***
### Importante
* Essa mudança é *nativa do WhatsApp*, e a Z-API apenas repassa as informações conforme recebidas.
* O comportamento de retorno (`@lid` ou `phone`) pode variar.
* O atributo `chatLid` já está implementado nos webhooks da Z-API e pode ser usado tanto para identificar quanto para enviar mensagens normalmente.
* O `@lid` é uma medida que está sendo implementada pelo próprio WhatsApp; as mudanças estão sendo aplicadas gradualmente e ele ainda não está completamente implementado, por isso o comportamento pode ser inconsistente.
# Coleção Postman
Source: https://developer.z-api.io/tips/postman-collection
## Introdução à coleção do Postman do Z-API
Para facilitar o desenvolvimento e a integração com a nossa API, disponibilizamos uma coleção do Postman que contém todos os endpoints do Z-API, parâmetros e exemplos de requisições. Essa coleção ajuda os desenvolvedores a testar os endpoints de forma rápida e prática, permitindo explorar as funcionalidades da API sem necessidade de criar requisições manualmente.
Abaixo está o link para acessar a coleção Postman do Z-API:
[Link para a coleção Postman](https://www.postman.com/docs-z-api/z-api-s-public-workspace/collection/gwri249/z-api-collection)
***
# Criar lista de transmissão
Source: https://developer.z-api.io/broadcast/create-broadcast
POST /instances/{instanceId}/token/{token}/broadcast
Cria uma nova lista de transmissão
## Conceituação
Neste método você pode criar uma nova lista de transmissão, definindo um nome e os números que farão parte dela.
Atente-se às limitações e regras do uso de listas de transmissão. Para mais detalhes, consulte a [introdução](/broadcast/introduction).
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Obrigatórios
Nome da lista de transmissão
Lista de números dos destinatários no formato E.164 sem o `+`. Ex: 5511999999999
***
## Request Body
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"name": "Nome da lista",
"phones": ["5511999999999", "5511888888888"]
}
```
***
## Response
### 200
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"broadcastId": "1779474934@broadcast",
"name": "Nome da lista",
"phones": [
"5511999999999",
"5511888888888"
]
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Deletar lista de transmissão
Source: https://developer.z-api.io/broadcast/delete-broadcast
DELETE /instances/{instanceId}/token/{token}/broadcast/{broadcastId}
Remove uma lista de transmissão existente no WhatsApp
## Conceituação
Neste método você pode deletar permanentemente uma lista de transmissão existente.
Atente-se às limitações e regras do uso de listas de transmissão. Para mais detalhes, consulte a [introdução](/broadcast/introduction).
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Path
ID da lista de broadcast a ser deletada. Ex: 1779474934\@broadcast
***
## Response
### 200
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"success": true
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o DELETE conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Introdução
Source: https://developer.z-api.io/broadcast/introduction
Entenda como funcionam as listas de transmissão na Z-API
## Lista de transmissão
Uma lista de transmissão permite enviar mensagens para múltiplos contatos de uma só vez, de forma individual — cada destinatário recebe a mensagem como se fosse uma conversa direta, e eventuais respostas chegam de forma privada, sem que os outros membros da lista tenham acesso.
Cada lista possui um identificador com o sufixo `@broadcast`, como por exemplo: **1624901640\@broadcast**.
Você pode consultar suas listas através do endpoint de [**listagem de broadcasts**](/broadcast/list-broadcast).
**Limitação para números WhatsApp Business:** O WhatsApp Business não permite criar listas de transmissão, enviar mensagens para elas, nem ser adicionado a listas criadas por outros usuários. No entanto, ao utilizar a Z-API, os endpoints de broadcast funcionam normalmente mesmo em números Business. Recomendamos verificar o comportamento esperado no seu caso de uso antes de utilizar essa funcionalidade com contas Business.
***
## Envio de mensagens para lista de transmissão
Para enviar mensagens a uma lista de transmissão, utilize normalmente os endpoints de envio disponíveis na API (como texto, mídia, documentos, áudios, entre outros), informando o ID da lista de transmissão no campo phone.
Por exemplo, ao utilizar o endpoint de [**send-text**](/message/send-text), basta passar o ID da lista no campo phone. O mesmo conceito se aplica aos demais endpoints de envio de mensagens.
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"phone": "1779476888985@broadcast",
"message": "Olá, essa é uma mensagem de broadcast!"
}
```
O `broadcastId` pode ser obtido através do endpoint de **listagem de broadcasts** disponível na Z-API.
**Limite mensal de envios pelo WhatsApp:** O WhatsApp impõe um limite de **35 transmissões (mensagens) por mês** por número. Ao atingir esse limite, novos envios pelo aplicativo ficam bloqueados até o próximo ciclo. Via Z-API, as mensagens continuam sendo enviadas normalmente mesmo após o limite ser atingido — porém, **recomendamos fortemente respeitar esse limite** para evitar possíveis restrições impostas pelo WhatsApp.
***
## Gerenciamento de listas de transmissão
A Z-API disponibiliza endpoints dedicados para **criar**, **editar**, **deletar** e **listar** suas listas de transmissão diretamente pela API. Consulte as páginas a seguir para mais detalhes.
# Listar listas de transmissão
Source: https://developer.z-api.io/broadcast/list-broadcast
GET /instances/{instanceId}/token/{token}/broadcast
Lista todas as listas de transmissão da instância
## Conceituação
Neste método você pode listar todas as listas de transmissão associadas à sua instância, com suporte a paginação.
Atente-se às limitações e regras do uso de listas de transmissão. Para mais detalhes, consulte a [introdução](/broadcast/introduction).
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Query params (Opcionais)
Número da página a ser retornada. Começa em 1
Quantidade de itens por página. Padrão: 20
***
## Response
### 200
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
[
{
"broadcastId": "1779395073@broadcast",
"name": "Teste broadcast 44",
"phones": [
"5511999999999",
"5511888888888"
]
},
{
"broadcastId": "1779395075@broadcast",
"name": "Teste broadcast 45",
"phones": [
"5511999999999",
"5511888888888"
]
}
]
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Editar lista de transmissão
Source: https://developer.z-api.io/broadcast/update-broadcast
PUT /instances/{instanceId}/token/{token}/broadcast/{broadcastId}
Edita uma lista de transmissão existente no WhatsApp
## Conceituação
Neste método você pode editar uma lista de transmissão já existente, alterando o nome e/ou os números que a compõem.
Atente-se às limitações e regras do uso de listas de transmissão. Para mais detalhes, consulte a [introdução](/broadcast/introduction).
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Path
ID da lista de broadcast a ser editada. Ex: 1779474934\@broadcast
### Opcionais
Novo nome da lista de transmissão
### Obrigatórios
Lista completa de números dos destinatários no formato E.164 sem o `+`. Ex: 5511999999999
O campo `phones` **substitui a lista atual por completo** a cada requisição. Por isso:
* Para **adicionar** um novo contato, envie todos os números já existentes na lista mais o novo.
* Para **remover** um contato, envie todos os números existentes, omitindo apenas os que deseja remover.
***
## Request Body
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"name": "Nome da lista",
"phones": ["5511999999999", "5511888888888"]
}
```
***
## Response
### 200
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"broadcastId": "1778158856@broadcast",
"name": "Teste de broadcast editado",
"phones": [
"5511999999999",
"5511888888888",
"5511777777777"
]
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Gerar token para chamadas
Source: https://developer.z-api.io/calls/call-token
GET /instances/{instanceId}/token/{token}/call-token
Gera um token efêmero para autenticação na SDK de chamadas
## Conceituação
Este método gera um token efêmero para autenticação na SDK de chamadas.
O token é temporário e válido para uma única conexão. Se a aplicação reiniciar, um novo token deve ser gerado. Deve ser chamado a partir do backend, nunca do frontend, para evitar a exposição de credenciais.
***
## Integração com SDK
Este endpoint deve ser utilizado em conjunto com a SDK oficial de chamadas:
[https://www.npmjs.com/package/@z-api/call](https://www.npmjs.com/package/@z-api/call)
Na documentação da SDK, consulte a seção "Exemplo de backend (Node.js)" para entender como utilizar este endpoint corretamente na geração do token.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
***
## Response
### 200
Token efêmero para autenticação na SDK de chamadas
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Introdução
Source: https://developer.z-api.io/calls/introduction
Entenda como funcionam as chamadas na Z-API
## Conceituação
Agora com a Z-API você pode realizar ligações para qualquer número, incluindo o envio de áudio durante a chamada. Para mais detalhes sobre como utilizar essa funcionalidade, confira as próximas páginas da documentação.
Além disso, também é possível utilizar a funcionalidade conhecida como "chamar atenção" — semelhante ao antigo “cutucar” do Facebook. Com ela, você pode iniciar uma ligação, aguardar até 15 segundos e encerrá-la automaticamente.
Através dos webhooks de mensagens recebidas, é possível acompanhar os eventos da chamada e identificar se o destinatário atendeu ou rejeitou a ligação.
***
## Importante para partners
Se você já é partner e deseja habilitar a funcionalidade de chamadas em uma instância, confira as opções abaixo:
* **Atualizar uma instância existente (já criada e assinada):**\
Utilize o endpoint de atualização de instância:\
[Atualizando a assinatura](/partner/update-instance)
* **Criar uma nova instância com chamadas habilitadas:**\
Ao criar e assinar a instância, utilize o parâmetro `withCalls=true` conforme a documentação:\
[Assinando uma instância](/partner/sign-instance)
Consulte as próximas páginas para entender em detalhes como utilizar os endpoints de chamadas.
## Sobre chamadas
A instância de ligação também consegue enviar mensagens — ou seja, ao assinar uma instância de ligação, é possível utilizar essa mesma instância para realizar até 3 ligações simultâneas e enviar mensagens.
Ao estar em uma ligação, as mensagens continuam sendo enviadas normalmente, não havendo interrupção da fila.
# Fazer ligação
Source: https://developer.z-api.io/calls/send-call
POST /instances/{instanceId}/token/{token}/send-call
Envia uma ligação para um número com WhatsApp
## Conceituação
Neste método você pode enviar uma ligação a um número que possua WhatsApp.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Obrigatórios
Telefone do destinatário no formato DDI DDD NÚMERO. Ex: 551199999999
### Opcionais
Duração da chamada em segundos. Padrão: 5 segundos. Máximo: 15 segundos
Link do arquivo de áudio (16k bitrate). Disponível apenas para contas com funcionalidade de chamadas habilitada
***
## Request Body
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"phone": "5511999999999",
"callDuration": 5
}
```
***
## Response
### 200
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"zaapId": "3999984263738042930CD6ECDE9VDWSA",
"messageId": "D241XXXX732339502B68",
"id": "D241XXXX732339502B68"
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Obter informações SIP
Source: https://developer.z-api.io/calls/sip-info
GET /instances/{instanceId}/token/{token}/sip-info
Consulta as informações SIP da instância
## Conceituação
Método utilizado para consultar as informações SIP da instância.
A funcionalidade de chamadas precisa estar **habilitada e contratada**. Execute este endpoint a partir do backend para proteger credenciais sensíveis.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
***
## Response
### 200
Endereço do servidor SIP
Identificador do usuário SIP
Token de autenticação SIP (parcialmente mascarado)
Status de ativação SIP
**Com token configurado:**
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"host": "sip.z-api.io",
"user": "3C67AB641C8AA0412F6A2242B4E23AC7",
"token": "BZ9***",
"active": true
}
```
**Sem token configurado:**
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"host": "sip.z-api.io",
"user": "3C67AB641C8AA0412F6A2242B4E23AC7",
"active": false
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Gerar token SIP
Source: https://developer.z-api.io/calls/sip-token
POST /instances/{instanceId}/token/{token}/sip-token
Gera credenciais SIP para a instância
## Conceituação
Este método gera credenciais SIP para a instância, habilitando integração de telefonia via protocolo SIP para fazer e receber chamadas.
A funcionalidade de chamadas precisa estar **habilitada e contratada**. Gerar novas credenciais substitui qualquer token SIP existente.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
***
## Response
### 200
Endereço do servidor SIP
Identificador do usuário SIP
Token de autenticação SIP
Status de ativação SIP
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"host": "sip.z-api.io",
"user": "3C67AB641C8AA0412F6A2242B4E23AC7",
"token": "BZ9vKoEsmmrCP6y4t0XYCYBW5rMZrQmJAt6KfERWLvk",
"active": true
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Arquivar chats
Source: https://developer.z-api.io/chats/archive-chat
POST /instances/{instanceId}/token/{token}/modify-chat
Este método é responsável por arquivar e desarquivar seus chats.
## Conceituação
Este método é responsável por arquivar e desarquivar seus chats.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Obrigatórios
Telefone do chat que deseja modificar
Ação: `archive` ou `unarchive`
***
## Request Body
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"phone": "5544999999999",
"action": "archive"
}
```
***
## Response
### 200
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"value": true
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Limpar chat
Source: https://developer.z-api.io/chats/clear-chat
POST /instances/{instanceId}/token/{token}/modify-chat
Este método é responsável por limpar as mensagens dos seus chats.
## Conceituação
Este método é responsável por limpar as mensagens dos seus chats.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Obrigatórios
Telefone do chat que deseja modificar
Ação: `clear`
***
## Request Body
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"phone": "5544999999999",
"action": "clear"
}
```
***
## Response
### 200
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"value": true
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Deletar chats
Source: https://developer.z-api.io/chats/delete-chat
POST /instances/{instanceId}/token/{token}/modify-chat
Este método é responsável por deletar seus chats.
## Conceituação
Este método é responsável por deletar seus chats.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Obrigatórios
Telefone do chat que deseja modificar
Ação: `delete`
***
## Request Body
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"phone": "5544999999999",
"action": "delete"
}
```
***
## Response
### 200
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"value": true
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Pegar chats
Source: https://developer.z-api.io/chats/get-chats
GET /instances/{instanceId}/token/{token}/chats
Retorna todos os chats da instância
## Conceituação
Este método é responsável por retornar todos os chats.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Query Parameters
Utilizado para paginação, informe a página de chats que quer buscar
Especifica o tamanho do retorno de chats por página
***
## Response
### 200
Indica se o chat está arquivado
Indica se o chat está fixado
Número de telefone do contato
Número de mensagens não lidas
Nome atribuído ao chat (retorna IDs para grupos/listas de transmissão)
Timestamp da última interação
0 ou 1 indicando se o chat está silenciado
Indica se o chat está marcado como spam
Indica se é um grupo
Anotações do chat (disponível apenas para WhatsApp Business)
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
[
{
"archived": "false",
"pinned": "true",
"messagesUnread": 0,
"phone": "5511999999999",
"unread": "0",
"name": "Z-API SUPORTE",
"lastMessageTime": "1622991687",
"isMuted": "0",
"isMarkedSpam": "false",
"isGroupAnnouncement": false,
"isGroup": false
},
{
"archived": "false",
"pinned": "true",
"messagesUnread": 0,
"phone": "5511999999999",
"unread": "0",
"name": "Z-api - Team",
"lastMessageTime": "1622990503",
"muteEndTime": 1655953774000,
"isMuted": "0",
"isMarkedSpam": "false",
"isGroupAnnouncement": false,
"isGroup": false,
"notes": {
"id": "KlesU6f4f/Qd5d6VuAbvOMi31rg/F92owVe/xDYad1C=",
"content": "texto da anotação",
"createdAt": 1655953774000,
"lastUpdateAt": 1655953774000
}
}
]
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Pegar metadata do chat
Source: https://developer.z-api.io/chats/get-metadata-chat
GET /instances/{instanceId}/token/{token}/chats/{phone}
Retorna as informações do metadata de um chat
## Conceituação
Este método é responsável por retornar as informações do metadata de um chat.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Path
Telefone do contato no formato DDI DDD NÚMERO. Ex: 551199999999
***
## Response
### 200
Telefone do contato
Número de mensagens não lidas
Timestamp da última interação
0 ou 1 indicando se o chat está silenciado
Indica se o chat está marcado como spam
URL da foto do chat (apagada após 48h pelo WhatsApp)
Indica se é um grupo de avisos
Indica se é um grupo
Recado do perfil
Anotações do chat (disponível apenas para WhatsApp Business)
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"phone": "5511999999999",
"unread": "0",
"lastMessageTime": "1619461666",
"isMuted": "0",
"isMarkedSpam": "false",
"profileThumbnail": "https://pps.whatsapp.net/...",
"messagesUnread": 0,
"about": "Recado do perfil",
"isGroupAnnouncement": false,
"isGroup": false,
"notes": {
"id": "KlesU6f4f/Qd5d6VuAbvOMi31rg/F92owVe/xDYad1C=",
"content": "texto da anotação",
"createdAt": 1655953774000,
"lastUpdateAt": 1655953774000
}
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Introdução
Source: https://developer.z-api.io/chats/introduction
Entenda como funcionam os chats na Z-API e os métodos disponíveis
## Conceituação
Conforme já falamos no tópico anterior, para o WhatsApp tudo é um chat. Neste tópico você vai encontrar todos os métodos para buscar informações e gerenciar seus chats.
Um chat no WhatsApp pode ser:
* **Conversa individual** — chat com um contato específico, identificado pelo número de telefone;
* **Grupo** — chat com múltiplos participantes, identificado por um ID único;
* **Lista de transmissão** — envio para múltiplos contatos ao mesmo tempo, identificada por um ID com prefixo "broadcast".
***
## O que você pode fazer com chats?
Através da Z-API, você tem acesso a diversos métodos para gerenciar seus chats:
Obtenha todos os chats abertos com informações como última mensagem, timestamp e dados do contato/grupo.
Busque informações detalhadas de um chat específico.
Marque um chat inteiro como lido, similar ao que você faz manualmente no WhatsApp.
Organize seus chats arquivando ou fixando conversas importantes.
Silencie notificações de um chat específico.
Limpe o histórico de mensagens ou delete um chat completamente.
***
## Identificadores de chat
É importante entender como o WhatsApp identifica cada tipo de chat:
| Tipo | Formato do ID | Exemplo |
| - | - | - |
| Contato | Número de telefone | `5511999999999` ou `99999999999@lid` |
| Grupo | ID do grupo | `120363019502650977-group` ou `123456789101-12345678910` |
Todos esses IDs são retornados pelo método **get-chats**. Recomendamos armazenar esses identificadores na sua aplicação para facilitar o gerenciamento dos chats.
# Mutar chats
Source: https://developer.z-api.io/chats/mute-chat
POST /instances/{instanceId}/token/{token}/modify-chat
Este método é responsável por mutar e desmutar seus chats.
## Conceituação
Este método é responsável por mutar e desmutar seus chats.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Obrigatórios
Telefone do chat que deseja modificar
Ação: `mute` ou `unmute`
***
## Request Body
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"phone": "5544999999999",
"action": "mute"
}
```
***
## Response
### 200
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"value": true
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Fixar chats
Source: https://developer.z-api.io/chats/pin-chat
POST /instances/{instanceId}/token/{token}/modify-chat
Este método é responsável por fixar e desafixar seus chats.
## Conceituação
Este método é responsável por fixar e desafixar seus chats.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Obrigatórios
Telefone do chat que deseja modificar
Ação: `pin` ou `unpin`
***
## Request Body
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"phone": "5544999999999",
"action": "pin"
}
```
***
## Response
### 200
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"value": true
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Ler chats
Source: https://developer.z-api.io/chats/read-chat
POST /instances/{instanceId}/token/{token}/modify-chat
Este método é responsável por realizar a ação de ler um chat como um todo, ou também marcar um chat como não lido.
## Conceituação
Este método é responsável por realizar a ação de ler um chat como um todo, ou também marcar um chat como não lido.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Obrigatórios
Telefone do chat que deseja modificar
Ação: `read` ou `unread`
***
## Request Body
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"phone": "5544999999999",
"action": "read"
}
```
***
## Response
### 200
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"value": true
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Expiração do chat
Source: https://developer.z-api.io/chats/send-chat-expiration
POST /instances/{instanceId}/token/{token}/send-chat-expiration
Este método é responsável por enviar expiração do chat.
## Conceituação
Este método é responsável por enviar expiração do chat.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Obrigatórios
Telefone do chat que deseja modificar
Expiração do chat: `24_HOURS`, `7_DAYS`, `90_DAYS` ou `OFF`
***
## Request Body
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"phone": "554497050785",
"chatExpiration": "90_DAYS"
}
```
***
## Response
### 200
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"value": true
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Promover admin da comunidade
Source: https://developer.z-api.io/communities/add-community-admin
POST /instances/{instanceId}/token/{token}/add-admin
Promove participantes da comunidade a administradores
## Conceituação
Este método é responsável por promover participantes da comunidade a administradores.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Obrigatórios
ID da comunidade, obtido na API de Listar comunidades
Números dos participantes a serem promovidos
***
## Request Body
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"communityId": "120363186053925765",
"phones": ["5544999999999", "5544888888888"]
}
```
***
## Response
### 200
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"value": true
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Adicionar participantes
Source: https://developer.z-api.io/communities/add-community-participant
POST /instances/{instanceId}/token/{token}/add-participant
Adiciona novos participantes a uma comunidade
## Conceituação
Este método é responsável por adicionar novos participantes à comunidade.
Caso não consiga adicionar diretamente, ao ativar o `autoInvite` a API envia convites privados com o link da comunidade para os participantes que não foram adicionados.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Obrigatórios
Envia link de convite da comunidade no privado
ID da comunidade
Array com os números dos participantes a serem adicionados
***
## Request Body
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"autoInvite": true,
"communityId": "120363019502650977",
"phones": ["5544999999999", "5544888888888"]
}
```
***
## Response
### 200
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"value": true
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Metadata da comunidade
Source: https://developer.z-api.io/communities/community-metadata
GET /instances/{instanceId}/token/{token}/communities-metadata/{communityId}
Retorna o metadata da comunidade com nome, descrição e grupos
## Conceituação
Este método retorna o metadata da comunidade, como nome, descrição e grupos vinculados.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Path
ID da comunidade
***
## Response
### 200
Nome da comunidade
ID da comunidade
Descrição da comunidade
Grupos vinculados à comunidade
Nome do grupo
ID/Phone do grupo
Indica se é o grupo de avisos
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"name": "Minha primeira Comunidade",
"id": "98372465382764532938",
"description": "Uma descrição da comunidade",
"subGroups": [
{
"name": "Minha primeira Comunidade",
"phone": "342532456234453-group",
"isGroupAnnouncement": true
},
{
"name": "Outro grupo",
"phone": "1203634230225498-group",
"isGroupAnnouncement": false
}
]
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Configurações da comunidade
Source: https://developer.z-api.io/communities/community-settings
POST /instances/{instanceId}/token/{token}/communities/settings
Altera as configurações de uma comunidade
## Conceituação
Com essa API você consegue alterar as configurações de uma comunidade.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Obrigatórios
ID da comunidade
Quem pode adicionar novos grupos: `admins` ou `all`
***
## Request Body
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"communityId": "98372465382764532938",
"whoCanAddNewGroups": "admins"
}
```
***
## Response
### 200
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"success": true
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Criar comunidade
Source: https://developer.z-api.io/communities/create-community
POST /instances/{instanceId}/token/{token}/communities
Cria uma nova comunidade no WhatsApp
## Conceituação
Antes de utilizar esse recurso, é importante verificar se o aplicativo do WhatsApp no seu celular já possui compatibilidade com as comunidades, caso já esteja disponível você pode utilizar essa API para criar novas comunidades.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Obrigatórios
Nome da comunidade
### Opcionais
Descrição da comunidade
***
## Request Body
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"name": "Minha primeira Comunidade"
}
```
***
## Response
### 200
ID da comunidade criada
Grupos vinculados à comunidade
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"id": "98372465382764532938",
"subGroups": [
{
"name": "Minha primeira Comunidade",
"phone": "342532456234453-group",
"isGroupAnnouncement": true
}
]
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Desativar comunidade
Source: https://developer.z-api.io/communities/deactivate-community
DELETE /instances/{instanceId}/token/{token}/communities/{communityId}
Desativa uma comunidade
## Conceituação
Este método é responsável por desativar uma comunidade.
Desativar a comunidade não excluirá seus grupos, mas sim os removerá da comunidade.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Path
ID da comunidade
***
## Response
### 200
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"success": true
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Introdução
Source: https://developer.z-api.io/communities/introduction
Entenda como funcionam as comunidades na Z-API
## Conceituação
O WhatsApp agora oferece a funcionalidade de Comunidades, que permite aos usuários agrupar grupos ao redor de um assunto ou interesse em comum.
### Como funciona comunidades?
Maria, João, Pedro, Paula
*Todos os participantes da comunidade*
Maria, João
Pedro, Paula
O **Grupo de avisos** contém todos os participantes de todos os grupos da comunidade. Quando um novo grupo é vinculado, seus participantes são automaticamente adicionados ao grupo de avisos.
***
## Observações
* Ao criar uma comunidade, é criado um grupo padrão (grupo de avisos) com o mesmo nome da comunidade.
* Este grupo representa sua comunidade inteira e é usado para enviar mensagens para todos.
* Cada novo grupo vinculado à comunidade, todos participantes farão parte do grupo de avisos.
* Ao desvincular um grupo, todos participantes dele são removidos do grupo de avisos.
***
## Especificações
Cada comunidade pode ter até **50 grupos**, e o(s) administrador(es) das comunidades poderão disparar mensagens para até **5 mil pessoas** de uma única vez através do grupo de avisos.
# Vincular grupos
Source: https://developer.z-api.io/communities/link-groups
POST /instances/{instanceId}/token/{token}/communities/link
Adiciona grupos a uma comunidade
## Conceituação
Com essa API você consegue adicionar outros grupos a uma comunidade.
Não é possível vincular o mesmo grupo em mais de uma comunidade. Se você enviar 3 grupos e 1 já pertencer a outra comunidade, 2 serão adicionados e o outro retornará um erro indicando que já faz parte de outra comunidade.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Obrigatórios
ID da comunidade
Array com os IDs/Phones dos grupos a serem vinculados
***
## Request Body
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"communityId": "98372465382764532938",
"groupsPhones": ["1345353454354354-group", "1203634230225498-group"]
}
```
***
## Response
### 200
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"success": true
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Listar comunidades
Source: https://developer.z-api.io/communities/list-communities
GET /instances/{instanceId}/token/{token}/communities
Retorna todas as comunidades que você faz parte
## Conceituação
Este método é responsável por retornar todas as comunidades que você faz parte.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Query Parameters
Utilizado para paginação, informe a página que quer buscar
Especifica o tamanho do retorno por página
***
## Response
### 200
Nome da comunidade
ID da comunidade
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
[
{
"name": "Minha primeira Comunidade",
"id": "98372465382764532938"
}
]
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Redefinir link de convite
Source: https://developer.z-api.io/communities/redefine-invitation-link
POST /instances/{instanceId}/token/{token}/redefine-invitation-link/{communityId}
Redefine o link de convite de uma comunidade
## Conceituação
Este método permite que você redefina o link de convite de uma comunidade.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Path
ID da comunidade
***
## Response
### 200
Novo link de convite da comunidade
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"invitationLink": "https://chat.whatsapp.com/C1adgkdEGki7554BWDdMkd"
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Remover admin da comunidade
Source: https://developer.z-api.io/communities/remove-community-admin
POST /instances/{instanceId}/token/{token}/remove-admin
Remove um ou mais administradores de uma comunidade
## Conceituação
Este método é responsável por remover um ou mais administradores de uma comunidade.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Obrigatórios
ID da comunidade
Números dos administradores a serem removidos
***
## Request Body
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"communityId": "120363019502650977",
"phones": ["5544999999999", "5544888888888"]
}
```
***
## Response
### 200
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"value": true
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Remover participantes
Source: https://developer.z-api.io/communities/remove-community-participant
POST /instances/{instanceId}/token/{token}/remove-participant
Remove participantes de uma comunidade
## Conceituação
Este método é responsável por remover participantes da comunidade.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Obrigatórios
ID da comunidade. Pode ser obtido na API de Listar comunidades
Array com os números dos participantes a serem removidos
***
## Request Body
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"communityId": "120363019502650977",
"phones": ["5544999999999", "5544888888888"]
}
```
***
## Response
### 200
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"value": true
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Desvincular grupos
Source: https://developer.z-api.io/communities/unlink-groups
POST /instances/{instanceId}/token/{token}/communities/unlink
Remove grupos de uma comunidade
## Conceituação
Com essa API você consegue remover grupos de uma comunidade, para isso você vai precisar do ID da sua comunidade e os telefones dos grupos que deseja remover.
Uma comunidade precisa manter pelo menos 1 grupo vinculado (excluindo o grupo de avisos), então não é possível remover um grupo se ele for o único grupo comum vinculado.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Obrigatórios
ID da comunidade
Array com os números dos grupos a serem desvinculados
***
## Request Body
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"communityId": "98372465382764532938",
"groupsPhones": ["1345353454354354-group"]
}
```
***
## Response
### 200
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"success": true
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Alterar descrição da comunidade
Source: https://developer.z-api.io/communities/update-community-description
POST /instances/{instanceId}/token/{token}/update-community-description
Altera a descrição da comunidade
## Conceituação
Este método permite você alterar a descrição da comunidade.
Somente administradores podem alterar as configurações da comunidade.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Obrigatórios
ID da comunidade
Nova descrição da comunidade
***
## Request Body
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"communityId": "120363019502650977",
"communityDescription": "descrição da comunidade"
}
```
***
## Response
### 200
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"value": true
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Adicionar contatos
Source: https://developer.z-api.io/contacts/add-contacts
POST /instances/{instanceId}/token/{token}/contacts/add
Salva contatos do WhatsApp na lista de contatos do celular
## Conceituação
Este método é responsável por salvar os contatos do WhatsApp em sua lista de contatos no celular.
**Sobre esse recurso**
O método para adicionar contatos à lista do WhatsApp só funcionará para contas que já receberam a atualização necessária. Certifique-se de que sua conta **do WhatsApp** tenha recebido a atualização antes de utilizar este recurso. Caso contrário, a operação não será concluída com sucesso.
Além disso, é necessário permitir que o WhatsApp adicione contatos diretamente no celular. Para isso, vá até as configurações de privacidade do seu aplicativo e ajuste as permissões de forma que o WhatsApp possa acessar e modificar seus contatos.
#### Exemplo nas configurações
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Obrigatórios
Nome do contato que vai ser adicionado na agenda
Número do contato que vai ser adicionado na agenda
### Opcionais
Sobrenome do contato que vai ser adicionado na agenda
***
## Request Body
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
[
{
"firstName": "Contato 1",
"lastName": "Sobrenome 1",
"phone": "554499999999"
},
{
"firstName": "Contato 2",
"lastName": "Sobrenome 2",
"phone": "554499998888"
}
]
```
***
## Response
### 200
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"success": true,
"errors": []
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Bloquear / Desbloquear contato
Source: https://developer.z-api.io/contacts/block-contact
POST /instances/{instanceId}/token/{token}/contacts/modify-blocked
Bloqueia ou desbloqueia um contato no WhatsApp
## Conceituação
Este método é responsável por bloquear ou desbloquear um contato.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Obrigatórios
Número do telefone do contato
Ação a ser executada: `block` (bloquear) ou `unblock` (desbloquear)
***
## Request Body
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"phone": "5544999999999",
"action": "block"
}
```
***
## Response
### 200
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"value": true
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Pegar contatos
Source: https://developer.z-api.io/contacts/get-contacts
GET /instances/{instanceId}/token/{token}/contacts
Retorna todos os contatos do WhatsApp
## Conceituação
Este método é responsável por retornar todos os contatos do WhatsApp.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Query Parameters
Utilizado para paginação, você deve informar aqui a página de contatos que quer buscar
Especifica o tamanho do retorno de contatos por página
***
## Response
### 200
Phone do contato
Nome e sobrenome do contato, só vai retornar preenchido caso você tenha o número em seus contatos
Nome do contato, só vai retornar preenchido caso você tenha o número em seus contatos
Nome do contato caso você tenha ele como contato
Nome informado nas configurações de nome do WhatsApp
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
[
{
"name": "Nome e sobrenome do contato",
"short": "Nome do contato",
"notify": "Nome no WhatsApp",
"vname": "Nome no vcard",
"phone": "559999999999"
}
]
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Número com WhatsApp?
Source: https://developer.z-api.io/contacts/get-iswhatsapp
GET /instances/{instanceId}/token/{token}/phone-exists/{phone}
Verifica se um número possui conta no WhatsApp
## Conceituação
Este método retorna se o número tem ou não WhatsApp.
Utilize essa API sempre que quiser verificar se um número possui WhatsApp, geralmente para validação de formulários. Não utilize essa API caso queira fazer uma verificação antes de enviar uma mensagem, pois o Z-API já valida a existência do número a cada mensagem enviada.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Query Parameters
Telefone do contato no formato DDI DDD NÚMERO. Ex: 551199999999
***
## Response
### 200
Indica se o número possui WhatsApp
Número formatado conforme resposta do WhatsApp
Identificador único privado do WhatsApp (null se exists = false)
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
[
{
"exists": true,
"phone": "5544999999999",
"lid": "999999999@lid"
}
]
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Verificação em lote
Source: https://developer.z-api.io/contacts/get-iswhatsapp-batch
POST /instances/{instanceId}/token/{token}/phone-exists-batch
Verifica em lote se números possuem conta no WhatsApp
## Conceituação
Diferente do método anterior que valida individualmente se um número possui WhatsApp através de uma requisição GET, essa API oferece uma verificação em lote.
Máximo de **50.000** validações por requisição.
Utilize essa API para validação de formulários. Não é recomendado utilizar esta API para verificar a existência do número antes de enviar uma mensagem, pois o Z-API já valida a existência do número a cada mensagem enviada.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Body
Lista de números de telefone no formato DDI DDD NÚMERO. Ex: 551199999999
***
## Request Body
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"phones": ["554499999999", "554488888888"]
}
```
***
## Response
### 200
Indica se o número possui WhatsApp
Número enviado na requisição
Número formatado conforme resposta do WhatsApp
Identificador único privado do WhatsApp (null se exists = false)
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
[
{
"exists": true,
"inputPhone": "554499999999",
"outputPhone": "554499999999",
"lid": "999999999999999@lid"
}
]
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Metadata do contato
Source: https://developer.z-api.io/contacts/get-metadata-contact
GET /instances/{instanceId}/token/{token}/contacts/{phone}
Retorna as informações do metadata do contato
## Conceituação
Este método é responsável por retornar as informações do metadata do contato.
Se você pretende armazenar a imagem do seu contato observe que sempre retornamos no get-contacts o atributo imgUrl com ela para você, porém é importante lembrar que esta fica disponível por apenas **48 horas** conforme política do WhatsApp.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Path
Telefone do contato no formato DDI DDD NÚMERO. Ex: 551199999999
***
## Response
### 200
Nome e sobrenome do contato
Número do contato
Nome do contato no WhatsApp
Nome do contato
URL da foto do contato (expira em 48 horas)
Recado do perfil do contato
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"name": "Nome e sobrenome do contato",
"phone": "551199999999",
"notify": "Nome do contato no WhatsApp",
"short": "Nome do contato",
"imgUrl": "https://...",
"about": "Recado do perfil do contato"
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Pegar imagem do contato
Source: https://developer.z-api.io/contacts/get-profile-picture
GET /instances/{instanceId}/token/{token}/profile-picture
Retorna a URL com a imagem do contato atualizada
## Conceituação
Este método é responsável por retornar a url com a imagem do contato atualizada.
A imagem do contato obtida via get-contacts fica disponível por apenas **48 horas** antes do WhatsApp apagar o link. Para obter a imagem atualizada, utilize este método.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Query Parameters
Telefone do contato no formato DDI DDD NÚMERO. Ex: 551199999999
***
## Response
### 200
URL com a foto do contato
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"link": "https://..."
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Introdução
Source: https://developer.z-api.io/contacts/introduction
Entenda como funcionam os contatos na Z-API
## Conceituação
Neste tópico você vai entender um pouco mais sobre o que o **Z-API** pode fazer quando o assunto é contato.
Para o WhatsApp todo contato é simplesmente um Chat! Parece ousado de se dizer mas é assim que ele trata o que chamamos de contato, ele utiliza o número do seu contato apenas como identificador para o chat conforme já dito em outros tópicos.
A diferença entre o get-chats e o get-contacts é que o get-chats vai trazer todos contatos aos quais você já manteve uma conversa ou seja tem um chat aberto com ele, o get-contacts vai retornar todos os seus contatos que tenham conta no WhatsApp somado aos contatos que participam de grupos com o seu número.
Tudo que o Z-API pode fazer quanto a contatos é o mesmo que o WhatsApp Web pode fazer ou seja, quase nada, não é possível adicionar um contato, nem mesmo renomear ou mesmo excluir, basicamente o que você precisa entender é que o WhatsApp Web não consegue manipular a agenda de contatos do seu celular, logo o **Z-API** também não.
***
## Sobre contatos
O método que retorna contatos pode te deixar um pouco confuso pois provavelmente ele deve retornar um número maior de contatos do que a quantidade que você tem em sua agenda, isso ocorre porque você provavelmente participa de grupos, o método get-contacts vai retornar todos os contatos que estão nos grupos que você participa.
# Remover contatos
Source: https://developer.z-api.io/contacts/remove-contacts
DELETE /instances/{instanceId}/token/{token}/contacts/remove
Remove contatos do WhatsApp da lista de contatos do celular
## Conceituação
Este método é responsável por remover os contatos do WhatsApp da sua lista de contatos no celular.
**Sobre esse recurso**
O método para remover contatos da lista do WhatsApp só funcionará para contas que já receberam a atualização necessária. Certifique-se de que sua conta **do WhatsApp** tenha recebido a atualização antes de utilizar este recurso. Caso contrário, a operação não será concluída com sucesso.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
***
## Request Body
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
["554499999999", "554499998888"]
```
***
## Response
### 200
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"success": true,
"errors": []
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o DELETE conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Denunciar contato
Source: https://developer.z-api.io/contacts/report-contact
POST /instances/{instanceId}/token/{token}/contacts/{phone}/report
Denuncia um contato no WhatsApp
## Conceituação
Este método é responsável por denunciar um contato.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Path
Número do telefone do contato que deseja denunciar
***
## Response
### 200
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"success": true
}
```
### 400
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"error": "Invalid phone"
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Aceitar convite do grupo
Source: https://developer.z-api.io/group/accept-group-invite
GET /instances/{instanceId}/token/{token}/accept-invite-group
Aceita um convite para participar de um grupo
## Conceituação
Este método é responsável por aceitar um convite que você recebeu para participar de um grupo.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Query Parameters
URL de convite do grupo recebida. Pode ser obtida através do webhook de mensagem recebida
***
## Response
### 200
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"success": true
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Promover admin do grupo
Source: https://developer.z-api.io/group/add-admin
POST /instances/{instanceId}/token/{token}/add-admin
Promove participantes do grupo a administradores
## Conceituação
Este método é responsável por promover participantes do grupo a administradores. Você pode promover um ou mais participantes a administrador.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Obrigatórios
ID/Phone do grupo
Array com os números dos participantes a serem promovidos
***
## Request Body
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"groupId": "120363019502650977-group",
"phones": ["5544999999999", "5544888888888"]
}
```
***
## Response
### 200
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"value": true
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Adicionar participantes
Source: https://developer.z-api.io/group/add-participant
POST /instances/{instanceId}/token/{token}/add-participant
Adiciona novos participantes ao grupo
## Conceituação
Este método é responsável por adicionar novos participantes ao grupo.
Para inclusão de participantes nos grupos, utilize exclusivamente o número de telefone. A identifição do @lid não é compatível e não realizará a adição de novos membros.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Obrigatórios
Caso não consiga adicionar, a API envia convites privados com o link do grupo
ID/Phone do grupo
Lista de números de telefone dos participantes a serem adicionados
***
## Request Body
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"autoInvite": true,
"groupId": "120363019502650977-group",
"phones": ["5544999999999", "5544888888888"]
}
```
***
## Response
### 200
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"value": true
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Aprovar participantes
Source: https://developer.z-api.io/group/approve-participant
POST /instances/{instanceId}/token/{token}/approve-participant
Aceita a entrada de participantes no grupo
## Conceituação
Este método é responsável por aceitar a entrada de participantes no grupo.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Obrigatórios
ID/Phone do grupo
Array com os números dos participantes a serem aceitos
***
## Request Body
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"groupId": "120363019502650977-group",
"phones": ["5544999999999", "5544888888888"]
}
```
***
## Response
### 200
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"value": true
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Criando grupos
Source: https://developer.z-api.io/group/create-group
POST /instances/{instanceId}/token/{token}/create-group
Cria um grupo com seus respectivos participantes
## Conceituação
Este método é responsável por criar um grupo com seus respectivos participantes.
Não é possível adicionar imagem durante a criação, mas você pode adicioná-la depois utilizando o método de atualizar imagem do grupo.
Você não deve passar o número conectado na lista de participantes. É necessário pelo menos um contato para criar o grupo, assim como no WhatsApp Web.
Ao criar um novo grupo, é necessário utilizar exclusivamente números de telefone. A identificação @lid não é compatível com a criação de grupos — caso seja enviada, o grupo será criado normalmente, porém o participante com @lid **não será incluído** e seu identificador será retornado no campo `phonesNotAdded`.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Obrigatórios
Define se será enviado um convite privado para os participantes que não puderem ser adicionados diretamente
Nome do grupo
Lista de números de telefone dos participantes
***
## Request Body
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"autoInvite": true,
"groupName": "Grupo Z-API",
"phones": ["5544999999999", "5544888888888"]
}
```
***
## Response
### 200
ID/Phone do grupo criado
Lista de identificadores que **não** foram adicionados ao grupo. Um participante pode aparecer aqui por dois motivos:
* **Uso de @lid**: identificadores no formato `@lid` não são suportados na criação de grupos. O grupo será criado normalmente, mas o participante com @lid ficará de fora e seu identificador será listado aqui.
* **Falta de permissão (autoInvite)**: quando um número não pode ser adicionado diretamente ao grupo e `autoInvite` está habilitado, um convite privado é enviado a ele. Enquanto o convite não é aceito, o número é retornado neste campo.
Link de convite do grupo
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"phone": "120363019502650977-group",
"phonesNotAdded": [
"2111897971174599@lid",
"5544777777777"
],
"invitationLink": "https://chat.whatsapp.com/GONwbGGDkLe8BifUWwLgct"
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Buscar grupos
Source: https://developer.z-api.io/group/get-groups
GET /instances/{instanceId}/token/{token}/groups
Retorna todos os grupos da instância
## Conceituação
Este método é responsável por retornar todos os grupos.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Query Parameters
Utilizado para paginação, informe a página de grupos que quer buscar
Especifica o tamanho do retorno de grupos por página
***
## Response
### 200
Indica se é um grupo ou não
Nome atribuído ao chat
ID/Phone do grupo
Número de mensagens não lidas no chat
Timestamp com a data e hora da última interação com o chat
0 ou 1 indica se você silenciou ou não este chat
Indica se o chat está arquivado
Indica se o chat está fixado
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
[
{
"isGroup": true,
"name": "Grupo teste",
"phone": "120263358412332916-group",
"unread": "0",
"lastMessageTime": "1730918668000",
"isMuted": "0",
"isMarkedSpam": "false",
"archived": "false",
"pinned": "false",
"muteEndTime": null,
"messagesUnread": "0"
}
]
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Obter link de convite
Source: https://developer.z-api.io/group/get-invitation-link
GET /instances/{instanceId}/token/{token}/group-invitation-link/{groupId}
Obtém o link de convite de um grupo
## Conceituação
Este método permite que você obtenha o link de convite de um grupo.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Path
ID/Phone do grupo
***
## Response
### 200
ID/Phone do grupo
Link de convite do grupo
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"phone": "120363019502650977-group",
"invitationLink": "https://chat.whatsapp.com/C1adgkdEGki7554BWDdMkd"
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Metadata do grupo por convite
Source: https://developer.z-api.io/group/group-invitation-metadata
GET /instances/{instanceId}/token/{token}/group-invitation-metadata
Retorna o metadata do grupo através do link de convite
## Conceituação
Este método retorna o metadata do grupo com todas informações do grupo e de seus participantes através do link de convite.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Query Parameters
Link de convite do grupo. Ex: [https://chat.whatsapp.com/KNmcL17DqVA0sqkQ5LLA5](https://chat.whatsapp.com/KNmcL17DqVA0sqkQ5LLA5)
***
## Response
### 200
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"phone": "120363019502650977-group",
"owner": "5511888888888",
"subject": "Meu grupo no Z-API",
"description": "descrição do grupo",
"creation": 1588721491000,
"invitationLink": "https://chat.whatsapp.com/KNmcL17DqVA0sqkQ5LLA5",
"contactsCount": 1,
"participantsCount": 1,
"participants": [
{
"phone": "5511888888888",
"isAdmin": false,
"isSuperAdmin": true
},
{
"phone": "5511777777777",
"isAdmin": false,
"isSuperAdmin": false
}
],
"subjectTime": 1617805323000,
"subjectOwner": "5511888888888",
"growthLocked": false,
"growthLockExpiration": 0
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Introdução
Source: https://developer.z-api.io/group/introduction
Entenda como funcionam os grupos na Z-API e os métodos disponíveis
## Conceituação
Neste tópico você vai conhecer todos os métodos disponíveis para manipulação de grupos.
Como já dito anteriormente para o WhatsApp tudo é um chat, sabendo disso o grupo nada mais é que um chat e basicamente tudo que você envia/recebe em um chat poderá enviar/receber com os grupos.
O grupo possui um ID/Fone que nada mais é do que o fone de quem criou concatenado com um timestamp algo parecido com "5511999999999-162327528", e é este ID/Fone que você vai utilizar como fone para realizar os envios para seus grupos.
Para você conseguir este ID/Fone utilize o método get/chats.
Neste tópico você também vai encontrar métodos para criação e administração de grupos.
***
## ID/Fone de Grupos
Para melhor frisar, pense que o id/fone do grupo é o número de quem criou concatenado com um timestamp, algo parecido com isso:
```
5511999999999-1623275280
```
**Atenção**
No dia 4 de novembro de 2021 o WhatsApp alterou o formato da criação de novos grupos.
**Antes:** `"phone": "5511999999999-1623281429"`
**Agora:** `"phone": "120363019502650977-group"`
# Sair do grupo
Source: https://developer.z-api.io/group/leave-group
POST /instances/{instanceId}/token/{token}/leave-group
Sai de um grupo ao qual participa
## Conceituação
Este método permite você sair de um grupo ao qual participa.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Obrigatórios
ID/Phone do grupo
***
## Request Body
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"groupId": "120363019502650977-group"
}
```
***
## Response
### 200
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"value": true
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Metadata do grupo (leve)
Source: https://developer.z-api.io/group/light-group-metadata
GET /instances/{instanceId}/token/{token}/light-group-metadata/{phone}
Retorna o metadata do grupo sem o link de convite
## Conceituação
Este método retorna o metadata do grupo com todas informações do grupo e de seus participantes com exceção do link de convite do grupo.
A única diferença entre este método e o Metadata do Grupo é que nesse não é retornado o link de convite do grupo, pois em certos momentos obter esse link é custoso e ligeiramente demorado. Caso precise do link, utilize o método [Obter link de convite do grupo](/group/get-invitation-link).
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Path
ID/Phone do grupo
***
## Response
### 200
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"phone": "120363019502650977-group",
"description": "Grupo Z-API",
"owner": "5511999999999",
"subject": "Meu grupo no Z-API",
"creation": 1588721491000,
"invitationLink": null,
"communityId": null,
"adminOnlyMessage": false,
"adminOnlySettings": false,
"requireAdminApproval": false,
"isGroupAnnouncement": false,
"participants": [
{
"phone": "5511888888888",
"isAdmin": false,
"isSuperAdmin": false
},
{
"phone": "5511777777777",
"isAdmin": true,
"isSuperAdmin": false,
"short": "ZAPIs",
"name": "ZAPIs Boys"
}
],
"subjectTime": 1617805323000,
"subjectOwner": "554497050785",
"growthLocked": false,
"growthLockExpiration": 0
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Mencionar todos
Source: https://developer.z-api.io/group/mention-all
POST /instances/{instanceId}/token/{token}/send-text
Menciona todos os participantes de um grupo
## Conceituação
Este método é responsável por mencionar todos os participantes de um grupo de uma só vez, sem a necessidade de listar cada número individualmente.
Para que a menção apareça como **@todos** em verde no WhatsApp (como uma menção real), o conteúdo da mensagem deve conter `@all`.
**Exemplo:** `"Mensagem Teste @all"`
* `@todos` **não funciona** — apenas `@all` é reconhecido pelo WhatsApp
* Funciona **somente em grupos** — não é compatível com Newsletters
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Obrigatórios
ID do grupo onde todos os participantes serão mencionados
Texto a ser enviado. Para que a menção apareça corretamente no WhatsApp, inclua `@all` no conteúdo da mensagem
Quando `true`, menciona todos os participantes do grupo
### Opcionais
Delay adicionado na mensagem. Você pode decidir entre um range de 1 a 15 sec. O delay default caso não seja informado é de 1 a 3 sec
***
## Request Body
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"phone": "120363019502650977-group",
"message": "Mensagem Teste @all",
"mentionAll": true
}
```
***
## Response
### 200
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"zaapId": "019DXXXXXXXXXXXXXXXXXXXXXXXX8B",
"messageId": "3EXXXXXXXXXXXXXXXD",
"id": "3XXXXXXXXXXXXXXXXX1D"
}
```
### 400
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"error": "mentionAll can only be used in groups"
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Mencionar grupo
Source: https://developer.z-api.io/group/mention-group
POST /instances/{instanceId}/token/{token}/send-text
Menciona grupos relacionados a uma comunidade
## Conceituação
Este método é responsável por fazer a menção de grupos relacionados a uma comunidade. O sistema restringe menções a grupos dentro da mesma estrutura de comunidade.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Obrigatórios
ID do grupo onde a menção será enviada
Texto a ser enviado (deve conter @ com o ID do grupo)
Array com os dados dos grupos a serem mencionados
ID do grupo sendo mencionado
Nome do grupo
### Opcionais
Delay adicionado na mensagem. Você pode decidir entre um range de 1 a 15 sec. O delay default caso não seja informado é de 1 a 3 sec
***
## Request Body
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"phone": "5511999999999-group",
"message": "Welcome to *Z-API group* @1203634230225498-group",
"groupMentioned": [
{
"phone": "1203634230225498-group",
"subject": "Z-API subgroup"
}
]
}
```
***
## Response
### 200
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"zaapId": "3999984263738042930CD6ECDE9VDWSA",
"messageId": "D241XXXX732339502B68",
"id": "D241XXXX732339502B68"
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Mencionar membro
Source: https://developer.z-api.io/group/mention-participant
POST /instances/{instanceId}/token/{token}/send-text
Menciona participantes em um grupo
## Conceituação
Este método é responsável por fazer a menção dos participantes em um grupo.
É possível mencionar vários membros ao mesmo tempo sem necessidade de incluir "@" explicitamente — basta incluir os números no array `mentioned`.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Obrigatórios
ID do grupo onde os participantes serão mencionados
Texto a ser enviado (deve conter @ com o número)
Números a serem mencionados
### Opcionais
Delay adicionado na mensagem. Você pode decidir entre um range de 1 a 15 sec. O delay default caso não seja informado é de 1 a 3 sec
***
## Request Body
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"phone": "5511999999999-group",
"message": "Welcome to *Z-API group* @5544999999999",
"mentioned": ["5544999999999"]
}
```
***
## Response
### 200
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"zaapId": "3999984263738042930CD6ECDE9VDWSA",
"messageId": "D241XXXX732339502B68",
"id": "D241XXXX732339502B68"
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Metadata do grupo
Source: https://developer.z-api.io/group/metadata-group
GET /instances/{instanceId}/token/{token}/group-metadata/{phone}
Retorna o metadata do grupo com todas informações e participantes
## Conceituação
Este método retorna o metadata do grupo com todas informações do grupo e de seus participantes.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Path
ID/Phone do grupo
***
## Response
### 200
ID/Phone do grupo
Descrição do grupo
Número do criador do grupo
Nome do grupo
Data de criação do grupo (timestamp)
Link de convite do grupo (apenas admin)
ID da comunidade
Apenas admin pode enviar mensagens
Apenas admin pode alterar configurações
Aprovação de admin necessária para entrar
Indica se é um grupo de avisos
Array com dados dos participantes
Indica se o grupo está com o link de convite suspenso
Timestamp de expiração da suspensão do link de convite
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"phone": "120363019502650977-group",
"description": "Grupo Z-API",
"owner": "5511999999999",
"subject": "Meu grupo no Z-API",
"creation": 1588721491000,
"invitationLink": "https://chat.whatsapp.com/40Aasd6af1",
"communityId": null,
"adminOnlyMessage": false,
"adminOnlySettings": false,
"requireAdminApproval": false,
"isGroupAnnouncement": false,
"participants": [
{
"phone": "5511888888888",
"isAdmin": false,
"isSuperAdmin": false
},
{
"phone": "5511777777777",
"isAdmin": true,
"isSuperAdmin": false,
"short": "ZAPIs",
"name": "ZAPIs Boys"
}
],
"subjectTime": 1617805323000,
"subjectOwner": "554497050785",
"growthLocked": false,
"growthLockExpiration": 0
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Redefinir link de convite
Source: https://developer.z-api.io/group/redefine-invitation-link
POST /instances/{instanceId}/token/{token}/redefine-invitation-link/{groupId}
Redefine o link de convite de um grupo
## Conceituação
Este método permite que você redefina o link de convite de um grupo.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Path
ID/Phone do grupo
***
## Response
### 200
Novo link de convite do grupo
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"invitationLink": "https://chat.whatsapp.com/C1adgkdEGki7554BWDdMkd"
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Rejeitar participantes
Source: https://developer.z-api.io/group/reject-participant
POST /instances/{instanceId}/token/{token}/reject-participant
Rejeita a entrada de participantes no grupo
## Conceituação
Este método é responsável por rejeitar a entrada de participantes no grupo.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Obrigatórios
ID/Phone do grupo
Array com os números dos participantes a serem rejeitados
***
## Request Body
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"groupId": "120363019502650977-group",
"phones": ["5544999999999", "5544888888888"]
}
```
***
## Response
### 200
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"value": true
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Remover admin do grupo
Source: https://developer.z-api.io/group/remove-admin
POST /instances/{instanceId}/token/{token}/remove-admin
Remove administradores de um grupo
## Conceituação
Este método é responsável por remover um ou mais administradores de um grupo.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Obrigatórios
ID/Phone do grupo
Array com os números dos administradores a serem removidos
***
## Request Body
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"groupId": "120363019502650977-group",
"phones": ["5544999999999", "5544888888888"]
}
```
***
## Response
### 200
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"value": true
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Remover participantes
Source: https://developer.z-api.io/group/remove-participant
POST /instances/{instanceId}/token/{token}/remove-participant
Remove participantes do grupo
## Conceituação
Este método é responsável por remover participantes do grupo.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Obrigatórios
ID/Phone do grupo
Array com os números dos participantes a serem removidos
***
## Request Body
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"groupId": "120363019502650977-group",
"phones": ["5544999999999", "5544888888888"]
}
```
***
## Response
### 200
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"value": true
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Alterar descrição
Source: https://developer.z-api.io/group/update-group-description
POST /instances/{instanceId}/token/{token}/update-group-description
Altera a descrição de um grupo
## Conceituação
Este método é responsável por alterar a descrição de um grupo.
Somente administradores podem alterar as preferências do grupo.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Obrigatórios
ID/Phone do grupo
Nova descrição do grupo
***
## Request Body
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"groupId": "120363019502650977-group",
"groupDescription": "descrição do grupo"
}
```
***
## Response
### 200
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"value": true
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Atualizar nome do grupo
Source: https://developer.z-api.io/group/update-group-name
POST /instances/{instanceId}/token/{token}/update-group-name
Altera o nome de um grupo existente
## Conceituação
Este método é responsável por alterar o nome de um grupo já existente.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Obrigatórios
ID/Phone do grupo
Novo nome do grupo
***
## Request Body
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"groupId": "120363019502650977-group",
"groupName": "Mudou o nome Meu grupo no Z-API"
}
```
***
## Response
### 200
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"value": true
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Atualizar imagem do grupo
Source: https://developer.z-api.io/group/update-group-photo
POST /instances/{instanceId}/token/{token}/update-group-photo
Altera a imagem de um grupo existente
## Conceituação
Este método é responsável por alterar a imagem de um grupo já existente.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Obrigatórios
ID/Phone do grupo
URL ou Base64 da imagem
***
## Request Body
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"groupId": "120363019502650977-group",
"groupPhoto": "https://www.z-api.io/wp-content/themes/z-api/dist/images/logo.svg"
}
```
***
## Response
### 200
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"value": true
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Configurações do grupo
Source: https://developer.z-api.io/group/update-group-settings
POST /instances/{instanceId}/token/{token}/update-group-settings
Altera as preferências e configurações do grupo
## Conceituação
Este método permite você alterar as preferências do grupo.
Somente administradores podem alterar as preferências do grupo.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Obrigatórios
ID/Phone do grupo
Apenas administradores podem enviar mensagens
Apenas administradores podem alterar configurações do grupo
Aprovação de administrador necessária para novos membros
Apenas administradores podem adicionar membros
***
## Request Body
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"phone": "120363019502650977-group",
"adminOnlyMessage": true,
"adminOnlySettings": true,
"requireAdminApproval": false,
"adminOnlyAddMember": true
}
```
***
## Response
### 200
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"value": true
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Responder texto com botões
Source: https://developer.z-api.io/message/reply-button
POST /instances/{instanceId}/token/{token}/reply-button
Responde um botão de lista de botões como se o usuário tivesse clicado
## Conceituação
Este endpoint permite responder um botão de lista de opções, simulando o clique do usuário em uma das opções enviadas anteriormente via [send-button-list](/message/send-button-list).
O botão deve ter sido previamente enviado e o **ID do botão** deve ser obtido via webhook de recebimento da mensagem.
***
#### Exemplo no WhatsApp
***
## Atributos
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Obrigatórios
Telefone (ou ID do grupo) no formato DDI DDD NÚMERO. Ex: 551199999999
ID do botão selecionado. Esse ID é obtido via webhook da mensagem recebida.
ID da mensagem que contém os botões enviados anteriormente.
***
## Request Body
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"phone": "5511999999999",
"responseButtonId": "1",
"messageId": "D241XXXX732339502B68"
}
```
## Response
### 200
id no z-api
id no whatsapp
Adicionado para compatibilidade com zapier, ele tem o mesmo valor do messageId
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"zaapId": "3999984263738042930CD6ECDE9VDWSA",
"messageId": "D241XXXX732339502B68",
"id": "D241XXXX732339502B68"
}
```
### 405
Verifique se o método HTTP utilizado está correto (POST).
### 415
Certifique-se de enviar o header Content-Type: application/json.
# Responder lista de opções
Source: https://developer.z-api.io/message/reply-option-list
POST /instances/{instanceId}/token/{token}/reply-option-list
Responde uma opção de lista de opções como se o usuário tivesse tocado nela
## Conceituação
Este endpoint permite responder uma lista de opções, simulando o toque do usuário em uma das opções enviadas anteriormente via [send-option-list](/message/send-option-list).
A lista precisa ter sido enviada ou recebida previamente. O **ID da opção** deve ser o mesmo `id` definido para essa opção no momento do envio da lista ou no webhook recebido.
***
#### Exemplo no WhatsApp
***
## Atributos
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Obrigatórios
Telefone (ou ID do grupo) no formato DDI DDD NÚMERO. Ex: 551199999999
ID da mensagem de lista de opções que está sendo respondida.
ID da opção escolhida. Deve ser o mesmo `id` definido na lista ao enviá-la.
***
## Request Body
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"phone": "5511999999999",
"messageId": "3EB0C767D82B0A6E9F5F",
"responseOptionId": "1"
}
```
## Response
### 200
id no z-api
id no whatsapp
Adicionado para compatibilidade com zapier, ele tem o mesmo valor do messageId
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"zaapId": "3999984263738042930CD6ECDE9VDWSA",
"messageId": "D241XXXX732339502B68",
"id": "D241XXXX732339502B68"
}
```
### 400
Verifique se o body da requisição foi enviado e se os campos obrigatórios (`phone`, `messageId` e `responseOptionId`) estão preenchidos.
### 405
Verifique se o método HTTP utilizado está correto (POST).
### 415
Certifique-se de enviar o header Content-Type: application/json.
# Responder botão de ação
Source: https://developer.z-api.io/message/reply-template-button
POST /instances/{instanceId}/token/{token}/reply-template-button
Responde um botão de botões de ação como se o usuário tivesse clicado
## Conceituação
Este endpoint permite responder um botão de ação, simulando o clique do usuário em uma das opções enviadas anteriormente via [send-button-actions](/message/send-button-actions).
Apenas botões do tipo **REPLY** podem ser respondidos. Botões de outros tipos não suportam resposta via API.
O botão deve ter sido previamente enviado e o **ID do botão** deve ser obtido via webhook de recebimento da mensagem.
***
#### Exemplo no WhatsApp
***
## Atributos
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Obrigatórios
Telefone (ou ID do grupo) no formato DDI DDD NÚMERO. Ex: 551199999999
ID do botão do tipo REPLY. Esse ID é obtido via webhook da mensagem recebida.
ID da mensagem que contém os botões enviados anteriormente.
***
## Request Body
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"phone": "5511999999999",
"responseTemplateButtonId": "1",
"messageId": "D241XXXX732339502B68"
}
```
## Response
### 200
id no z-api
id no whatsapp
Adicionado para compatibilidade com zapier, ele tem o mesmo valor do messageId
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"zaapId": "3999984263738042930CD6ECDE9VDWSA",
"messageId": "D241XXXX732339502B68",
"id": "D241XXXX732339502B68"
}
```
### 405
Verifique se o método HTTP utilizado está correto (POST).
### 415
Certifique-se de enviar o header Content-Type: application/json.
# Conversar com a Meta AI
Source: https://developer.z-api.io/metaai/conversation
POST /instances/{instanceId}/token/{token}/send-text
Envia mensagens de texto para a Meta AI no WhatsApp
## Conceituação
Este método permite a interação direta com a Meta AI no WhatsApp através da Z-API, facilitando o envio de mensagens de texto para obter respostas automatizadas e contextuais.
Você pode conversar com a Meta AI em chat privado usando o número `13135550002` ou incluí-la em grupos usando o ID do grupo.
Atualmente, a Meta AI na Z-API suporta apenas mensagens em texto. Isso significa que áudio, documentos, imagens e outros arquivos multimídia não são compatíveis nesta integração.
Esse recurso está disponível apenas para contas **pessoais** do WhatsApp.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Obrigatórios
Use `13135550002` para chat privado ou o ID do grupo para conversas em grupo
Texto da mensagem
### Opcionais
Delay adicionado na mensagem. Você pode decidir entre um range de 1 a 15 sec
Delay com status "Digitando...". Range de 1 a 15 sec
Inclua `13135550002` ao mencionar a Meta AI em grupos
***
## Request Body
**Chat privado:**
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"phone": "13135550002",
"message": "Olá, Meta AI! Gostaria de saber sobre..."
}
```
**Em grupo:**
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"phone": "5511999999999-group",
"message": "@13135550002 Olá, Meta AI! Gostaria de saber sobre...",
"mentioned": [13135550002]
}
```
***
## Response
### 200
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"zaapId": "3999984263738042930CD6ECDE9VDWSA",
"messageId": "D241XXXX732339502B68",
"id": "D241XXXX732339502B68"
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Introdução
Source: https://developer.z-api.io/metaai/introduction
Integração com a Meta AI na Z-API
## Integração com a Meta AI na Z-API
A Meta AI oferece uma gama de funcionalidades avançadas que transformam o WhatsApp em um verdadeiro assistente digital, visando tornar o dia a dia do usuário mais prático e interativo. Com a Meta AI, os usuários podem realizar pesquisas diretamente no aplicativo, sem precisar abrir navegadores, e recebem sugestões personalizadas para ações e eventos, como recomendações de restaurantes, locais de viagem e até planejamento de atividades com base nas preferências e necessidades especificadas.
Um dos recursos é a funcionalidade "Imagine," que permite a criação de imagens a partir de descrições textuais fornecidas pelo usuário, integrando um elemento visual único às interações. Essa abordagem expande as possibilidades de atendimento e criatividade, oferecendo suporte e soluções com respostas rápidas e envolventes.
Agora, a Z-API permite que empresas e desenvolvedores automatizem conversas, respondam com inteligência e melhorem significativamente a experiência de seus clientes. Essa conectividade permite que as interações com o usuário sejam mais dinâmicas, intuitivas e eficazes, agregando valor tanto ao suporte quanto ao engajamento geral com os clientes.
Esse recurso está disponível apenas para contas **pessoais** do WhatsApp, ou seja, não é acessível para contas business.
# Aceitar convite de admin
Source: https://developer.z-api.io/newsletter/accept-newsletter-admin-invite
POST /instances/{instanceId}/token/{token}/newsletter/accept-admin-invite/{newsletterId}
Aceita um convite para ser administrador de um canal
## Conceituação
Este método é responsável por aceitar um convite para ser administrador de um canal.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Path
ID do canal
***
## Response
### 201
Retorno de sucesso.
O ID do canal sempre deve conter o sufixo **@newsletter**, pois esse é o padrão utilizado pelo próprio WhatsApp.
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Criando canais
Source: https://developer.z-api.io/newsletter/create-newsletter
POST /instances/{instanceId}/token/{token}/create-newsletter
Cria um novo canal no WhatsApp
## Conceituação
Este método é responsável por criar um canal.
Não é possível adicionar imagem durante a criação, utilize o método de atualizar imagem do canal depois.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Body
Nome do canal
Descrição do canal
***
## Request Body
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"name": "Nome do canal",
"description": "Descrição do canal"
}
```
***
## Response
### 201
ID do canal criado
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"id": "999999999999999999@newsletter"
}
```
O ID do canal sempre deve conter o sufixo **@newsletter**, pois esse é o padrão utilizado pelo próprio WhatsApp.
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Deletar canal
Source: https://developer.z-api.io/newsletter/delete-newsletter
DELETE /instances/{instanceId}/token/{token}/delete-newsletter
Deleta um canal no WhatsApp
## Conceituação
Este método é responsável por deletar um canal.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Body
ID do canal
***
## Request Body
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"id": "999999999999999999@newsletter"
}
```
***
## Response
### 200
`true` caso tenha dado certo e `false` em caso de falha
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"value": true
}
```
O ID do canal sempre deve conter o sufixo **@newsletter**, pois esse é o padrão utilizado pelo próprio WhatsApp.
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Seguir canal
Source: https://developer.z-api.io/newsletter/follow-newsletter
PUT /instances/{instanceId}/token/{token}/follow-newsletter
Segue um canal no WhatsApp
## Conceituação
Este método é responsável por seguir um canal.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Body
ID do canal
***
## Request Body
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"id": "999999999999999999@newsletter"
}
```
***
## Response
### 200
`true` caso tenha dado certo e `false` em caso de falha
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"value": true
}
```
O ID do canal sempre deve conter o sufixo **@newsletter**, pois esse é o padrão utilizado pelo próprio WhatsApp.
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Introdução
Source: https://developer.z-api.io/newsletter/introduction
Entenda como funcionam os canais (newsletters) na Z-API
## Conceituação
Neste tópico você vai conhecer todos os métodos disponíveis para manipulação de canais.
**O que são os canais?** Os Canais do WhatsApp são semelhantes às páginas do Facebook, oferecendo um espaço para compartilhar informações, novidades, avisos e outros conteúdos relacionados a um tópico específico ou entidade. Esses canais podem ser criados por uma variedade de entidades, desde times de futebol até empresas que oferecem serviço de streaming, e permitem que os usuários acompanhem e se envolvam com o conteúdo de seu interesse.
É necessário enfatizar que o padrão utilizado pelo WhatsApp para os IDs dos canais é sempre com o sufixo **@newsletter**.
# Mutar canal
Source: https://developer.z-api.io/newsletter/mute-newsletter
PUT /instances/{instanceId}/token/{token}/mute-newsletter
Muta um canal no WhatsApp
## Conceituação
Este método é responsável por mutar um canal.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Body
ID do canal
***
## Request Body
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"id": "999999999999999999@newsletter"
}
```
***
## Response
### 200
`true` caso tenha dado certo e `false` em caso de falha
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"value": true
}
```
O ID do canal sempre deve conter o sufixo **@newsletter**, pois esse é o padrão utilizado pelo próprio WhatsApp.
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Listar canais
Source: https://developer.z-api.io/newsletter/newsletter-list
GET /instances/{instanceId}/token/{token}/newsletter
Retorna a lista de canais que você é dono e que segue
## Conceituação
Este método retorna o metadata dos canais que você é dono e dos canais que você segue.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
***
## Response
### 200
Retorna um array de objetos de canais.
ID do canal
Timestamp de criação do canal
Estado do canal (ACTIVE ou NON\_EXISTING)
Nome do canal
Descrição do canal
Número de inscritos do canal
Link de convite do canal
Status de verificação (VERIFIED ou UNVERIFIED)
URL da imagem do canal
URL da imagem de preview do canal
Informações de visualização do canal
Status de mute do canal (ON ou OFF)
Papel do usuário no canal (OWNER ou SUBSCRIBER)
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
[
{
"id": "999999999999999999@newsletter",
"creationTime": 1695124988,
"state": "ACTIVE",
"name": "Nome do canal",
"description": "Descrição",
"subscribersCount": "150",
"inviteLink": "https://whatsapp.com/channel/...",
"verification": "VERIFIED",
"picture": "https://...",
"preview": "https://...",
"viewMetadata": {
"mute": "OFF",
"role": "OWNER"
}
}
]
```
O ID do canal sempre deve conter o sufixo **@newsletter**, pois esse é o padrão utilizado pelo próprio WhatsApp.
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Metadata do canal
Source: https://developer.z-api.io/newsletter/newsletter-metadata
GET /instances/{instanceId}/token/{token}/newsletter/metadata/{newsletterId}
Retorna o metadata do canal com todas as informações
## Conceituação
Este método retorna o metadata do canal com todas as informações do canal e de sua visualização.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Path
ID do canal
### Query Parameters
Quando enviado como `true`, inclui na resposta o campo `subscribers` com a lista de seguidores do canal. O valor padrão é `false`.
***
## Response
### 200
ID do canal
Timestamp de criação do canal
Estado do canal (ACTIVE ou NON\_EXISTING)
Nome do canal
Descrição do canal
Número de inscritos do canal
Link de convite do canal
Status de verificação (VERIFIED ou UNVERIFIED)
URL da imagem do canal
URL da imagem de preview do canal
Informações de visualização do canal
Status de mute do canal (ON ou OFF)
Papel do usuário no canal (OWNER ou SUBSCRIBER)
Lista com até 9 seguidores do canal. Só é retornada quando o parâmetro `mustGetSubscribers` é enviado como `true`.
ID do seguidor (pode ser um número de telefone ou um `@lid`)
Número de telefone do seguidor, quando disponível
Nome de exibição do seguidor, quando disponível
Nome de usuário do seguidor, quando disponível
Papel do seguidor no canal (OWNER, ADMIN ou SUBSCRIBER)
Timestamp de quando o usuário começou a seguir o canal, quando disponível
Informações do perfil de admin do seguidor, quando ele for admin do canal
ID do admin
Nome do admin
Caminho da imagem de perfil do admin, quando disponível
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"id": "999999999999999999@newsletter",
"creationTime": 1695124988,
"state": "ACTIVE",
"name": "Nome do canal",
"description": "Descrição",
"subscribersCount": "150",
"inviteLink": "https://whatsapp.com/channel/...",
"verification": "VERIFIED",
"picture": "https://...",
"preview": "https://...",
"viewMetadata": {
"mute": "OFF",
"role": "OWNER"
},
"subscribers": [
{
"id": "199690293383294@lid",
"phoneNumber": null,
"displayName": null,
"username": null,
"role": "SUBSCRIBER",
"followTime": null,
"adminProfile": null
}
]
}
```
O ID do canal sempre deve conter o sufixo **@newsletter**, pois esse é o padrão utilizado pelo próprio WhatsApp.
O WhatsApp só retorna os seguidores que estiverem na lista de contatos de quem realizou a requisição, e é necessário que quem realiza a requisição seja admin do canal. Além disso, essa listagem retorna no máximo 9 seguidores, o mesmo limite exibido na tela de informações do canal no WhatsApp Web. Para obter a listagem completa de seguidores, utilize o endpoint [Listar seguidores do canal](/newsletter/newsletter-subscribers).
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Remover admin do canal
Source: https://developer.z-api.io/newsletter/newsletter-remove-admin
POST /instances/{instanceId}/token/{token}/newsletter/remove-admin/{newsletterId}
Remove um usuário da administração do canal
## Conceituação
Este método é responsável por remover um usuário da administração do canal.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Path
ID do canal
### Body
Número do usuário a ser removido
***
## Request Body
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"phone": "5511999999999"
}
```
***
## Response
### 201
Retorno de sucesso.
O ID do canal sempre deve conter o sufixo **@newsletter**, pois esse é o padrão utilizado pelo próprio WhatsApp.
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Anular convite de admin
Source: https://developer.z-api.io/newsletter/newsletter-revoke-admin-invite
POST /instances/{instanceId}/token/{token}/newsletter/revoke-admin-invite/{newsletterId}
Anula um convite de administrador de um canal
## Conceituação
Este método é responsável por anular um convite de administrador de um canal.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Path
ID do canal
### Body
Número do usuário
***
## Request Body
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"phone": "5511999999999"
}
```
***
## Response
### 201
Retorno de sucesso.
O ID do canal sempre deve conter o sufixo **@newsletter**, pois esse é o padrão utilizado pelo próprio WhatsApp.
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Listar seguidores do canal
Source: https://developer.z-api.io/newsletter/newsletter-subscribers
GET /instances/{instanceId}/token/{token}/newsletter/subscribers/{newsletterId}
Retorna a lista completa de seguidores do canal
## Conceituação
Este método retorna a lista completa de seguidores do canal.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Path
ID do canal
***
## Response
### 200
Retorna um array de objetos de seguidores.
ID do seguidor (pode ser um número de telefone ou um `@lid`)
Número de telefone do seguidor, quando disponível
Nome de exibição do seguidor, quando disponível
Nome de usuário do seguidor, quando disponível
Papel do seguidor no canal (OWNER, ADMIN ou SUBSCRIBER)
Timestamp de quando o usuário começou a seguir o canal, quando disponível
Informações do perfil de admin do seguidor, quando ele for admin do canal
ID do admin
Nome do admin
Caminho da imagem de perfil do admin, quando disponível
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
[
{
"id": "199690293383294@lid",
"phoneNumber": null,
"displayName": null,
"username": null,
"role": "SUBSCRIBER",
"followTime": null,
"adminProfile": null
},
{
"id": "277454937673921@lid",
"phoneNumber": null,
"displayName": null,
"username": null,
"role": "SUBSCRIBER",
"followTime": null,
"adminProfile": null
}
]
```
O ID do canal sempre deve conter o sufixo **@newsletter**, pois esse é o padrão utilizado pelo próprio WhatsApp.
O WhatsApp só retorna os seguidores que estiverem na lista de contatos de quem realizou a requisição, e é necessário que quem realiza a requisição seja admin do canal. Essa listagem não possui paginação, retornando todos os seguidores disponíveis em uma única resposta.
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Encontrar canais
Source: https://developer.z-api.io/newsletter/search-newsletter
POST /instances/{instanceId}/token/{token}/search-newsletter
Busca canais através de filtros
## Conceituação
Este método retorna uma lista com dados de canais, de acordo com a busca realizada através de filtros passados no body da requisição.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Body
Limite de registros
Filtros da busca
Array de códigos ISO de países
Tipo de visualização (RECOMMENDED, TRENDING, POPULAR ou NEW)
Texto de busca
***
## Request Body
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"limit": 50,
"view": "TRENDING",
"filters": {
"countryCodes": ["BR", "AF", "CA"]
},
"searchText": "Z-API"
}
```
***
## Response
### 200
Retorna um array de objetos de canais.
ID do canal
Timestamp de criação do canal
Estado do canal (ACTIVE ou NON\_EXISTING)
Nome do canal
Descrição do canal
Número de inscritos do canal
Link de convite do canal
Status de verificação (VERIFIED ou UNVERIFIED)
URL da imagem do canal
URL da imagem de preview do canal
Informações de visualização do canal
Status de mute do canal (ON ou OFF)
Papel do usuário no canal (OWNER ou SUBSCRIBER)
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
[
{
"id": "999999999999999999@newsletter",
"creationTime": 1695124988,
"state": "ACTIVE",
"name": "Nome do canal",
"description": "Descrição",
"subscribersCount": "150",
"inviteLink": "https://whatsapp.com/channel/...",
"verification": "VERIFIED",
"picture": "https://...",
"preview": "https://...",
"viewMetadata": {
"mute": "OFF",
"role": "OWNER"
}
}
]
```
O ID do canal sempre deve conter o sufixo **@newsletter**, pois esse é o padrão utilizado pelo próprio WhatsApp.
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Transferir propriedade do canal
Source: https://developer.z-api.io/newsletter/transfer-newsletter-ownership
POST /instances/{instanceId}/token/{token}/newsletter/transfer-ownership/{newsletterId}
Transfere a propriedade de um canal a outro usuário
## Conceituação
Este método é responsável por transferir a propriedade de um canal a outro usuário, o qual seja administrador desse canal.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Path
ID do canal
### Body
Número do novo proprietário
Define se você deixará de ser admin após a transferência
***
## Request Body
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"phone": "5511999999999",
"quitAdmin": true
}
```
***
## Response
### 200
`true` caso tenha dado certo e `false` em caso de falha
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"value": true
}
```
O ID do canal sempre deve conter o sufixo **@newsletter**, pois esse é o padrão utilizado pelo próprio WhatsApp.
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Deixar de seguir canal
Source: https://developer.z-api.io/newsletter/unfollow-newsletter
PUT /instances/{instanceId}/token/{token}/unfollow-newsletter
Deixa de seguir um canal no WhatsApp
## Conceituação
Este método é responsável por deixar de seguir um canal.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Body
ID do canal
***
## Request Body
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"id": "999999999999999999@newsletter"
}
```
***
## Response
### 200
`true` caso tenha dado certo e `false` em caso de falha
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"value": true
}
```
O ID do canal sempre deve conter o sufixo **@newsletter**, pois esse é o padrão utilizado pelo próprio WhatsApp.
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Desmutar canal
Source: https://developer.z-api.io/newsletter/unmute-newsletter
PUT /instances/{instanceId}/token/{token}/unmute-newsletter
Desmuta um canal no WhatsApp
## Conceituação
Este método é responsável por desmutar um canal.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Body
ID do canal
***
## Request Body
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"id": "999999999999999999@newsletter"
}
```
***
## Response
### 200
`true` caso tenha dado certo e `false` em caso de falha
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"value": true
}
```
O ID do canal sempre deve conter o sufixo **@newsletter**, pois esse é o padrão utilizado pelo próprio WhatsApp.
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Configurações do canal
Source: https://developer.z-api.io/newsletter/update-newsletter-config
POST /instances/{instanceId}/token/{token}/newsletter/settings/{newsletterId}
Altera as configurações de um canal
## Conceituação
Este método é responsável por alterar as configurações de um canal.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Path
ID do canal
### Body
Tipo de reações permitidas (`basic` ou `all`)
***
## Request Body
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"reactionCodes": "basic"
}
```
***
## Response
### 201
`true` caso tenha dado certo e `false` em caso de falha
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"value": true
}
```
O ID do canal sempre deve conter o sufixo **@newsletter**, pois esse é o padrão utilizado pelo próprio WhatsApp.
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Atualizar descrição do canal
Source: https://developer.z-api.io/newsletter/update-newsletter-description
POST /instances/{instanceId}/token/{token}/update-newsletter-description
Altera a descrição de um canal existente
## Conceituação
Este método é responsável por alterar a descrição de um canal já existente.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Body
ID do canal com sufixo @newsletter
Nova descrição do canal
***
## Request Body
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"id": "999999999999999999@newsletter",
"description": "Nova descrição do canal"
}
```
***
## Response
### 201
`true` caso tenha dado certo e `false` em caso de falha
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"value": true
}
```
O ID do canal sempre deve conter o sufixo **@newsletter**, pois esse é o padrão utilizado pelo próprio WhatsApp.
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Atualizar nome do canal
Source: https://developer.z-api.io/newsletter/update-newsletter-name
POST /instances/{instanceId}/token/{token}/update-newsletter-name
Altera o nome de um canal existente
## Conceituação
Este método é responsável por alterar o nome de um canal já existente.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Body
ID do canal com sufixo @newsletter
Novo nome do canal
***
## Request Body
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"id": "999999999999999999@newsletter",
"name": "Novo nome do canal"
}
```
***
## Response
### 201
`true` caso tenha dado certo e `false` em caso de falha
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"value": true
}
```
O ID do canal sempre deve conter o sufixo **@newsletter**, pois esse é o padrão utilizado pelo próprio WhatsApp.
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Atualizar imagem do canal
Source: https://developer.z-api.io/newsletter/update-newsletter-picture
POST /instances/{instanceId}/token/{token}/update-newsletter-picture
Altera a imagem de um canal existente
## Conceituação
Este método é responsável por alterar a imagem de um canal já existente.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Body
ID do canal com sufixo @newsletter
URL ou Base64 da imagem
***
## Request Body
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"id": "999999999999999999@newsletter",
"pictureUrl": "https://example.com/logo.svg"
}
```
***
## Response
### 201
`true` caso tenha dado certo e `false` em caso de falha
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"value": true
}
```
O ID do canal sempre deve conter o sufixo **@newsletter**, pois esse é o padrão utilizado pelo próprio WhatsApp.
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Listar contatos não permitidos
Source: https://developer.z-api.io/privacy/get-disallowed-contacts
GET /instances/{instanceId}/token/{token}/privacy/disallowed-contacts
Lista os contatos na blacklist para certas interações com sua conta
## Conceituação
Através deste método, é possível listar os contatos que estão na lista de não permitidos (blacklist) para certas interações com sua conta.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Query Parameters
Define o escopo do bloqueio: `lastSeen`, `photo`, `description` ou `groupAdd`
***
## Response
### 200
Lista de números de telefone bloqueados
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"disallowedContacts": [
"554411111111",
"554422222222"
]
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Introdução
Source: https://developer.z-api.io/privacy/introduction
Configurações de privacidade do WhatsApp via API
## Conceituação
Neste tópico você vai conhecer todos os métodos disponíveis para configurações de privacidade.
As **configurações de privacidade** do WhatsApp são um conjunto de opções e recursos que permitem aos usuários controlar quem pode acessar suas informações pessoais e interagir com eles no aplicativo de mensagens. Essas configurações visam proteger a privacidade dos usuários e oferecer controle sobre o compartilhamento de informações. Os principais elementos das configurações de privacidade incluem a possibilidade de definir quem pode ver sua **foto de perfil**, informações de **visto por último** e **confirmar a leitura de mensagens**.
# Permissão de adição em grupos
Source: https://developer.z-api.io/privacy/set-group-add-permission
POST /instances/{instanceId}/token/{token}/privacy/group-add
Configura quem pode te adicionar em grupos
## Conceituação
Através deste método, é possível configurar quem pode te adicionar em grupos.
A blacklist (lista de contatos não permitidos) é diferente para cada configuração de privacidade.
Não é necessário reenviar o atributo `contactsBlacklist` com os contatos já adicionados. Esse parâmetro é somente para alterações na blacklist.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Obrigatórios
Tipo de permissão: `ALL` (todos), `CONTACTS` (apenas contatos) ou `CONTACT_BLACKLIST` (todos os contatos exceto os da blacklist)
### Opcionais
Lista de alterações na blacklist (apenas para tipo CONTACT\_BLACKLIST)
Ação: `add` (adicionar) ou `remove` (remover)
Número do contato
***
## Request Body
**Permitir todos:**
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"type": "ALL"
}
```
**Com blacklist:**
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"type": "CONTACT_BLACKLIST",
"contactsBlacklist": [
{ "action": "add", "phone": "554411111111" },
{ "action": "remove", "phone": "554422222222" }
]
}
```
***
## Response
### 200
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"success": true
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Visto por último
Source: https://developer.z-api.io/privacy/set-last-seen
POST /instances/{instanceId}/token/{token}/privacy/last-seen
Configura quem pode ver seu 'visto por último'
## Conceituação
Através deste método, é possível configurar quem pode ver seu "visto por último".
A blacklist (lista de contatos não permitidos) é diferente para cada configuração de privacidade.
Não é necessário reenviar o atributo `contactsBlacklist` com os contatos já adicionados. Esse parâmetro é somente para alterações na blacklist.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Obrigatórios
Tipo de visualização: `ALL` (todos), `NONE` (ninguém), `CONTACTS` (apenas contatos) ou `CONTACT_BLACKLIST` (todos os contatos exceto os da blacklist)
### Opcionais
Lista de alterações na blacklist (apenas para tipo CONTACT\_BLACKLIST)
Ação: `add` (adicionar) ou `remove` (remover)
Número do contato
***
## Request Body
**Visível para todos:**
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"visualizationType": "ALL"
}
```
**Com blacklist:**
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"visualizationType": "CONTACT_BLACKLIST",
"contactsBlacklist": [
{ "action": "add", "phone": "554411111111" },
{ "action": "remove", "phone": "554422222222" }
]
}
```
***
## Response
### 200
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"success": true
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Mensagens temporárias
Source: https://developer.z-api.io/privacy/set-messages-duration
POST /instances/{instanceId}/token/{token}/privacy/messages-duration
Configura mensagens temporárias para novas conversas individuais
## Conceituação
Através deste método, é possível configurar mensagens temporárias para novas conversas individuais.
Esta configuração afeta apenas **novas conversas**, não é retroativa para conversas existentes.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Query Parameters
Duração das mensagens: `days90` (90 dias), `days7` (7 dias), `hours24` (24 horas) ou `disable` (desabilitar)
***
## Response
### 200
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"success": true
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Foto do perfil
Source: https://developer.z-api.io/privacy/set-photo-visualization
POST /instances/{instanceId}/token/{token}/privacy/photo-visualization
Configura quem pode ver sua foto do perfil
## Conceituação
Através deste método, é possível configurar quem pode ver sua foto do perfil.
A blacklist (lista de contatos não permitidos) é diferente para cada configuração de privacidade.
Não é necessário reenviar o atributo `contactsBlacklist` com os contatos já adicionados. Esse parâmetro é somente para alterações na blacklist.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Obrigatórios
Tipo de visualização: `ALL` (todos), `NONE` (ninguém), `CONTACTS` (apenas contatos) ou `CONTACT_BLACKLIST` (todos os contatos exceto os da blacklist)
### Opcionais
Lista de alterações na blacklist (apenas para tipo CONTACT\_BLACKLIST)
Ação: `add` (adicionar) ou `remove` (remover)
Número do contato
***
## Request Body
**Visível para todos:**
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"visualizationType": "ALL"
}
```
**Com blacklist:**
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"visualizationType": "CONTACT_BLACKLIST",
"contactsBlacklist": [
{ "action": "add", "phone": "554411111111" },
{ "action": "remove", "phone": "554422222222" }
]
}
```
***
## Response
### 200
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"success": true
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Recado do perfil
Source: https://developer.z-api.io/privacy/set-privacy-description
POST /instances/{instanceId}/token/{token}/privacy/description
Configura quem pode ver o recado do seu perfil
## Conceituação
Através deste método, é possível configurar quem pode ver o recado do seu perfil.
A blacklist (lista de contatos não permitidos) é diferente para cada configuração de privacidade.
Não é necessário reenviar o atributo `contactsBlacklist` com os contatos já adicionados. Esse parâmetro é somente para alterações na blacklist.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Obrigatórios
Tipo de visualização: `ALL` (todos), `NONE` (ninguém), `CONTACTS` (apenas contatos) ou `CONTACT_BLACKLIST` (todos os contatos exceto os da blacklist)
### Opcionais
Lista de alterações na blacklist (apenas para tipo CONTACT\_BLACKLIST)
Ação: `add` (adicionar) ou `remove` (remover)
Número do contato
***
## Request Body
**Visível para todos:**
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"visualizationType": "ALL"
}
```
**Com blacklist:**
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"visualizationType": "CONTACT_BLACKLIST",
"contactsBlacklist": [
{ "action": "add", "phone": "554411111111" },
{ "action": "remove", "phone": "554422222222" }
]
}
```
***
## Response
### 200
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"success": true
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Visibilidade online
Source: https://developer.z-api.io/privacy/set-privacy-online
POST /instances/{instanceId}/token/{token}/privacy/online
Configura quem pode ver quando você estiver online
## Conceituação
Através deste método, é possível configurar quem pode ver quando você estiver online.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Obrigatórios
Tipo de visualização: `ALL` (todos podem ver) ou `SAME_LAST_SEEN` (segue a mesma configuração do "visto por último")
***
## Request Body
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"visualizationType": "ALL"
}
```
***
## Response
### 200
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"success": true
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Confirmação de leitura
Source: https://developer.z-api.io/privacy/set-read-receipts
POST /instances/{instanceId}/token/{token}/privacy/read-receipts
Configura as confirmações de leitura de mensagens
## Conceituação
Através deste método, é possível configurar as confirmações de leitura de mensagens (não aplicável a grupos).
Ao desabilitar as confirmações de leitura, você também não conseguirá ver se suas próprias mensagens foram lidas.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Query Parameters
Valor da configuração: `enable` (habilitar) ou `disable` (desabilitar)
***
## Response
### 200
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"success": true
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Adicionar produtos à coleção
Source: https://developer.z-api.io/business/add-product-to-collection
POST /instances/{instanceId}/token/{token}/catalogs/collection/add-product
Adiciona produtos a uma coleção existente no catálogo do WhatsApp Business
## Conceituação
Este método é responsável por adicionar produtos a uma coleção existente no catálogo do WhatsApp Business.
Ao adicionar ou remover produtos de uma coleção, o ID da mesma é alterado pelo WhatsApp. Utilize o ID retornado para operações subsequentes.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Obrigatórios
ID da coleção
IDs dos produtos a serem adicionados
***
## Request Body
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"collectionId": "658387616418640",
"productIds": ["6643149779134830"]
}
```
***
## Response
### 200
`true` caso tenha dado certo e `false` em caso de falha
Novo ID da coleção após a alteração
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"success": true,
"collectionId": "1798362193933497"
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Listar categorias
Source: https://developer.z-api.io/business/available-categories
GET /instances/{instanceId}/token/{token}/business/available-categories
Lista as categorias disponíveis para o WhatsApp Business
## Conceituação
Este método é responsável por listar todas as categorias disponíveis para configuração no perfil do WhatsApp Business.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Query Parameters
Busca por categoria
***
## Response
### 200
Nome de exibição da categoria
Label da categoria
ID da categoria
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
[
{
"displayName": "Outras empresas",
"label": "OTHER_COMPANIES",
"id": "629412378414563"
}
]
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Alterar horário de funcionamento
Source: https://developer.z-api.io/business/business-hours
POST /instances/{instanceId}/token/{token}/business/hours
Altera o horário de funcionamento da empresa no WhatsApp Business
## Conceituação
Este método é responsável por alterar o horário de funcionamento da empresa no perfil do WhatsApp Business.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Obrigatórios
Fuso horário
### Opcionais
Modo de funcionamento: `specificHours`, `open24h` ou `appointmentOnly`
Lista de dias com horários de funcionamento (dayOfWeek, openTime, closeTime)
***
## Request Body
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"timezone": "America/Sao_Paulo",
"days": [
{
"dayOfWeek": "MONDAY",
"openTime": "08:00",
"closeTime": "12:00"
}
],
"mode": "specificHours"
}
```
***
## Response
### 201
`true` caso tenha dado certo e `false` em caso de falha
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"success": true
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Atribuir anotações a um chat
Source: https://developer.z-api.io/business/chats-notes
POST /instances/{instanceId}/token/{token}/chats/{phone}/notes
Atribui notas a um chat
## Conceituação
Através deste método, é possível atribuir notas a um chat no WhatsApp Business.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Path
Telefone do chat
### Obrigatórios
Texto da anotação
***
## Request Body
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"notes": "anotação"
}
```
***
## Response
### 200
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"success": true
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Alterar endereço da empresa
Source: https://developer.z-api.io/business/company-address
POST /instances/{instanceId}/token/{token}/business/company-address
Altera o endereço da empresa no WhatsApp Business
## Conceituação
Este método é responsável por alterar o endereço da empresa no perfil do WhatsApp Business.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Obrigatórios
Endereço comercial. Envie vazio para remover
***
## Request Body
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"value": "Endereço da empresa"
}
```
***
## Response
### 201
`true` caso tenha dado certo e `false` em caso de falha
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"success": true
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Atribuir categorias
Source: https://developer.z-api.io/business/company-categories
POST /instances/{instanceId}/token/{token}/business/categories
Atribui categorias ao perfil do WhatsApp Business
## Conceituação
Este método é responsável por atribuir categorias ao perfil do WhatsApp Business.
Máximo de **3 categorias** (mínimo 1). Os valores devem ser os IDs ou labels retornados pela API de [Listar categorias](/business/available-categories).
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Obrigatórios
IDs ou labels das categorias
***
## Request Body
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"categories": ["RESTAURANT", "FINANCE", "629412378414563"]
}
```
***
## Response
### 201
`true` caso tenha dado certo e `false` em caso de falha
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"success": true
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Alterar descrição da empresa
Source: https://developer.z-api.io/business/company-description
POST /instances/{instanceId}/token/{token}/business/company-description
Altera a descrição da empresa no WhatsApp Business
## Conceituação
Este método é responsável por alterar a descrição da empresa no perfil do WhatsApp Business.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Obrigatórios
Texto da descrição. Envie vazio para remover
***
## Request Body
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"value": "Texto da descrição"
}
```
***
## Response
### 201
`true` caso tenha dado certo e `false` em caso de falha
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"success": true
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Alterar email da empresa
Source: https://developer.z-api.io/business/company-email
POST /instances/{instanceId}/token/{token}/business/company-email
Altera o email da empresa no WhatsApp Business
## Conceituação
Este método é responsável por alterar o email da empresa no perfil do WhatsApp Business.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Obrigatórios
Email da empresa. Envie vazio para remover
***
## Request Body
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"value": "email@example.com"
}
```
***
## Response
### 201
`true` caso tenha dado certo e `false` em caso de falha
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"success": true
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Alterar websites da empresa
Source: https://developer.z-api.io/business/company-websites
POST /instances/{instanceId}/token/{token}/business/company-websites
Altera os websites da empresa no WhatsApp Business
## Conceituação
Este método é responsável por alterar os websites da empresa no perfil do WhatsApp Business.
Máximo de **2 websites** por conta.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Obrigatórios
URLs dos websites. Envie array vazio para remover
***
## Request Body
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"websites": ["https://example.com", "https://example2.org"]
}
```
***
## Response
### 201
`true` caso tenha dado certo e `false` em caso de falha
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"success": true
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Criar coleção
Source: https://developer.z-api.io/business/create-collection
POST /instances/{instanceId}/token/{token}/catalogs/collection
Cria uma nova coleção no catálogo do WhatsApp Business
## Conceituação
Este método é responsável por criar uma nova coleção no catálogo do WhatsApp Business, permitindo agrupar produtos de forma organizada.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Obrigatórios
Nome da coleção
IDs dos produtos
***
## Request Body
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"name": "Nome da coleção",
"productIds": ["121212121212", "232323232323"]
}
```
***
## Response
### 200
ID da coleção criada
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"collectionId": "123456789123"
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Criar nova etiqueta
Source: https://developer.z-api.io/business/create-tag
POST /instances/{instanceId}/token/{token}/business/create-tag
Cria uma nova etiqueta para atribuição em chats
## Conceituação
Nesse método você será capaz de criar uma nova etiqueta disponível para atribuição em chats.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Obrigatórios
Nome da etiqueta
### Opcionais
Índice da cor desejada conforme disponível na API de cores
***
## Request Body
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"name": "Nome da etiqueta",
"color": 1
}
```
***
## Response
### 200
ID da etiqueta criada
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"id": "10"
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Deletar coleção
Source: https://developer.z-api.io/business/delete-collection
DELETE /instances/{instanceId}/token/{token}/catalogs/collection/{collectionId}
Deleta uma coleção do catálogo do WhatsApp Business
## Conceituação
Este método é responsável por deletar uma coleção existente no catálogo do WhatsApp Business.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Path
ID da coleção a ser deletada
***
## Response
### 200
`true` caso tenha dado certo e `false` em caso de falha
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"success": true
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Deletar produto
Source: https://developer.z-api.io/business/delete-product
DELETE /instances/{instanceId}/token/{token}/products/{productId}
Deleta um produto pelo ID
## Conceituação
Nesse método você será capaz de deletar um produto pelo seu ID.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Path
ID do produto a ser deletado
***
## Response
### 200
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"success": true
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o DELETE conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Deletar etiqueta
Source: https://developer.z-api.io/business/delete-tag
DELETE /instances/{instanceId}/token/{token}/business/tag/{tagId}
Deleta uma etiqueta pelo ID
## Conceituação
Através deste método, é possível deletar uma etiqueta.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Path
ID da etiqueta
***
## Response
### 200
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"success": true
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Editar coleção
Source: https://developer.z-api.io/business/edit-collection
POST /instances/{instanceId}/token/{token}/catalogs/collection-edit/{collectionId}
Edita o nome de uma coleção existente no catálogo do WhatsApp Business
## Conceituação
Este método é responsável por editar uma coleção existente no catálogo do WhatsApp Business.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Path
ID da coleção a ser editada
### Obrigatórios
Novo nome da coleção
***
## Request Body
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"name": "Novo nome da coleção"
}
```
***
## Response
### 200
`true` caso tenha dado certo e `false` em caso de falha
ID da coleção editada
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"success": true,
"collectionId": "228078660281007"
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Criar/editar produto
Source: https://developer.z-api.io/business/edit-product
POST /instances/{instanceId}/token/{token}/products
Cadastra ou atualiza um produto no catálogo
## Conceituação
Nesse método você será capaz de cadastrar e atualizar um produto no seu catálogo.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Obrigatórios
Nome do produto
Preço do produto
Tipo de moeda (ex: BRL)
Descrição do produto
URLs das imagens do produto
### Opcionais
Ocultar produto no catálogo
Preço promocional
ID do produto
URL do produto
***
## Request Body
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"currency": "BRL",
"description": "Uma descrição do produto",
"images": ["https://avatars.githubusercontent.com/u/60630101?s=200&v=4"],
"isHidden": false,
"name": "Meu primeiro produto",
"price": 20,
"salePrice": 18,
"retailerId": "002",
"url": "https://z-api.io"
}
```
***
## Response
### 200
ID do produto criado/atualizado
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"id": "4741575945866725"
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Editar etiqueta
Source: https://developer.z-api.io/business/edit-tag
POST /instances/{instanceId}/token/{token}/business/edit-tag/{tagId}
Edita uma etiqueta existente
## Conceituação
Através deste método, é possível editar uma etiqueta.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Path
ID da etiqueta
### Obrigatórios
Novo nome da etiqueta
### Opcionais
Índice da cor desejada conforme disponível na API de cores
***
## Request Body
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"name": "Nome da etiqueta",
"color": 2
}
```
***
## Response
### 200
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"success": true
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Pegar produto (ID)
Source: https://developer.z-api.io/business/get-product-id
GET /instances/{instanceId}/token/{token}/products/{productId}
Retorna os dados de um produto específico pelo ID
## Conceituação
Nesse método você será capaz de pegar os dados de um produto específico pelo seu ID do catálogo do WhatsApp Business.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Path
ID do produto
***
## Response
### 200
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"cartEnabled": true,
"catalogId": "999999999999999",
"availability": "in stock",
"id": "999999999999999",
"retailerId": null,
"description": "Descrição do produto",
"price": "100000",
"salePrice": "90000",
"currency": "BRL",
"name": "Mouse",
"images": ["https://..."]
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Pegar produtos
Source: https://developer.z-api.io/business/get-products
GET /instances/{instanceId}/token/{token}/catalogs
Retorna os produtos do catálogo do WhatsApp Business
## Conceituação
Nesse método você será capaz de pegar os produtos de um catálogo do WhatsApp Business.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Query Parameters
Token de paginação para buscar mais registros
***
## Response
### 200
Status do carrinho de compras ativo
Lista de produtos do catálogo
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"cartEnabled": true,
"products": [
{
"availability": "in stock",
"id": "999999999999999",
"retailerId": null,
"description": "Descrição do mouse",
"price": "100000",
"salePrice": "90000",
"currency": "BRL",
"name": "Mouse",
"quantity": null,
"images": ["https://..."]
}
]
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 414 - URI Too Large
Em alguns casos o envio do nextCursor pode causar um erro 414 "URI Too Large". Para resolver esse problema implementamos uma V2 para essa rota da API que aceita requisições do tipo POST para que você possa enviar o nextCursor no corpo da requisição. Consulte a rota [Pegar Produtos V2](/business/get-products-v2).
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Pegar produtos (telefone)
Source: https://developer.z-api.io/business/get-products-phone
GET /instances/{instanceId}/token/{token}/catalogs/{phone}
Retorna os produtos do catálogo de qualquer número business
## Conceituação
Nesse método você será capaz de pegar os produtos de um catálogo do WhatsApp Business de qualquer número, seja o seu ou de outra pessoa.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Path
Número de telefone do WhatsApp Business
### Query Parameters
Token de paginação para buscar mais registros
***
## Response
### 200
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"cartEnabled": true,
"products": [
{
"availability": "in stock",
"id": "999999999999999",
"retailerId": null,
"description": "Descrição do mouse",
"price": "100000",
"salePrice": "90000",
"currency": "BRL",
"name": "Mouse",
"quantity": null,
"images": ["https://..."]
}
]
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Pegar produtos V2 (telefone)
Source: https://developer.z-api.io/business/get-products-phone-v2
POST /instances/{instanceId}/token/{token}/catalogs/{phone}
Retorna os produtos do catálogo de qualquer número (V2 com paginação via body)
## Conceituação
Nesse método você será capaz de pegar os produtos de um catálogo do WhatsApp Business de qualquer número, sendo o seu catálogo ou de outra pessoa. Esta versão utiliza POST com paginação via body.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Path
Número de telefone do WhatsApp Business
### Body
Token de paginação para buscar mais registros
***
## Request Body
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"nextCursor": "eyJwbHVnaW5fbmFtZSI6IldIQVRTQVBQX0NBVEFMT0ciLCJxdWVy..."
}
```
***
## Response
### 200
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"cartEnabled": true,
"products": [
{
"availability": "in stock",
"id": "999999999999999",
"retailerId": null,
"description": "Descrição do mouse",
"price": "100000",
"salePrice": "90000",
"currency": "BRL",
"name": "Mouse",
"quantity": null,
"images": ["https://..."]
}
]
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Pegar produtos V2
Source: https://developer.z-api.io/business/get-products-v2
POST /instances/{instanceId}/token/{token}/catalogs
Retorna os produtos do catálogo (V2 com paginação via body)
## Conceituação
Nesse método você será capaz de pegar os produtos de um catálogo do WhatsApp Business. Esta versão utiliza POST com paginação via body, ideal para quando o cursor de paginação é muito grande para a URL.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Body
Token de paginação para buscar mais registros
***
## Request Body
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"nextCursor": "eyJwbHVnaW5fbmFtZSI6IldIQVRTQVBQX0NBVEFMT0ciLCJxdWVy..."
}
```
***
## Response
### 200
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"cartEnabled": true,
"products": [
{
"availability": "in stock",
"id": "999999999999999",
"retailerId": null,
"description": "Descrição do mouse",
"price": "100000",
"salePrice": "90000",
"currency": "BRL",
"name": "Mouse",
"quantity": null,
"images": ["https://..."]
}
]
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Introdução
Source: https://developer.z-api.io/business/introduction
APIs para o WhatsApp Business na Z-API
## Sobre o WhatsApp Business
Agora temos novas APIs para o **WhatsApp Business**:
* Criar ou editar um produto
* Pegar meu catálogo de produtos
* Pegar catálogo de produtos de outro número business
* Pegar dados de um produto por ID
* Excluir um produto por ID
* Gerenciar etiquetas e coleções
* Configurar dados da empresa
Todas as novas APIs **só funcionam** em WhatsApp Business, e também são **disponíveis apenas** para WhatsApp Business que utilizam o **"Multi Device"**.
# Listar produtos de uma coleção
Source: https://developer.z-api.io/business/list-collection-products
GET /instances/{instanceId}/token/{token}/catalogs/collection-products/{phone}
Lista os produtos de uma coleção específica do catálogo do WhatsApp Business
## Conceituação
Este método é responsável por listar todos os produtos pertencentes a uma coleção específica do catálogo do WhatsApp Business.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Path
Telefone do dono do catálogo
### Query Parameters
ID da coleção
Cursor para paginação dos resultados
***
## Response
### 200
Lista de produtos da coleção
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
[
{
"id": "6643149779134830",
"name": "Nome do produto",
"description": "Descrição do produto",
"price": 9900,
"currency": "BRL",
"images": [
{
"url": "https://example.com/image.jpg"
}
]
}
]
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Listar coleções
Source: https://developer.z-api.io/business/list-collections
GET /instances/{instanceId}/token/{token}/catalogs/collection
Lista todas as coleções do catálogo do WhatsApp Business
## Conceituação
Este método é responsável por listar todas as coleções cadastradas no catálogo do WhatsApp Business.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Query Parameters
Cursor para paginação dos resultados
***
## Response
### 200
Cursor para a próxima página de resultados
Lista de coleções
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"nextCursor": "AQHRi...",
"collections": [
{
"id": "1072603710847740",
"name": "Nome da coleção",
"status": "APPROVED"
}
]
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Dados da conta business
Source: https://developer.z-api.io/business/profile
GET /instances/{instanceId}/token/{token}/business/profile
Retorna os dados do perfil da conta WhatsApp Business
## Conceituação
Este método é responsável por retornar os dados do perfil da conta WhatsApp Business, incluindo descrição, endereço, email, websites, categorias e horário de funcionamento.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Query Parameters
Telefone da conta business
***
## Response
### 200
Descrição da empresa
Endereço da empresa
Email da empresa
Websites da empresa
Categorias da empresa
Horário de funcionamento
Indica se a conta possui foto de capa
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"description": "...",
"address": "...",
"email": "...",
"websites": ["..."],
"categories": [
{
"displayName": "...",
"label": "...",
"id": "..."
}
],
"businessHours": {
"timezone": "America/Sao_Paulo",
"days": [
{
"dayOfWeek": "MONDAY",
"openTime": "08:00",
"closeTime": "18:00"
}
],
"mode": "specificHours"
},
"hasCoverPhoto": false
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Remover produtos da coleção
Source: https://developer.z-api.io/business/remove-product-from-collection
POST /instances/{instanceId}/token/{token}/catalogs/collection/remove-product
Remove produtos de uma coleção existente no catálogo do WhatsApp Business
## Conceituação
Este método é responsável por remover produtos de uma coleção existente no catálogo do WhatsApp Business.
Ao adicionar ou remover produtos de uma coleção, o ID da mesma é alterado pelo WhatsApp. Utilize o ID retornado para operações subsequentes.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Obrigatórios
ID da coleção
IDs dos produtos a serem removidos
***
## Request Body
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"collectionId": "658387616418640",
"productIds": ["6643149779134830"]
}
```
***
## Response
### 200
`true` caso tenha dado certo e `false` em caso de falha
Novo ID da coleção após a alteração
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"success": true,
"collectionId": "1798362193933497"
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Configuração do catálogo
Source: https://developer.z-api.io/business/save-catalog-config
POST /instances/{instanceId}/token/{token}/catalogs/config
Edita as configurações do catálogo
## Conceituação
Utilizando esse método você será capaz de editar as configurações do seu catálogo.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Obrigatórios
Ativar ou desativar o carrinho
***
## Request Body
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"cartEnabled": true
}
```
***
## Response
### 200
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"success": true
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Buscar etiquetas
Source: https://developer.z-api.io/business/tags
GET /instances/{instanceId}/token/{token}/tags
Retorna todas as etiquetas cadastradas na conta business
## Conceituação
Nesse método você será capaz de buscar todas as etiquetas cadastradas na sua conta do WhatsApp Business.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
***
## Response
### 200
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
[
{ "id": "1", "name": "Novo cliente", "color": 1 },
{ "id": "2", "name": "Novo pedido", "color": 2 },
{ "id": "3", "name": "Pagamento pendente", "color": 0 },
{ "id": "4", "name": "Pago", "color": 3 },
{ "id": "5", "name": "Pedido finalizado", "color": 5 }
]
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Atribuir etiquetas a um chat
Source: https://developer.z-api.io/business/tags-add
PUT /instances/{instanceId}/token/{token}/chats/{phone}/tags/{tag}/add
Atribui uma etiqueta a um chat
## Conceituação
Através deste método, é possível atribuir uma etiqueta a um chat no WhatsApp Business.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Path
Telefone do chat
ID da etiqueta
***
## Response
### 200
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"value": true
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Cores de etiquetas
Source: https://developer.z-api.io/business/tags-colors
GET /instances/{instanceId}/token/{token}/business/tags/colors
Retorna as cores disponíveis para etiquetas
## Conceituação
Nesse método você será capaz de buscar as opções de cores disponíveis para etiquetas da sua conta do WhatsApp Business.
As cores podem aparecer de forma diferente entre Android e iPhone.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
***
## Response
### 200
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"0": "#FF9485",
"1": "#64C4FF",
"2": "#FFD429"
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Remover etiquetas de um chat
Source: https://developer.z-api.io/business/tags-remove
PUT /instances/{instanceId}/token/{token}/chats/{phone}/tags/{tag}/remove
Remove uma etiqueta de um chat
## Conceituação
Através deste método, é possível remover uma etiqueta de um chat no WhatsApp Business.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Path
Telefone do chat
ID da etiqueta
***
## Response
### 200
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"value": true
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Find My Pack
Source: https://developer.z-api.io/integrators/introduction
Integração com Find My Pack para controle logístico no e-commerce
## Introdução
O controle logístico é essencial para seu e-commerce ter sucesso. Conheça as funcionalidades oferecidas pela [Find My Pack](https://www.findmypack.com.br/) que elevarão o seu atendimento pós-vendas ao nível de excelência.
***
## Tutorial para integrar
Assista ao vídeo tutorial abaixo para realizar a integração com o Find My Pack:
# Configurar proxy
Source: https://developer.z-api.io/partner/configure-proxy
PUT /instances/{instanceId}/token/{token}/integrator/configure-proxy
Configura a URL do proxy e habilita ou desabilita o uso de proxy na instância
## Conceituação
Método utilizado para configurar tanto a URL do proxy quanto a opção de habilitação do uso do proxy na instância.
Para utilizar os endpoints de Partner, informe o Token de Parceiro no campo **Authorization**, no formato: `Bearer `
Os valores atuais configurados de `proxyUrl` e `useProxy` da instância podem ser consultados no endpoint [Dados da instância](/instance/me)
***
## Parâmetros
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
## Atributos
URL do proxy a ser utilizado pela instância.
Define se o uso do proxy configurado deve ser habilitado (`true`) ou desabilitado (`false`)
Na ausência do campo `proxyUrl` ou quando ele for informado como uma string vazia, a configuração atual de `proxyUrl` da instância será substituída por um valor vazio.
Na ausência do campo `enable` ou em caso de valor `null`, a configuração existente de `enable` na instância será substituída por `false`
Se não houver valor configurado para `proxyUrl`, o campo `enable` não terá efeito. A ausência de uma URL de proxy configurada resultará na conexão da instância sem a utilização de proxy, independentemente do valor de `enable`
***
## Request Body
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"proxyUrl": "socks5://user:senha123@localhost:1080",
"enable": true
}
```
***
Caso haja erro ao se conectar utilizando o proxy configurado, serão feitas **3 tentativas de retry**.
Caso a conexão falhe na terceira tentativa, a instância é conectada **sem utilizar nenhum proxy**, e um webhook é disparado para a URL configurada no webhook de [Webhook de falha no proxy](/partner/update-proxy-webhook).
## Response
### 200
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"value": true
}
```
### 400
```
"Proxy is not reachable"
```
Esse erro ocorre quando o teste de conexão com o proxy configurado falha. Verifique se a URL do proxy informada está correta e acessível.
### 401
Esse erro ocorre quando o Token de Parceiro informado no campo **Authorization** está vazio ou inválido.
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o PUT conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Criando uma instância
Source: https://developer.z-api.io/partner/create-instance
POST /instances/integrator/on-demand
Cria uma instância vinculada à sua conta de parceiro integrador
## Conceituação
Método utilizado para criar uma instância vinculada a sua conta.
Você não precisa necessariamente assinar a instância neste momento pois você tem 2 dias para utilizar como trial. Após 2 dias sem assinatura, a instância tem seu status alterado para PENDENTE, permanecendo na listagem até que seja assinada.
Para utilizar os endpoints de Partner, informe o Token de Parceiro no campo **Authorization**, no formato: `Bearer `
Não é necessário enviar o **Client-Token** nessas requisições.
***
## Atributos
### Obrigatórios
Nome da instância
### Opcionais
Nome da sessão nos dispositivos conectados
URL webhook de mensagens enviadas
URL webhook de mensagens recebidas
URL webhook de mensagens recebidas e enviadas por mim
URL webhook status do chat
URL webhook de desconexão
URL webhook de conexão
URL webhook status da mensagem
Rejeitar chamadas automaticamente
Mensagem ao rejeitar chamada
Leitura automática de mensagens
Leitura automática de status
Instância mobile (true) ou web (false)
Versão WhatsApp Business
Habilitar/desabilitar fila quando desconectado
### Opcionais - apenas para criação de instâncias mobile
Nome do perfil do WhatsApp
URL referente a foto de perfil do WhatsApp
Define se a instância com o recurso de proteção anti-golpe em grupos de avisos ativa.
***
## Request Body
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"name": "Minha instância"
}
```
***
## Response
### 200
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"id": "instanceId",
"token": "instanceToken",
"due": 1648565999675
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Deletando uma instância
Source: https://developer.z-api.io/partner/delete-instance
DELETE /instances/{instanceId}/token/{token}/integrator/on-demand/delete
Deleta uma instância vinculada à sua conta de parceiro integrador
## Conceituação
Método utilizado para deletar uma instância vinculada à sua conta. Para deletar várias de uma vez, use [Deletando instâncias em lote](/partner/delete-instances).
Para utilizar os endpoints de Partner, informe o Token de Parceiro no campo **Authorization**, no formato: `Bearer `
Não é necessário enviar o **Client-Token** nessas requisições.
A exclusão é definitiva e não pode ser desfeita.
***
## Regras de elegibilidade
Uma instância só é deletada quando atende a **todas** as condições abaixo:
* Está **desconectada** do WhatsApp e do celular.
* Está com status de pagamento **pendente**, **trial** ou **cancelado**. Instâncias pagas, com boleto pendente, em processo de cancelamento, em retentativa de pagamento ou sem status de pagamento definido não são elegíveis.
* Se estiver **pendente**, não tem assinatura pendente. Cancele a assinatura antes de deletar a instância.
Instâncias canceladas podem ser deletadas assim que entram nesse status, sem carência após o cancelamento.
***
## Atributos
### Header
Token de parceiro no formato `Bearer `
### Path
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
***
## Response
### 204
A instância foi deletada. A resposta não tem corpo.
### 403
A instância não atende às regras de elegibilidade. O campo `type` identifica a regra que bloqueou a exclusão e o campo `message` descreve o motivo.
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"type": "INSTANCE_HAS_ACTIVE_SUBSCRIPTION",
"message": "Cannot delete instance because it has a pending subscription. Cancel the subscription first"
}
```
Motivos possíveis:
| type | message | Quando acontece |
| - | - | - |
| `INSTANCE_STILL_CONNECTED` | `Cannot delete instance because it is still connected to WhatsApp or phone` | A instância ainda está conectada ao WhatsApp ou ao celular. Desconecte antes de deletar. |
| `INSTANCE_PAYMENT_STATUS_MISSING` | `Cannot delete instance because payment status is unknown` | A instância não tem status de pagamento definido. |
| `INSTANCE_NOT_ELIGIBLE` | `Cannot delete instance because it is still active` | O status de pagamento não é pendente, trial nem cancelado (por exemplo: paga, boleto pendente, em processo de cancelamento ou em retentativa de pagamento). |
| `INSTANCE_HAS_ACTIVE_SUBSCRIPTION` | `Cannot delete instance because it has a pending subscription. Cancel the subscription first` | A instância está pendente e tem assinatura pendente. Cancele a assinatura antes de deletar. |
### 401
O header **Authorization** não foi enviado ou o Token de Parceiro é inválido.
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"message": "Authorization token is empty"
}
```
### 404
Não existe instância para o par `instanceId` e `token` informado.
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"message": "Instance not found"
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o DELETE conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Deletando instâncias em lote
Source: https://developer.z-api.io/partner/delete-instances
POST /instances/integrator/on-demand/batch-delete
Deleta várias instâncias vinculadas à sua conta de parceiro integrador em uma única requisição
## Conceituação
Método utilizado para deletar várias instâncias vinculadas à sua conta em uma única requisição. Para deletar apenas uma instância, use [Deletando uma instância](/partner/delete-instance).
Para utilizar os endpoints de Partner, informe o Token de Parceiro no campo **Authorization**, no formato: `Bearer `
Não é necessário enviar o **Client-Token** nessas requisições.
Envie no máximo **100 instâncias por requisição**. Para volumes maiores, divida a operação em várias chamadas.
Cada instância da lista é avaliada individualmente. Uma instância recusada não impede que as demais sejam deletadas: a resposta informa o resultado de cada uma.
***
## Regras de elegibilidade
Uma instância só é deletada quando atende a **todas** as condições abaixo:
* Está **desconectada** do WhatsApp e do celular.
* Está com status de pagamento **pendente**, **trial** ou **cancelado**. Instâncias pagas, com boleto pendente, em processo de cancelamento, em retentativa de pagamento ou sem status de pagamento definido não são elegíveis.
* Se estiver **pendente**, não tem assinatura pendente. Cancele a assinatura antes de deletar a instância.
Instâncias canceladas podem ser deletadas assim que entram nesse status, sem carência após o cancelamento.
***
## Atributos
### Header
Token de parceiro no formato `Bearer `
### Obrigatórios
Lista das instâncias a serem deletadas. Máximo de 100 por requisição.
Id da instância a ser deletada
Token da instância a ser deletada
***
## Request Body
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"instances": [
{
"id": "instanceId",
"token": "instanceToken"
}
]
}
```
***
## Response
### 200
O campo `results` traz uma entrada por instância enviada, na mesma ordem da requisição.
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"total": 3,
"deleted": 1,
"rejected": 2,
"results": [
{
"id": "3C7A1B2C3D4E5F6A",
"status": "deleted",
"type": null,
"reason": null
},
{
"id": "3C7B2C3D4E5F6A7B",
"status": "rejected",
"type": "INSTANCE_HAS_ACTIVE_SUBSCRIPTION",
"reason": "Cannot delete instance because it has a pending subscription. Cancel the subscription first"
},
{
"id": "3C7C3D4E5F6A7B8C",
"status": "rejected",
"type": "INSTANCE_NOT_FOUND",
"reason": "Instance not found"
}
]
}
```
### Motivos de recusa
Cada item recusado traz um `type` que identifica a regra que bloqueou a exclusão.
| type | Quando acontece |
| - | - |
| `INSTANCE_STILL_CONNECTED` | A instância ainda está conectada ao WhatsApp ou ao celular. |
| `INSTANCE_PAYMENT_STATUS_MISSING` | A instância não tem status de pagamento definido. |
| `INSTANCE_NOT_ELIGIBLE` | O status de pagamento não é pendente, trial nem cancelado (por exemplo: paga, boleto pendente, em processo de cancelamento ou em retentativa de pagamento). |
| `INSTANCE_HAS_ACTIVE_SUBSCRIPTION` | A instância está pendente e tem assinatura pendente. Cancele a assinatura antes de deletar. |
| `INSTANCE_NOT_FOUND` | Não existe instância para o par `id` e `token` informado. |
| `INTEGRATION_ERROR` | Falha ao comunicar com o provedor de pagamento. |
| `INTERNAL_ERROR` | Falha inesperada ao deletar a instância. |
### 400
A lista de instâncias veio vazia ou acima do limite de 100 por requisição.
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"message": "Maximum of 100 instances per batch"
}
```
### 401
O header **Authorization** não foi enviado ou o Token de Parceiro é inválido.
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"message": "Authorization token is empty"
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Conexão via extensão para parceiros
Source: https://developer.z-api.io/partner/extension-token
Como implementar o fluxo de geração de token de extensão na sua plataforma
## Visão geral
Em alguns dispositivos, o WhatsApp passou a exigir uma verificação de segurança com chave de acesso para autorizar novas conexões ao WhatsApp Web. Quando isso acontece, o cliente final **não consegue conectar** a instância Z-API pelo fluxo tradicional de QR Code.
Esse comportamento **não ocorre em todos os dispositivos**. Por isso, não substitua o fluxo de conexão padrão — implemente a conexão via extensão como uma **opção alternativa**, exibida apenas quando o cliente relatar dificuldades para conectar.
**Limitações conhecidas (fora do nosso controle):** o pareamento via passkey depende de recursos da própria plataforma (Windows/Bluetooth), e não da Z-API.
* **Windows 10 (ou inferior):** não há suporte a pareamento de passkey via Bluetooth nem sincronização de passkeys em nuvem. Nesses casos, o sistema solicita uma "chave de segurança USB" física e o fluxo não avança. Como o Windows 10 saiu de suporte em out/2025, não há previsão de correção pela Microsoft. Esse recurso é exclusivo do **Windows 11**.
* **Dispositivos sem Bluetooth:** independentemente do sistema operacional, o pareamento com o celular não é possível sem Bluetooth.
A recomendação é seguir o mesmo padrão do painel Z-API: exibir um aviso ou banner de "problemas ao conectar" que, ao ser clicado, inicia o fluxo de geração do código de extensão. Veja o exemplo abaixo:
Dessa forma, clientes que conseguem conectar normalmente não são impactados, e os que precisam da extensão têm um caminho claro para resolver.
***
## Responsabilidade do parceiro
O fluxo de responsabilidades é o seguinte:
1. **Parceiro** → chama o endpoint [`extension-token`](/instance/extension-token) da Z-API para gerar o código
2. **Parceiro** → exibe o código gerado na própria interface para o cliente
3. **Cliente final** → usa o código na extensão [Z-API Conector](https://chromewebstore.google.com/detail/iopmkohngoecmepoheapifkafbeomphn) para conectar a instância
A geração do token é de responsabilidade do parceiro. O cliente final nunca deve ter acesso direto às credenciais da instância (instanceId e token).
***
## Como gerar o token
Faça uma requisição autenticada ao endpoint de geração de token da instância do seu cliente:
```bash theme={"theme":{"light":"github-light","dark":"poimandres"}}
curl --location 'https://api.z-api.io/instances/{instanceId}/token/{instanceToken}/extension-token' \
--header 'Client-Token: SEU_CLIENT_TOKEN'
```
**Resposta:**
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"token": "FA48-HS63",
"expiresAt": 1782851138085
}
```
Código de conexão a ser exibido para o cliente final (formato `XXXX-XXXX`)
Timestamp Unix (em milissegundos) com a data de expiração do código
O token possui validade limitada. Exiba o tempo restante para o cliente e ofereça a opção de gerar um novo código caso ele expire antes de ser utilizado.
Documentação completa do endpoint: [Gerar token para extensão](/instance/extension-token)
***
## O que exibir para o cliente
Abaixo está o exemplo de como o próprio painel Z-API exibe o código para o cliente — use como referência para implementar na sua plataforma:
Sua interface deve apresentar ao cliente:
* O **código de conexão** gerado (ex: `FA48-HS63`) com opção de copiar
* Um **contador regressivo** com o tempo restante de validade
* O **link para instalar a extensão** [Z-API Conector](https://chromewebstore.google.com/detail/iopmkohngoecmepoheapifkafbeomphn)
* Os **passos** que o cliente deve seguir após receber o código:
1. Instalar a extensão Z-API Conector no Chrome
2. Acessar [https://web.whatsapp.com/](https://web.whatsapp.com/) logado com o número a conectar
3. Clicar no ícone da extensão e digitar o código
4. Confirmar na tela da extensão para finalizar a conexão
***
## O que o cliente faz com o código
Após receber o código gerado pela sua plataforma, o cliente deve seguir os passos abaixo:
### 1. Instalar a extensão Z-API Conector
Caso ainda não tenha instalado, o cliente acessa a Chrome Web Store e instala a extensão [Z-API Conector](https://chromewebstore.google.com/detail/iopmkohngoecmepoheapifkafbeomphn).
### 2. Abrir o WhatsApp Web logado com o número a conectar
O cliente acessa **[web.whatsapp.com](https://web.whatsapp.com/)** no Chrome, já conectado com o número que deve ser vinculado à instância Z-API.
O número aberto no WhatsApp Web deve ser o mesmo que será conectado na instância. A extensão detecta automaticamente o número logado.
### 3. Inserir o código na extensão
Com o WhatsApp Web aberto, o cliente clica no ícone da extensão **Z-API Conector** na barra do Chrome. A extensão detecta o número logado e exibe os campos para digitar o código de conexão (formato `XXXX-XXXX`):
### 4. Confirmar e conectar na Z-API
Após digitar o código, a extensão exibe uma tela de confirmação com o nome da instância, o número detectado e um contador regressivo. O cliente clica em **"Conectar na Z-API"**:
A sessão ativa do WhatsApp Web é encerrada e o número passa a estar conectado na instância Z-API.
***
## Considerações finais
* O backend do parceiro deve ser o único a chamar o endpoint [`extension-token`](/instance/extension-token); nunca exponha essa chamada no frontend
* Oriente seu cliente a ter o WhatsApp Web aberto e logado **antes** de inserir o código na extensão
# Introdução
Source: https://developer.z-api.io/partner/introduction
Parceiro Integrador Z-API - Como funciona o programa de parceiros
## Parceiro Integrador, seja bem vindo!
Se você está neste tópico, significa que já quebrou algumas castanhas com a gente, não é mesmo? Ficamos extremamente satisfeitos por você considerar ser um parceiro integrador nosso.
Agora que você alcançou 10 instâncias, já nos conhecemos bem e nossa parceria está ainda mais fortalecida.
***
## Modelo de Integrador
Ao participar do programa de parceria, você receberá um token exclusivo de integração, juntamente com a documentação necessária para criar, assinar ou cancelar instâncias via API, eliminando a necessidade de acesso à nossa interface admin.
***
## Tokens
No Z-API disponibilizamos dois tokens para configurar em sua conta: Client-Token (Token de segurança da conta) e Partner-Token (Token de Parceiro). Abaixo é explicado o funcionamento de cada um deles.
### Client-Token (Token de Segurança da Conta)
Utilizado para todas as chamadas realizada via API, proporcionando uma camada adicional de proteção para suas instâncias, garantindo que apenas solicitações autorizadas tenham acesso aos seus recursos.
### Token Integrador (Token de Parceiro)
Para obter o Token Integrador, é necessário se tornar um Parceiro Z-API. Com esse token, você poderá criar, assinar, listar e cancelar instâncias via API.
Quer saber mais sobre o programa e como se tornar um parceiro? Conheça o Programa Partner.
🔗 [https://z-api.io/seja-partner-zapi](https://z-api.io/seja-partner-zapi)
***
## Importante
**ATENÇÃO**
* Toda responsabilidade do uso do token é do cliente. Sua empresa é responsável financeiramente por todas as instâncias criadas. Evite utilizar tokens em ambientes de teste.
* Novas instâncias chegam com um período default de **2 dias de trial**. Após a expiração, as instâncias param e são automaticamente deletadas, a menos que o método de assinatura seja invocado. Não é necessário cancelar instâncias durante o período de trial.
* O modelo de parceria integradora atualmente funciona no modelo **pós-pago**, com opções de pré-pago em breve.
***
## Faturamento
Nosso ciclo de faturamento funciona da seguinte forma:
* Toda instância assinada entre os dias **01 ao dia 31** será agrupada e disponibilizada em um único pagamento com vencimento no dia **05 do próximo mês**.
* Instâncias canceladas permanecem ativas até o **último dia do mês vigente**, sendo desativadas automaticamente ao encerramento do ciclo. A cobrança segue normalmente até esse período.
* Todas as instâncias expiram no dia **10** do mês de cobrança. O não pagamento resulta na exclusão pelo DevOps no dia **15**.
***
## Migrar instâncias
Durante a adesão do plano a empresa integradora pode optar pela migração de todas as instâncias ativas no modelo pré-pago para o novo modelo pós-pago, porém este desejo precisa ser manifestado no ato da adesão.
***
## Como cobrar de seu cliente
Recomendamos a nossos clientes a prática do modelo pré-pago em suas soluções pois não trabalhamos com pro rata.
# Listando instâncias
Source: https://developer.z-api.io/partner/list-instances
GET /instances
Lista todas as instâncias criadas pelo parceiro integrador
## Conceituação
Método utilizado para listar todas as instâncias criadas.
Para utilizar os endpoints de Partner, informe o Token de Parceiro no campo **Authorization**, no formato: `Bearer `
Não é necessário enviar o **Client-Token** nessas requisições.
***
## Atributos
### Query Parameters
Página que quer buscar
Tamanho do retorno por página
Busca pelo nome e ID da instância
Tipo da instância: `web` ou `mobile`
***
## Exemplos de requisições
### Listar por nome ou ID da instância
```bash theme={"theme":{"light":"github-light","dark":"poimandres"}}
https://api.z-api.io/instances?page=1&pageSize=15&query=NOME_OU_INSTANCEID
```
### Listar por tipo (web ou mobile)
```bash theme={"theme":{"light":"github-light","dark":"poimandres"}}
https://api.z-api.io/instances?page=1&pageSize=15&middleware=web
```
### Listar por tipo (web ou mobile) + nome ou ID da instância
```bash theme={"theme":{"light":"github-light","dark":"poimandres"}}
https://api.z-api.io/instances?page=1&pageSize=15&middleware=web&query=NOME_OU_INSTANCEID
```
## Response
### 200
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"total": 1,
"totalPage": 1,
"pageSize": 1,
"page": 1,
"content": [
{
"token": "",
"tenant": "",
"created": "",
"due": 1648565999675,
"paymentStatus": "",
"deliveryCallbackUrl": "",
"phoneConnected": false,
"whatsappConnected": false,
"middleware": "web",
"name": "",
"id": ""
}
]
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Gerar token do SDK
Source: https://developer.z-api.io/partner/sdk-connector-token
GET /instances/{instanceId}/token/{token}/sdk-connector-token
Gera um token de sessão para abrir o SDK de conexão no frontend
## Conceituação
Este método gera um **token de sessão** para o [SDK de conexão](/partner/sdk-connector). O seu backend chama este endpoint com o seu Client-Token e devolve o `token` retornado para o frontend, que o usa em `ZAPIConnector.open({ token })`.
A chamada deve ser feita pelo **seu backend**. Nunca exponha o seu Client-Token nem as credenciais da instância (instanceId e token) no frontend. O token gerado tem validade limitada — gere-o sob demanda, no momento em que o cliente for conectar.
Guia de implementação completo: [SDK de conexão](/partner/sdk-connector).
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
***
## Response
### 200
Token de sessão a ser usado em `ZAPIConnector.open({ token })` no frontend
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Assinando uma instância
Source: https://developer.z-api.io/partner/sign-instance
POST /instances/{instanceId}/token/{token}/integrator/on-demand/subscription
Assina uma instância de parceiro integrador
## Conceituação
Método utilizado para assinar uma instância.
Para utilizar os endpoints de Partner, informe o Token de Parceiro no campo **Authorization**, no formato: `Bearer `
Não é necessário enviar o **Client-Token** nessas requisições.
***
## Atributos
### Opcionais
Define se a instância será criada com suporte a chamadas
O atributo **withCalls** é opcional. Caso não seja enviado, a requisição continuará funcionando normalmente com o comportamento padrão. Este recurso está disponível apenas para contas que possuem a funcionalidade de chamadas habilitada.
```bash cURL theme={"theme":{"light":"github-light","dark":"poimandres"}}
curl --request POST \
--url https://api.z-api.io/instances/{instanceId}/token/{token}/integrator/on-demand/subscription \
--header 'Authorization: Bearer ' \
--header 'Content-Type: application/json' \
--data '
{
"withCalls": false
}
'
```
```json JSON theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"withCalls": false
}
```
***
## Request Body
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"withCalls": false
}
```
***
## Response
### 201
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Cancelando uma instância
Source: https://developer.z-api.io/partner/unsubscribe-instance
POST /instances/{instanceId}/token/{token}/integrator/on-demand/cancel
Cancela a assinatura de uma instância de parceiro integrador
## Conceituação
Método utilizado para cancelar a assinatura de uma instância.
Ao cancelar uma instância, ela continuará ativa até o final do ciclo vigente, que corresponde ao último dia do mês. Após o encerramento do ciclo, a instância será desativada automaticamente. A cobrança será realizada normalmente até o término desse período.
Para utilizar os endpoints de Partner, informe o Token de Parceiro no campo **Authorization**, no formato: `Bearer `
Não é necessário enviar o **Client-Token** nessas requisições.
***
## Response
### 201
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Atualizando a assinatura
Source: https://developer.z-api.io/partner/update-instance
PUT /instances/{instanceId}/token/{token}/integrator/subscription/update
Atualiza a assinatura de uma instância para habilitar suporte a chamadas
## Conceituação
Método utilizado para atualizar a assinatura de uma instância para habilitar suporte a chamadas.
O atributo **withCalls** é obrigatório e aceita apenas o valor **true**. Não é possível realizar downgrade da assinatura (remover chamadas). Para isso, cancele a assinatura atual e contrate uma nova.
Este recurso está disponível apenas para contas que possuem a funcionalidade de chamadas habilitada.
Para utilizar os endpoints de Partner, informe o Token de Parceiro no campo **Authorization**, no formato: `Bearer `
Não é necessário enviar o **Client-Token** nessas requisições.
***
## Atributos
### Obrigatórios
Deve ser enviado como `true` para habilitar chamadas
***
## Request Body
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"withCalls": true
}
```
***
## Response
### 201
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Webhook de falha no proxy
Source: https://developer.z-api.io/partner/update-proxy-webhook
PUT /instances/{instanceId}/token/{token}/update-proxy-webhook
Atualiza a URL do webhook para callbacks de falha na conexão com o proxy
## Conceituação
Método utilizado para atualizar a URL do webhook onde serão recebidos os callbacks de falha na conexão com o proxy.
***
## Parâmetros
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
## Atributos
URL do webhook que receberá os callbacks de falha.
***
## Request Body
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"value": "http://localhost:3001/api/webhook"
}
```
***
## Comportamento do callback
Caso haja erro ao se conectar utilizando o proxy configurado, serão feitas **3 tentativas de retry**.
Caso a conexão falhe na terceira tentativa, a instância é conectada **sem utilizar nenhum proxy**, e um webhook é disparado para a URL configurada neste endpoint, com o seguinte payload:
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"type": "ProxyCallback",
"instanceId": "3F2XXXXXXXXXXXXXXXXXXXA2FF",
"error": "The instance was connected without proxy, the configured proxy (socks5://user:senha123@localhost:1080) failed 3 times to connect."
}
```
***
## Response
### 200
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"value": true
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o PUT conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Apagar fila
Source: https://developer.z-api.io/queue/delete-queue
DELETE /instances/{instanceId}/token/{token}/queue
Deleta todas as mensagens da fila
## Conceituação
Este método é responsável por deletar todas mensagens que estão em sua fila aguardando para ser processada.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
***
## Response
### 200
Fila apagada com sucesso.
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o DELETE conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Apagar mensagem da fila
Source: https://developer.z-api.io/queue/delete-queue-id
DELETE /instances/{instanceId}/token/{token}/queue/{zaapId}
Deleta uma mensagem específica da fila
## Conceituação
Este método é responsável por deletar uma mensagem dentro da fila aguardando para ser processada.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Path
ID da mensagem na fila que deseja deletar
***
## Response
### 200
Mensagem removida da fila com sucesso.
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o DELETE conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Fila (Depreciada)
Source: https://developer.z-api.io/queue/get-queue
GET /instances/{instanceId}/token/{token}/queue
Retorna todas as mensagens que estão na fila aguardando processamento
Este endpoint esta **obsoleto**, pois o modelo de paginacao foi atualizado para um formato baseado em **cursor (pagingState)**. Utilize o novo endpoint [POST /queue](/queue/post-queue). **Descontinuacao programada:** Este endpoint sera removido em **30/04**.
## Conceituação
Este método é responsável por retornar todas mensagens que estão em sua fila aguardando para ser processada.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Query Parameters
Utilizado para paginação, informe a página de mensagens que quer buscar
Especifica o tamanho do retorno de mensagens por página
Para retornar apenas a contagem total de mensagens na fila, utilize: `GET /queue/count`
***
## Response
### 200
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"messages": [
{
"_id": "39BB1684570F00E91090F6BBC7EE7646",
"DelayMessage": -1,
"Message": "Mensagem da fila 1",
"IsTrial": false,
"InstanceId": "3A5D07856DC26A1C9E2E08E691E63271",
"Phone": "5511999999999",
"ZaapId": "39BB1684570F00E91090F6BBC7EE7646",
"DelayTyping": 0,
"MessageId": "7AD29EAA5EF34C301F0B",
"Created": 1624977905648
}
]
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Introdução
Source: https://developer.z-api.io/queue/introduction
Entenda como funciona o sistema de fila de mensagens na Z-API
## Fila
O Z-API disponibiliza a seus usuários um sistema de fila que funciona unicamente para as mensagens enviadas através da nossa API. Esta fila exerce um importante papel em nossa arquitetura que é o de organizar e ordenar as mensagens até que as mesmas sejam entregues ao WhatsApp. Este recurso também é muito útil para aquelas situações onde o celular conectado ao Z-API passa por algumas instabilidades ou fique fora da internet. Caso isso ocorra, ou seja, se o celular fica por um período fora do ar, assim que você voltar a conectar as mensagens serão enviadas ao destinatário normalmente.
### Tempo de envio
Nossa fila trabalha com tempo de envio alternado entre uma mensagem e outra a fim de simular o comportamento humano. Este intervalo fica em um range default randômico entre 1 a 3 segundos por mensagem. Caso queira aumentar o delay das mensagens, você pode passar o atributo `delayMessage` no body da requisição.
***
## Recomendação
Recomendamos que sempre antes de se conectar você verifique se existem mensagens pendentes de envio na fila, caso tenha avise seu usuário e solicite a ele a decisão de enviar ou não enviar mais estas mensagens que estão na fila. Imagine que talvez as mensagens na fila possam já não fazer mais sentido para serem enviadas, então é importante notificar o usuário e dar esta decisão a ele. Sempre que você se conectar ao Z-API ele vai automaticamente executar a fila e disparar as mensagens caso tenha. Então muito cuidado!
### Limite da fila
O Z-API permite até **1000 mensagens** para celulares desconectados em sua fila antes de começar a rejeitar novas mensagens.
# Fila
Source: https://developer.z-api.io/queue/post-queue
POST /instances/{instanceId}/token/{token}/queue
Retorna mensagens da fila aguardando processamento com suporte a paginacao por cursor
## Conceituacao
Este metodo retorna as mensagens que estao na fila aguardando processamento, com suporte a paginacao por cursor. Diferente do GET, este endpoint permite controlar a paginacao de forma mais eficiente utilizando `pagingState`.
***
## Atributos
### Obrigatorios
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Body (Opcionais)
Numero de mensagens retornadas por requisicao. Valor padrao: 20, maximo: 30.
Cursor de paginacao. Quando nao informado, retorna a primeira pagina. Use o valor retornado na resposta para buscar as proximas paginas.
***
## Request Body
Primeira pagina:
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{}
```
Proximas paginas:
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"pageSize": 20,
"pagingState": "eyJidWNrZXQiOjI5MzQsInBhZ2VTdGF0ZSI6IjAw..."
}
```
***
## Response
### 200
Lista de mensagens na fila
Cursor para a proxima pagina
Indica se existem mais paginas
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"messages": [
{
"_id": "019D44XXXXXXXXXXXXXXXXX68DA6",
"DelayMessage": -1,
"Message": "Mensagem teste",
"InstanceId": "3E98XXXXXXXXXXXXXXXXXXXF5DDF",
"Phone": "5511999999999",
"ZaapId": "019D44XXXXXXXXXXXXXXXXX68DA6",
"DelayTyping": 0,
"MessageId": "ECFXXXXXXXXXXXXXX39",
"Created": 1774968031776,
"CreatedAt": "2026-03-31T14:40:31.776+00:00",
"Beta": false,
"IsTrial": false
}
],
"pagingState": "eyJi...",
"hasMore": true
}
```
## Paginacao
* Caso nao envie `pagingState`, a primeira pagina sera retornada automaticamente
* Caso nao informe `pageSize`, o valor padrao de 20 mensagens sera utilizado
* O numero maximo de mensagens que podem ser retornadas por pagina e 30 mensagens
* Utilize o `pagingState` retornado para buscar as proximas paginas
* Quando `hasMore` for `false`, nao existem mais mensagens disponiveis
### 405
Neste caso certifique que esteja enviando corretamente a especificacao do metodo, ou seja verifique se voce enviou o POST ou GET conforme especificado no inicio deste topico.
### 415
Caso voce receba um erro 415, certifique de adicionar na headers da requisicao o "Content-Type" do objeto que voce esta enviando, em sua grande maioria "application/json".
# Atualizar configuração da fila
Source: https://developer.z-api.io/queue/update-queue-settings
PUT /instances/{instanceId}/token/{token}/update-queue-settings
Atualiza as configurações de fila de uma instância, permitindo controlar o comportamento de enfileiramento quando desconectada.
## Conceituação
Este método permite atualizar configurações relacionadas ao comportamento da fila de mensagens da instância.
Atualmente, é possível configurar se a instância deve ou não aceitar novas mensagens na fila enquanto estiver desconectada.
***
## Atributos
### Obrigatórios
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Body (Obrigatórios)
Define se a instância deve bloquear o enfileiramento de mensagens quando estiver desconectada.
***
## Request Body
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"disableEnqueueWhenDisconnected": true
}
```
***
## Comportamento da fila
* Por padrão, a Z-API permite o envio de mensagens para a fila mesmo quando a instância não possui um número conectado
* Quando `disableEnqueueWhenDisconnected` for `true`, novas mensagens não serão adicionadas à fila enquanto a instância estiver desconectada
* Quando `disableEnqueueWhenDisconnected` for `false`, o comportamento padrão é mantido (mensagens continuam sendo enfileiradas mesmo desconectado)
* Essa configuração é útil para evitar o acúmulo de mensagens na fila quando a instância é reutilizada sem um número conectado
***
## Response
### 200
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"success": true
}
```
### 405
Neste caso, certifique-se de que está utilizando o método correto (PUT) conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, verifique se o header "Content-Type" foi definido corretamente como "application/json".
# Introdução
Source: https://developer.z-api.io/status/introduction
Entenda como funciona o recurso de Status na Z-API
## Conceituação
O Status do WhatsApp é um recurso que permite compartilhar textos, fotos e vídeos que ficam disponíveis por 24 horas para seus contatos. Ele fica localizado em uma aba entre Conversas e Chamadas.
Com a Z-API, você pode automatizar a publicação de status, enviando textos, imagens e vídeos programaticamente, além de responder status de outros contatos.
***
## O que você pode fazer com Status?
Publique um status com texto personalizado e cor de fundo.
Publique uma imagem como status com legenda opcional.
Publique um vídeo como status.
Responda status de contatos com texto, GIF ou sticker.
# Responder status com GIF
Source: https://developer.z-api.io/status/reply-status-gif
POST /instances/{instanceId}/token/{token}/reply-status-gif
Envia uma resposta com GIF a um status do WhatsApp.
## Conceituação
Método responsável por enviar uma resposta com GIF a um status.
***
## Atributos
### Header
### Obrigatórios
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
Número de quem enviou o status
Link do GIF, precisa ser MP4
ID da mensagem do status, obtido no webhook de mensagem recebida
***
## Request Body
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"phone": "5544999999999",
"gif": "https://example.com/file.mp4",
"statusMessageId": "1F606398F2ECAA4846269F659B6003A9"
}
```
***
## Response
### 200
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"zaapId": "3999984263738042930CD6ECDE9VDWSA",
"messageId": "D241XXXX732339502B68",
"id": "D241XXXX732339502B68"
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Responder status com sticker
Source: https://developer.z-api.io/status/reply-status-sticker
POST /instances/{instanceId}/token/{token}/reply-status-sticker
Envia uma resposta com sticker a um status do WhatsApp.
## Conceituação
Método responsável por enviar uma resposta com sticker a um status.
***
## Atributos
### Header
### Obrigatórios
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
Número de quem enviou o status
URL do sticker ou Base64
ID da mensagem do status, obtido no webhook de mensagem recebida
***
## Request Body
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"phone": "5544999999999",
"sticker": "https://example.com/sticker.png",
"statusMessageId": "1F606398F2ECAA4846269F659B6003A9"
}
```
***
## Response
### 200
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"zaapId": "3999984263738042930CD6ECDE9VDWSA",
"messageId": "D241XXXX732339502B68",
"id": "D241XXXX732339502B68"
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Responder status com texto
Source: https://developer.z-api.io/status/reply-status-text
POST /instances/{instanceId}/token/{token}/reply-status-text
Envia uma resposta em texto a um status do WhatsApp.
## Conceituação
Método responsável por enviar uma resposta em texto a um status.
***
## Atributos
### Header
### Obrigatórios
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
Número de quem enviou o status
Mensagem da resposta
ID da mensagem do status, obtido no webhook de mensagem recebida
***
## Request Body
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"phone": "5544999999999",
"message": "texto da mensagem",
"statusMessageId": "1F606398F2ECAA4846269F659B6003A9"
}
```
***
## Response
### 200
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"zaapId": "3999984263738042930CD6ECDE9VDWSA",
"messageId": "D241XXXX732339502B68",
"id": "D241XXXX732339502B68"
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Enviar imagem status
Source: https://developer.z-api.io/status/send-image-status
POST /instances/{instanceId}/token/{token}/send-image-status
Envia uma imagem para o status do WhatsApp.
## Conceituação
Método responsável por enviar uma imagem para seu status, lembre-se que os status somem após 24 horas.
***
## Atributos
### Header
### Obrigatórios
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
Link da imagem ou Base64
### Opcionais
Legenda da imagem
***
## Request Body
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"image": "https://example.com/image.jpg",
"caption": "texto da legenda"
}
```
***
## Response
### 200
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"zaapId": "3999984263738042930CD6ECDE9VDWSA",
"messageId": "D241XXXX732339502B68"
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Enviar texto status
Source: https://developer.z-api.io/status/send-text-status
POST /instances/{instanceId}/token/{token}/send-text-status
Envia uma mensagem de texto para o status do WhatsApp.
## Conceituação
Você pode postar textos no seu status e este método é responsável por isso, lembre-se que os status somem após 24 horas.
***
## Atributos
### Header
### Obrigatórios
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
Mensagem a ser enviada para o status
***
## Request Body
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"message": "Sua mensagem para status"
}
```
***
## Response
### 200
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"zaapId": "3999984263738042930CD6ECDE9VDWSA",
"messageId": "D241XXXX732339502B68"
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Enviar vídeo status
Source: https://developer.z-api.io/status/send-video-status
POST /instances/{instanceId}/token/{token}/send-video-status
Envia um vídeo para o status do WhatsApp.
## Conceituação
Método responsável por enviar um vídeo para seu status, lembre-se que os status somem após 24 horas.
Tamanho máximo do vídeo para status: 10MB.
***
## Atributos
### Header
### Obrigatórios
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
Link do vídeo ou Base64
### Opcionais
Legenda do vídeo
***
## Request Body
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"video": "https://example.com/video.mp4",
"caption": "texto da legenda"
}
```
***
## Response
### 200
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"zaapId": "3999984263738042930CD6ECDE9VDWSA",
"messageId": "D241XXXX732339502B68"
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou GET conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Introdução
Source: https://developer.z-api.io/webhooks/introduction
Entenda como funcionam os webhooks na Z-API
## Conceituação
Neste tópico falaremos sobre os **retornos** dos webhooks que utilizamos.
As instâncias do Z-API fazem requisições com o método **POST** dos eventos realizados por ela para a URL configurada previamente. Para cada requisição há um corpo em JSON específico que será descrito em seguida.
Seu endpoint precisa aceitar um **POST**.
***
## O que é e para que serve?
Segundo o Google, Webhook é um recurso usado na internet para que uma aplicação se comunique com outra, fornecendo dados em tempo real sempre que um evento acontecer.
Então se você está se integrando com o Z-API e precisa receber informações pelo WhatsApp, é necessário prover estes endpoints na sua aplicação para conseguirmos te avisar sobre tudo que acontece no seu WhatsApp.
***
## Nossos webhooks
Notifica quando sua mensagem foi entregue ao WhatsApp. Isso não garante que o contato recebeu a mensagem.
Acionado toda vez que alguém interagir com seu número no WhatsApp.
Informa mudanças de status da mensagem (recebida, lida, respondida, excluída).
Acionado quando há indisponibilidade na comunicação entre celular-WhatsApp ou celular-Z-API.
***
## Como configurar meu webhook?
### Via Painel
Acesse o painel admin, navegue até Instâncias, clique no ícone de visualização da instância desejada e selecione "editar" nos três pontinhos.
### Via API
É possível atualizar a rota do webhook através dos endpoints de atualização descritos nos tópicos seguintes desta documentação.
# Status do chat
Source: https://developer.z-api.io/webhooks/on-chat-presence
PUT /instances/{instanceId}/token/{token}/update-webhook-chat-presence
Webhook de retorno do status do chat
## Conceituação
Esse é o webhook de retorno do status do chat.
O Z-API não aceita webhooks que não sejam **HTTPS**.
Para ver todos os exemplos de retorno por status, consulte a página [Exemplos de retorno de Status do chat](/webhooks/on-chat-presence-examples).
***
## Atualizar webhook
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Body
URL do webhook de presença do chat
### Request Body
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"value": "https://endereco-do-seu-sistema.com.br/instancia/SUA_INSTANCIA/presence"
}
```
***
## Response
### 200
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"value": true
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou PUT conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Exemplos de retorno de Status do chat
Source: https://developer.z-api.io/webhooks/on-chat-presence-examples
Exemplos de retorno do webhook de presença do chat por tipo de status
## Retorno do webhook
### Atributos comuns
Tipo do evento: `PresenceChatCallback`
Número de telefone do contato
Status de presença: `AVAILABLE`, `UNAVAILABLE`, `COMPOSING`, `PAUSED` ou `RECORDING`
Timestamp do último acesso (pode ser null)
Identificador da instância
***
## Exemplos por status
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"type": "PresenceChatCallback",
"phone": "5544999999999",
"status": "AVAILABLE",
"lastSeen": null,
"instanceId": "instance.id"
}
```
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"type": "PresenceChatCallback",
"phone": "5544999999999",
"status": "UNAVAILABLE",
"lastSeen": null,
"instanceId": "instance.id"
}
```
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"type": "PresenceChatCallback",
"phone": "5544999999999",
"status": "COMPOSING",
"lastSeen": null,
"instanceId": "instance.id"
}
```
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"type": "PresenceChatCallback",
"phone": "5544999999999",
"status": "PAUSED",
"lastSeen": null,
"instanceId": "instance.id"
}
```
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"type": "PresenceChatCallback",
"phone": "5544999999999",
"status": "RECORDING",
"lastSeen": null,
"instanceId": "instance.id"
}
```
# Ao receber
Source: https://developer.z-api.io/webhooks/on-message-received
PUT /instances/{instanceId}/token/{token}/update-webhook-received
Webhook de retorno de mensagens recebidas
O webhook `ReceivedCallback` pode ser configurado de duas formas: recebendo apenas as mensagens enviadas por outros usuários, ou recebendo também as mensagens enviadas por você mesmo.
Ao configurar o webhook através do endpoint **[Ao receber - enviadas por mim](/webhooks/on-message-received-and-delivery)**, a API passa a dar prioridade automaticamente à URL configurada nesse endpoint. Ou seja, mesmo que você já tenha um webhook configurado no endpoint `Ao receber`, ele permanece salvo, porém deixa de ser utilizado enquanto o outro estiver ativo.
Para voltar a utilizar a URL configurada no endpoint `Ao receber` e deixar de receber as mensagens enviadas por você mesmo, é necessário desativar a opção **Notificar as enviadas por mim também** através do endpoint **[Atualizar notificar enviadas por mim](/webhooks/update-notify-sent-by-me)**.
## Conceituação
Esse é o webhook de retorno de mensagens recebidas, também é executado quando a sua instância está configurada para notificar também mensagens enviadas por você mesmo.
O Z-API não aceita webhooks que não sejam **HTTPS**.
Os arquivos de mídia ficam disponíveis por **30 dias** no armazenamento da Z-API. Para ver todos os exemplos de retorno por tipo de mensagem, consulte a página [Exemplos de retorno](/webhooks/on-message-received-examples).
***
## Atualizar webhook
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Body
URL do webhook de recebimento
### Request Body
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"value": "https://endereco-do-seu-sistema.com.br/instancia/SUA_INSTANCIA/receive"
}
```
***
## Response
### 200
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"value": true
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou PUT conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Ao receber - enviadas por mim
Source: https://developer.z-api.io/webhooks/on-message-received-and-delivery
PUT /instances/{instanceId}/token/{token}/update-webhook-received-delivery
Webhook de retorno de mensagens recebidas
O webhook `ReceivedCallback` pode ser configurado de duas formas: recebendo apenas as mensagens enviadas por outros usuários, ou recebendo também as mensagens enviadas por você mesmo.
Ao configurar o webhook através do endpoint `Ao receber - enviadas por mim`, a API passa a dar prioridade automaticamente à URL configurada nesse endpoint. Ou seja, mesmo que você já tenha um webhook configurado no endpoint **[Ao receber](/webhooks/on-message-received)**, ele permanece salvo, porém deixa de ser utilizado enquanto o outro estiver ativo.
Para voltar a utilizar a URL configurada no endpoint **[Ao receber](/webhooks/on-message-received)** e deixar de receber as mensagens enviadas por você mesmo, é necessário desativar a opção `Notificar as enviadas por mim também` através do endpoint **[Atualizar notificar enviadas por mim](/webhooks/update-notify-sent-by-me)**.
## Conceituação
Este webhook funciona como o retorno padrão de mensagens recebidas, porém com uma particularidade em relação ao **Ao receber** comum: ao configurá-lo, a URL do webhook de recebimento é atualizada para que as mensagens enviadas por você mesmo também sejam notificadas.
O Z-API não aceita webhooks que não sejam **HTTPS**.
Os arquivos de mídia ficam disponíveis por **30 dias** no armazenamento da Z-API. Para ver todos os exemplos de retorno por tipo de mensagem, consulte a página [Exemplos de retorno](/webhooks/on-message-received-examples).
***
## Atualizar webhook
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Body
URL do webhook de recebimento
### Request Body
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"value": "https://endereco-do-seu-sistema.com.br/instancia/SUA_INSTANCIA/receive-delivery"
}
```
***
## Response
### 200
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"value": true
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou PUT conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Exemplos de retorno de Ao receber
Source: https://developer.z-api.io/webhooks/on-message-received-examples
Exemplos de retorno do webhook de mensagens recebidas por tipo de mensagem
## Retorno do webhook
### Atributos comuns
Todos os retornos de webhook possuem os seguintes atributos em comum:
Identifica se a mensagem recebida é uma resposta de status
ID do contato no WhatsApp
Número de telefone conectado à API
Identifica se a sua mensagem está com status de "Aguardando a mensagem"
Identifica se a mensagem recebida foi editada
Indica se o chat é um grupo
Indica se o chat é um canal
Identificador único da instância que recebeu a mensagem
Identificador da mensagem na conversa
Número de telefone, ou do grupo que enviou a mensagem
Indica se a mensagem enviada partiu do número conectado a API
Momento em que a mensagem foi recebida ou do erro
Status que a mensagem se encontra no momento do envio do callback (PENDING, SENT, RECEIVED, READ ou PLAYED)
Nome do chat ou participante que originou a mensagem
URL da foto do usuário que enviou a mensagem
Nome exibido do remetente
Número de telefone do membro do grupo que enviou a mensagem
ID do contato no WhatsApp, do participante que enviou a mensagem dentro de um grupo
Indicador se a mensagem foi enviada para lista de transmissão
Tipo do evento da instância, nesse caso será `ReceivedCallback`
Tipo de evento ao receber uma ligação, indicando se é ou não de video
***
## Exemplos de retorno por tipo
### Mensagens de texto e mídia
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"isStatusReply": false,
"senderLid": "81896604192873@lid",
"connectedPhone": "554499999999",
"waitingMessage": false,
"isEdit": false,
"isGroup": false,
"isNewsletter": false,
"instanceId": "A20DA9C0183A2D35A260F53F5D2B9244",
"messageId": "A20DA9C0183A2D35A260F53F5D2B9244",
"phone": "5544999999999",
"fromMe": false,
"momment": 1632228638000,
"status": "RECEIVED",
"chatName": "name",
"senderPhoto": "https://",
"senderName": "name",
"participantPhone": null,
"participantLid": null,
"photo": "https://",
"broadcast": false,
"type": "ReceivedCallback",
"text": {
"message": "teste",
"description": "(opcional) em caso da mensagem possuir uma descrição inserida pelo WhatsApp",
"title": "(opcional) em caso da mensagem possuir um título inserido pelo WhatsApp",
"url": "(opcional) caso a mensagem possua um link ligado a ela",
"thumbnailUrl": "(opcional) caso a mensagem possua uma imagem de thumbnail"
}
}
```
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"isStatusReply": false,
"senderLid": "81896604192873@lid",
"connectedPhone": "554499999999",
"waitingMessage": false,
"isEdit": false,
"isGroup": false,
"isNewsletter": false,
"instanceId": "A20DA9C0183A2D35A260F53F5D2B9244",
"messageId": "A20DA9C0183A2D35A260F53F5D2B9244",
"phone": "5544999999999",
"fromMe": false,
"momment": 1632228828000,
"status": "RECEIVED",
"chatName": "name",
"senderPhoto": "https://",
"senderName": "name",
"participantPhone": null,
"participantLid": null,
"photo": "https://",
"broadcast": false,
"type": "ReceivedCallback",
"image": {
"mimeType": "image/jpeg",
"imageUrl": "https://",
"thumbnailUrl": "https://",
"downloadError": null,
"caption": "",
"width": 600,
"height": 315,
"viewOnce": true
}
}
```
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"isStatusReply": false,
"senderLid": "81896604192873@lid",
"connectedPhone": "554499999999",
"waitingMessage": false,
"isEdit": false,
"isGroup": false,
"isNewsletter": false,
"instanceId": "A20DA9C0183A2D35A260F53F5D2B9244",
"messageId": "A20DA9C0183A2D35A260F53F5D2B9244",
"phone": "5544999999999",
"fromMe": false,
"momment": 1632228849000,
"status": "RECEIVED",
"chatName": "name",
"senderPhoto": "https://",
"senderName": "name",
"participantPhone": null,
"participantLid": null,
"photo": "https://",
"broadcast": false,
"type": "ReceivedCallback",
"audio": {
"ptt": true,
"seconds": 10,
"audioUrl": "https://",
"mimeType": "audio/ogg; codecs=opus",
"viewOnce": true
}
}
```
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"isStatusReply": false,
"senderLid": "81896604192873@lid",
"connectedPhone": "554499999999",
"waitingMessage": false,
"isEdit": false,
"isGroup": false,
"isNewsletter": false,
"instanceId": "A20DA9C0183A2D35A260F53F5D2B9244",
"messageId": "A20DA9C0183A2D35A260F53F5D2B9244",
"phone": "5544999999999",
"fromMe": false,
"momment": 1632228889000,
"status": "RECEIVED",
"chatName": "name",
"senderPhoto": "https://",
"senderName": "name",
"participantPhone": null,
"participantLid": null,
"photo": "https://",
"broadcast": false,
"type": "ReceivedCallback",
"video": {
"videoUrl": "https://",
"caption": "",
"mimeType": "video/mp4",
"seconds": 13,
"viewOnce": true
}
}
```
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"isStatusReply": false,
"senderLid": "81896604192873@lid",
"connectedPhone": "554499999999",
"waitingMessage": false,
"isEdit": false,
"isGroup": false,
"isNewsletter": false,
"instanceId": "A20DA9C0183A2D35A260F53F5D2B9244",
"messageId": "A20DA9C0183A2D35A260F53F5D2B9244",
"phone": "5544999999999",
"fromMe": true,
"momment": 1688496074000,
"status": "RECEIVED",
"chatName": "eu",
"senderPhoto": "https://",
"senderName": "name",
"photo": "https://",
"broadcast": false,
"participantPhone": "5544999999999",
"messageExpirationSeconds": 0,
"forwarded": true,
"type": "ReceivedCallback",
"video": {
"videoUrl": "https://",
"caption": "",
"mimeType": "video/mp4"
}
}
```
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"isStatusReply": false,
"senderLid": "81896604192873@lid",
"connectedPhone": "554499999999",
"waitingMessage": false,
"isEdit": false,
"isGroup": false,
"isNewsletter": false,
"instanceId": "A20DA9C0183A2D35A260F53F5D2B9244",
"messageId": "A20DA9C0183A2D35A260F53F5D2B9244",
"phone": "5544999999999",
"fromMe": false,
"momment": 1632228889000,
"status": "RECEIVED",
"chatName": "name",
"senderPhoto": "https://",
"senderName": "name",
"participantPhone": null,
"participantLid": null,
"photo": "https://",
"broadcast": false,
"type": "ReceivedCallback",
"video": {
"videoUrl": "https://",
"caption": "",
"mimeType": "video/mp4"
}
}
```
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"isStatusReply": false,
"senderLid": "81896604192873@lid",
"connectedPhone": "554499999999",
"waitingMessage": false,
"isEdit": false,
"isGroup": false,
"isNewsletter": false,
"instanceId": "A20DA9C0183A2D35A260F53F5D2B9244",
"messageId": "A20DA9C0183A2D35A260F53F5D2B9244",
"phone": "5544999999999",
"fromMe": false,
"momment": 1632228955000,
"status": "RECEIVED",
"chatName": "name",
"senderPhoto": "https://",
"senderName": "name",
"participantPhone": null,
"participantLid": null,
"photo": "https://",
"broadcast": false,
"type": "ReceivedCallback",
"document": {
"documentUrl": "https://",
"mimeType": "application/pdf",
"title": "nome",
"pageCount": 1,
"fileName": "nome.pdf"
}
}
```
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"isStatusReply": false,
"senderLid": "81896604192873@lid",
"connectedPhone": "554499999999",
"waitingMessage": false,
"isEdit": false,
"isGroup": false,
"isNewsletter": false,
"instanceId": "A20DA9C0183A2D35A260F53F5D2B9244",
"messageId": "A20DA9C0183A2D35A260F53F5D2B9244",
"phone": "5544999999999",
"fromMe": false,
"momment": 1632228925000,
"status": "RECEIVED",
"chatName": "name",
"senderPhoto": "https://",
"senderName": "name",
"participantPhone": null,
"participantLid": null,
"photo": "https://",
"broadcast": false,
"type": "ReceivedCallback",
"contact": {
"displayName": "Cesar Baleco",
"vCard": "BEGIN:VCARD\\nVERSION:3.0\\nN:;nome;;;\\nFN:nome\\nTEL;type=CELL;type=VOICE;waid=5544999999999:+55 44 9999-9999\\nEND:VCARD",
"phones": ["5544999999999"]
}
}
```
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"isStatusReply": false,
"senderLid": "81896604192873@lid",
"connectedPhone": "554499999999",
"waitingMessage": false,
"isEdit": false,
"isGroup": false,
"isNewsletter": false,
"instanceId": "A20DA9C0183A2D35A260F53F5D2B9244",
"messageId": "A20DA9C0183A2D35A260F53F5D2B9244",
"phone": "5544999999999",
"fromMe": false,
"momment": 1632228970000,
"status": "RECEIVED",
"chatName": "name",
"senderPhoto": "https://",
"senderName": "name",
"participantPhone": null,
"participantLid": null,
"photo": "https://",
"broadcast": false,
"type": "ReceivedCallback",
"location": {
"longitude": -99.999999999999999,
"latitude": -99.9999999999999999,
"address": "",
"url": ""
}
}
```
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"isStatusReply": false,
"senderLid": "81896604192873@lid",
"connectedPhone": "554499999999",
"waitingMessage": false,
"isEdit": false,
"isGroup": false,
"isNewsletter": false,
"instanceId": "A20DA9C0183A2D35A260F53F5D2B9244",
"messageId": "A20DA9C0183A2D35A260F53F5D2B9244",
"phone": "5544999999999",
"fromMe": false,
"momment": 1632228982000,
"status": "RECEIVED",
"chatName": "name",
"senderPhoto": "https://",
"senderName": "name",
"participantPhone": null,
"participantLid": null,
"photo": "https://",
"broadcast": false,
"type": "ReceivedCallback",
"sticker": {
"stickerUrl": "https://",
"mimeType": "image/webp"
}
}
```
### Reações e interações
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"isStatusReply": false,
"senderLid": "81896604192873@lid",
"connectedPhone": "554499999999",
"waitingMessage": false,
"isEdit": false,
"isGroup": false,
"isNewsletter": false,
"instanceId": "A20DA9C0183A2D35A260F53F5D2B9244",
"messageId": "A20DA9C0183A2D35A260F53F5D2B9244",
"phone": "5544999999999",
"fromMe": false,
"momment": 1632228955000,
"status": "RECEIVED",
"chatName": "name",
"senderPhoto": "https://",
"senderName": "name",
"participantPhone": null,
"participantLid": null,
"photo": "https://",
"broadcast": false,
"type": "ReceivedCallback",
"reaction": {
"value": "❤️",
"time": 1651878681150,
"reactionBy": "554499999999",
"referencedMessage": {
"messageId": "3EB0796DC6B777C0C7CD",
"fromMe": true,
"phone": "5544999999999",
"participant": null
}
}
}
```
### Enquetes
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"isStatusReply": false,
"senderLid": "81896604192873@lid",
"connectedPhone": "554499999999",
"waitingMessage": false,
"isEdit": false,
"isGroup": false,
"isNewsletter": false,
"instanceId": "A20DA9C0183A2D35A260F53F5D2B9244",
"messageId": "A20DA9C0183A2D35A260F53F5D2B9244",
"phone": "5544999999999",
"fromMe": false,
"momment": 1632228638000,
"status": "RECEIVED",
"chatName": "name",
"senderPhoto": "https://",
"senderName": "name",
"participantPhone": null,
"participantLid": null,
"photo": "https://",
"broadcast": false,
"type": "ReceivedCallback",
"poll": {
"question": "Qual a melhor API de WhatsApp?",
"pollMaxOptions": 0,
"options": [
{
"name": "Z-API"
},
{
"name": "Outras"
}
]
}
}
```
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"isStatusReply": false,
"senderLid": "81896604192873@lid",
"connectedPhone": "554499999999",
"waitingMessage": false,
"isEdit": false,
"isGroup": false,
"isNewsletter": false,
"instanceId": "A20DA9C0183A2D35A260F53F5D2B9244",
"messageId": "A20DA9C0183A2D35A260F53F5D2B9244",
"phone": "5544999999999",
"fromMe": false,
"momment": 1632228638000,
"status": "RECEIVED",
"chatName": "name",
"senderPhoto": "https://",
"senderName": "name",
"participantPhone": "se for grupo esse será o participante que respondeu",
"photo": "https://",
"broadcast": false,
"type": "ReceivedCallback",
"pollVote": {
"pollMessageId": "ID da mensagem de enquete que foi respondida",
"options": [
{
"name": "Z-API"
}
]
}
}
```
### Botões e listas
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"isStatusReply": false,
"senderLid": "81896604192873@lid",
"connectedPhone": "554499999999",
"waitingMessage": false,
"isEdit": false,
"isGroup": false,
"isNewsletter": false,
"instanceId": "A20DA9C0183A2D35A260F53F5D2B9244",
"messageId": "A20DA9C0183A2D35A260F53F5D2B9244",
"phone": "5544999999999",
"fromMe": false,
"momment": 1634645380000,
"status": "RECEIVED",
"chatName": "Nome",
"senderPhoto": "https://",
"senderName": "Nome",
"participantPhone": null,
"participantLid": null,
"photo": "https://",
"broadcast": false,
"referenceMessageId": "A20DA9C0183A2D35A260F53F5D2B9244",
"forwarded": false,
"type": "ReceivedCallback",
"buttonsResponseMessage": {
"buttonId": "1",
"message": "Ótimo"
}
}
```
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"isStatusReply": false,
"senderLid": "81896604192873@lid",
"connectedPhone": "554499999999",
"waitingMessage": false,
"isEdit": false,
"isGroup": false,
"isNewsletter": false,
"instanceId": "A20DA9C0183A2D35A260F53F5D2B9244",
"messageId": "A20DA9C0183A2D35A260F53F5D2B9244",
"phone": "5544999999999",
"fromMe": false,
"momment": 1634645683000,
"status": "RECEIVED",
"chatName": "Nome",
"senderPhoto": "https://",
"senderName": "Nome",
"participantPhone": null,
"participantLid": null,
"photo": "https://",
"broadcast": false,
"referenceMessageId": "A20DA9C0183A2D35A260F53F5D2B9244",
"forwarded": false,
"type": "ReceivedCallback",
"listResponseMessage": {
"message": "Z-API Asas para sua imaginação",
"title": "Z-API",
"selectedRowId": "1"
}
}
```
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"isStatusReply": false,
"chatLid": "81896604192873@lid",
"connectedPhone": "554499999999",
"waitingMessage": false,
"isEdit": false,
"isGroup": false,
"isNewsletter": false,
"instanceId": "3C67AB641C8AA0412F6A2242B4E23AC7",
"messageId": "9D968A5FA2880508C4",
"phone": "554499999999",
"fromMe": false,
"momment": 1708455444850,
"status": "RECEIVED",
"chatName": "name",
"senderPhoto": null,
"senderName": "554499999999",
"photo": null,
"broadcast": false,
"participantLid": null,
"forwarded": false,
"type": "ReceivedCallback",
"fromApi": false,
"buttonsMessage": {
"imageUrl": "URL da imagem",
"videoUrl": null,
"message": "Texto da mensagem",
"buttons": [
{
"buttonId": "1",
"type": 1,
"buttonText": {
"displayText": "Texto do botão 1"
}
},
{
"buttonId": "2",
"type": 1,
"buttonText": {
"displayText": "Texto do botão 2"
}
}
]
}
}
```
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"isStatusReply": false,
"chatLid": "81896604192873@lid",
"connectedPhone": "554499999999",
"waitingMessage": false,
"isEdit": false,
"isGroup": false,
"isNewsletter": false,
"instanceId": "3C67AB641C8AA0412F6A2242B4E23AC7",
"messageId": "9D968A5FA2880508C4",
"phone": "554499999999",
"fromMe": false,
"momment": 1708455444850,
"status": "RECEIVED",
"chatName": "name",
"senderPhoto": null,
"senderName": "554499999999",
"photo": null,
"broadcast": false,
"participantLid": null,
"forwarded": false,
"type": "ReceivedCallback",
"fromApi": false,
"buttonsMessage": {
"imageUrl": null,
"videoUrl": "URL do video",
"message": "Texto da mensagem",
"buttons": [
{
"buttonId": "1",
"type": 1,
"buttonText": {
"displayText": "Texto do botão 1"
}
},
{
"buttonId": "2",
"type": 1,
"buttonText": {
"displayText": "Texto do botão 2"
}
}
]
}
}
```
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"isStatusReply": false,
"chatLid": "81896604192873@lid",
"connectedPhone": "554499999999",
"waitingMessage": false,
"isEdit": false,
"isGroup": false,
"isNewsletter": false,
"instanceId": "3C67AB641C8AA0412F6A2242B4E23AC7",
"messageId": "9D968A5FA2880508C4",
"phone": "554499999999",
"fromMe": false,
"momment": 1708455444850,
"status": "RECEIVED",
"chatName": "name",
"senderPhoto": null,
"senderName": "554499999999",
"photo": null,
"broadcast": false,
"participantLid": null,
"forwarded": false,
"type": "ReceivedCallback",
"fromApi": false,
"hydratedTemplate": {
"header": {},
"message": "texto da mensagem",
"footer": "",
"title": "",
"templateId": "",
"hydratedButtons": [
{
"urlButton": {
"displayText": "Copiar código",
"url": "https://www.whatsapp.com/otp/code/?otp_type=COPY_CODE&code=otp123"
},
"index": 0
}
]
}
}
```
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"isStatusReply": false,
"chatLid": "81896604192873@lid",
"connectedPhone": "554499999999",
"waitingMessage": false,
"isEdit": false,
"isGroup": false,
"isNewsletter": false,
"instanceId": "3C67AB641C8AA0412F6A2242B4E23AC7",
"messageId": "9D968A5FA2880508C4",
"phone": "554499999999",
"fromMe": false,
"momment": 1708455444850,
"status": "RECEIVED",
"chatName": "name",
"senderPhoto": null,
"senderName": "554499999999",
"photo": null,
"broadcast": false,
"participantLid": null,
"forwarded": false,
"type": "ReceivedCallback",
"fromApi": false,
"pixKeyMessage": {
"currency": "BRL",
"referenceId": "4PXRAHSIRDA",
"key": "pixkey",
"keyType": "EVP",
"merchantName": "Pix"
}
}
```
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"isStatusReply": false,
"chatLid": null,
"connectedPhone": "554499999999",
"waitingMessage": false,
"isEdit": false,
"isGroup": false,
"isNewsletter": false,
"instanceId": "A20DA9C0183A2D35A260F53F5D2B9244",
"messageId": "A20DA9C0183A2D35A260F53F5D2B9244",
"phone": "554499999999",
"fromMe": true,
"momment": 1739368022130,
"status": "SENT",
"chatName": "Nome",
"senderPhoto": null,
"senderName": "Nome",
"photo": "https://",
"broadcast": false,
"participantLid": null,
"forwarded": false,
"type": "ReceivedCallback",
"fromApi": true,
"carouselMessage": {
"text": "Texto da mensagem",
"cards": [
{
"header": {
"image": {
"imageUrl": "https://",
"thumbnailUrl": "https://",
"caption": "",
"mimeType": "image/jpeg",
"viewOnce": false,
"width": 0,
"height": 0
}
},
"message": "Mensagem do cartão do carrosel",
"footer": "",
"title": "",
"hydratedButtons": [
{
"index": 0,
"urlButton": {
"displayText": "Texto do botão",
"url": "https://"
}
},
{
"index": 1,
"quickReplyButton": {
"displayText": "Texto do botão",
"id": "2"
}
}
]
},
{
"header": {
"image": {
"imageUrl": "https://",
"thumbnailUrl": "https://",
"caption": "",
"mimeType": "image/jpeg",
"viewOnce": false,
"width": 0,
"height": 0
}
},
"message": "Mensagem do cartão do carrosel",
"footer": "",
"title": "",
"hydratedButtons": [
{
"index": 0,
"urlButton": {
"displayText": "Texto do botão",
"url": "https://"
}
},
{
"index": 1,
"quickReplyButton": {
"displayText": "Texto do botão",
"id": "2"
}
}
]
}
]
}
}
```
### Templates
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"isStatusReply": false,
"chatLid": "81896604192873@lid",
"connectedPhone": "554499999999",
"waitingMessage": false,
"isEdit": false,
"isGroup": false,
"isNewsletter": false,
"instanceId": "3C67AB641C8AA0412F6A2242B4E23AC7",
"messageId": "702CC5F7E0A6BF4421",
"phone": "5544999999999",
"fromMe": false,
"momment": 1708457193876,
"status": "RECEIVED",
"chatName": "Test Number",
"senderPhoto": null,
"senderName": "5544999999999",
"photo": null,
"broadcast": false,
"participantLid": null,
"forwarded": false,
"type": "ReceivedCallback",
"fromApi": false,
"hydratedTemplate": {
"header": {},
"message": "texto da mensagem",
"footer": "rodapé da mensagem",
"title": "título da mensagem",
"templateId": "790118069824606",
"hydratedButtons": []
}
}
```
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"isStatusReply": false,
"chatLid": "81896604192873@lid",
"connectedPhone": "554499999999",
"waitingMessage": false,
"isEdit": false,
"isGroup": false,
"isNewsletter": false,
"instanceId": "3C67AB641C8AA0412F6A2242B4E23AC7",
"messageId": "885FF934BF100D579E",
"phone": "554499999999",
"fromMe": false,
"momment": 1708454725028,
"status": "RECEIVED",
"chatName": "name",
"senderPhoto": null,
"senderName": "554499999999",
"photo": null,
"broadcast": false,
"participantLid": null,
"forwarded": false,
"type": "ReceivedCallback",
"fromApi": false,
"hydratedTemplate": {
"header": {
"image": {
"imageUrl": "https://example.jpeg",
"thumbnailUrl": "https://example.jpeg",
"caption": "",
"mimeType": "image/jpeg",
"viewOnce": false,
"width": 1600,
"height": 926
}
},
"message": "texto da mensagem",
"footer": "rodapé da mensagem",
"title": "título da mensagem",
"templateId": "674504507982622",
"hydratedButtons": []
}
}
```
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"isStatusReply": false,
"chatLid": "81896604192873@lid",
"connectedPhone": "554499999999",
"waitingMessage": false,
"isEdit": false,
"isGroup": false,
"isNewsletter": false,
"instanceId": "3C67AB641C8AA0412F6A2242B4E23AC7",
"messageId": "0E4AD761B62E3D5EF9",
"phone": "5544999999999",
"fromMe": false,
"momment": 1708456287181,
"status": "RECEIVED",
"chatName": "name",
"senderPhoto": null,
"senderName": "5544999999999",
"photo": null,
"broadcast": false,
"participantLid": null,
"forwarded": false,
"type": "ReceivedCallback",
"fromApi": false,
"hydratedTemplate": {
"header": {
"video": {
"videoUrl": "https://example.mp4",
"caption": "",
"mimeType": "video/mp4",
"width": 0,
"height": 0,
"seconds": 0,
"viewOnce": false
}
},
"message": "texto da mensagem",
"footer": "rodapé da mensagem",
"title": "título da mensagem",
"templateId": "938481574354947",
"hydratedButtons": []
}
}
```
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"isStatusReply": false,
"chatLid": "81896604192873@lid",
"connectedPhone": "554499999999",
"waitingMessage": false,
"isEdit": false,
"isGroup": false,
"isNewsletter": false,
"instanceId": "3C67AB641C8AA0412F6A2242B4E23AC7",
"messageId": "9D968A5FA2880508C4",
"phone": "554499999999",
"fromMe": false,
"momment": 1708455444850,
"status": "RECEIVED",
"chatName": "name",
"senderPhoto": null,
"senderName": "554499999999",
"photo": null,
"broadcast": false,
"participantLid": null,
"forwarded": false,
"type": "ReceivedCallback",
"fromApi": false,
"hydratedTemplate": {
"header": {
"document": {
"documentUrl": "https://example.pdf",
"mimeType": "application/pdf"
}
},
"message": "texto da mensagem",
"footer": "rodapé da mensagem",
"title": "título da mensagem",
"templateId": "811492407484976",
"hydratedButtons": []
}
}
```
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"isStatusReply": false,
"chatLid": "81896604192873@lid",
"connectedPhone": "554499999999",
"waitingMessage": false,
"isEdit": false,
"isGroup": false,
"isNewsletter": false,
"instanceId": "3C67AB641C8AA0412F6A2242B4E23AC7",
"messageId": "27BBF23E0185D363D9",
"phone": "554499999999",
"fromMe": false,
"momment": 1708456969808,
"status": "RECEIVED",
"chatName": "name",
"senderPhoto": null,
"senderName": "554499999999",
"photo": null,
"broadcast": false,
"participantLid": null,
"forwarded": false,
"type": "ReceivedCallback",
"fromApi": false,
"hydratedTemplate": {
"header": {
"location": {
"longitude": -46.6388,
"latitude": -23.5489,
"name": "nome do lugar",
"address": "nome do endereço"
}
},
"message": "texto da mensagem",
"footer": "rodapé da mensagem",
"title": "título da mensagem",
"templateId": "1143940003434066",
"hydratedButtons": []
}
}
```
### Anúncios
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"isStatusReply": false,
"senderLid": "81896604192873@lid",
"connectedPhone": "554499999999",
"waitingMessage": false,
"isGroup": false,
"isEdit": false,
"isNewsletter": false,
"instanceId": "A20DA9C0183A2D35A260F53F5D2B9244",
"messageId": "A20DA9C0183A2D35A260F53F5D2B9244",
"phone": "5544999999999",
"fromMe": false,
"momment": 1657209752000,
"status": "RECEIVED",
"chatName": "name",
"senderPhoto": null,
"senderName": "name",
"photo": null,
"broadcast": false,
"externalAdReply": {
"title": "Titulo",
"body": "texto do anuncio",
"mediaType": "IMAGE",
"thumbnailUrl": "https://",
"sourceType": "ad",
"sourceId": "23722824350495506",
"ctwaClid": "Aff-niaAw7V94N8LGd79Vjr43TlJD4UnoBdpZJQ3LzABitbbG6wgKBSVOth4EN0IDr9glsKWjm2LBaFrJG3Nb0ILxP49ZtossVBNzlS8cFXBvv2ow7gNw",
"sourceUrl": "https://",
"containsAutoReply": false,
"renderLargerThumbnail": true,
"showAdAttribution": true
},
"messageExpirationSeconds": 0,
"forwarded": false,
"type": "ReceivedCallback",
"text": {
"message": "mensagem recebida",
"description": "texto do anuncio",
"title": "titulo",
"url": "https://",
"thumbnailUrl": "https://"
}
}
```
### Produtos e pedidos
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"isStatusReply": false,
"senderLid": "81896604192873@lid",
"connectedPhone": "554499999999",
"waitingMessage": false,
"isEdit": false,
"isGroup": false,
"isNewsletter": false,
"instanceId": "A20DA9C0183A2D35A260F53F5D2B9244",
"messageId": "A20DA9C0183A2D35A260F53F5D2B9244",
"phone": "5544999999999",
"fromMe": false,
"momment": 1632233527000,
"status": "RECEIVED",
"senderPhoto": "https://",
"senderName": "5544999999999",
"participantPhone": null,
"participantLid": null,
"photo": "https://",
"broadcast": false,
"type": "ReceivedCallback",
"product": {
"productImage": "https://",
"businessOwnerJid": "5544999999999",
"currencyCode": "BRL",
"productId": "99999999999999999999",
"description": "",
"productImageCount": 1,
"price": 1,
"url": "",
"retailerId": "",
"firstImageId": "",
"title": "name"
}
}
```
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"isStatusReply": false,
"senderLid": "81896604192873@lid",
"connectedPhone": "554499999999",
"waitingMessage": false,
"isEdit": false,
"isGroup": false,
"isNewsletter": false,
"instanceId": "A20DA9C0183A2D35A260F53F5D2B9244",
"messageId": "A20DA9C0183A2D35A260F53F5D2B9244",
"phone": "5544999999999",
"fromMe": false,
"momment": 1632233527000,
"status": "RECEIVED",
"chatName": "name",
"senderPhoto": null,
"senderName": "name",
"photo": "https://",
"broadcast": false,
"forwarded": false,
"type": "ReceivedCallback",
"order": {
"itemCount": 1,
"orderId": "422508169684569",
"message": "",
"orderTitle": "name",
"sellerJid": "5544999999999",
"thumbnailUrl": "https://",
"token": "AR5d4yUr+DmSzeCR2kUtPEeMfS+eG0O+S/T/17B+oY1mfA==",
"currency": "BRL",
"total": 2000,
"subTotal": 2000,
"products": [
{
"quantity": 1,
"name": "nameProduct",
"productId": "5338924696127051",
"retailerId": "1242",
"price": 2000,
"currencyCode": "BRL"
}
]
}
}
```
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"isStatusReply": false,
"senderLid": "81896604192873@lid",
"connectedPhone": "554499999999",
"waitingMessage": false,
"isEdit": false,
"isGroup": false,
"isNewsletter": false,
"instanceId": "A20DA9C0183A2D35A260F53F5D2B9244",
"messageId": "A20DA9C0183A2D35A260F53F5D2B9244",
"phone": "5544999999999",
"fromMe": false,
"momment": 1632228925000,
"status": "RECEIVED",
"chatName": "name",
"senderPhoto": "https://",
"senderName": "name",
"participantPhone": null,
"participantLid": null,
"photo": "https://",
"broadcast": false,
"type": "ReceivedCallback",
"reviewOrder": {
"currency": "BRL",
"referenceId": "4N9AVI38VOB",
"orderRequestId": "4N9AVI38VYZ",
"orderStatus": "processing",
"paymentStatus": "pending",
"total": 605,
"subTotal": 600,
"discount": 10,
"shipping": 5,
"tax": 10,
"products": [
{
"name": "order 1",
"quantity": 2,
"isCustomItem": true,
"productId": "custom-item-4N9AVI38WI1",
"value": 150
}
]
}
}
```
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"isStatusReply": false,
"senderLid": "81896604192873@lid",
"connectedPhone": "554499999999",
"waitingMessage": false,
"isEdit": false,
"isGroup": false,
"isNewsletter": false,
"instanceId": "A20DA9C0183A2D35A260F53F5D2B9244",
"messageId": "A20DA9C0183A2D35A260F53F5D2B9244",
"phone": "5544999999999",
"fromMe": false,
"momment": 1632228925000,
"status": "RECEIVED",
"chatName": "name",
"senderPhoto": "https://",
"senderName": "name",
"participantPhone": null,
"participantLid": null,
"photo": "https://",
"broadcast": false,
"type": "ReceivedCallback",
"reviewAndPay": {
"type": "physical-goods",
"currency": "BRL",
"referenceId": "4N9AVI38VOB",
"orderRequestId": "4N9AVI38VYZ",
"orderStatus": "pending",
"paymentStatus": "pending",
"total": 605,
"subTotal": 600,
"discount": 10,
"shipping": 5,
"tax": 10,
"products": [
{
"name": "order 1",
"quantity": 2,
"isCustomItem": true,
"productId": "custom-item-4N9AVI38WI1",
"value": 150
}
]
}
}
```
### Pagamentos
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"isStatusReply": false,
"senderLid": "81896604192873@lid",
"connectedPhone": "554499999999",
"waitingMessage": false,
"isEdit": false,
"isGroup": false,
"isNewsletter": false,
"instanceId": "A20DA9C0183A2D35A260F53F5D2B9244",
"messageId": "A20DA9C0183A2D35A260F53F5D2B9244",
"phone": "5544999999999",
"fromMe": false,
"momment": 1632229683000,
"status": "RECEIVED",
"chatName": "name",
"senderPhoto": "https://",
"senderName": "name",
"participantPhone": null,
"participantLid": null,
"photo": "https://",
"broadcast": false,
"type": "ReceivedCallback",
"requestPayment": {
"value": 1,
"currencyCode": "BRL",
"expiration": 1632834482000,
"requestPhone": "5544999999999",
"paymentInfo": {
"receiverPhone": "5544999999999",
"value": 1,
"currencyCode": "BRL",
"status": "WAITING",
"transactionStatus": "COLLECT_SUCCESS"
}
}
}
```
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"isStatusReply": false,
"senderLid": "81896604192873@lid",
"connectedPhone": "554499999999",
"waitingMessage": false,
"isEdit": false,
"isGroup": false,
"isNewsletter": false,
"instanceId": "A20DA9C0183A2D35A260F53F5D2B9244",
"messageId": "A20DA9C0183A2D35A260F53F5D2B9244",
"phone": "5544999999999",
"fromMe": false,
"momment": 1632230512000,
"status": "RECEIVED",
"chatName": "name",
"senderPhoto": "https://",
"senderName": "name",
"participantPhone": null,
"participantLid": null,
"photo": "https://",
"broadcast": false,
"type": "ReceivedCallback",
"sendPayment": {
"paymentInfo": {
"receiverPhone": "5544999999999",
"value": 1,
"currencyCode": "BRL",
"status": "COMPLETE",
"transactionStatus": "SUCCESS"
}
}
}
```
### Eventos
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"isStatusReply": false,
"senderLid": "81896604192873@lid",
"connectedPhone": "554499999999",
"waitingMessage": false,
"isEdit": false,
"isGroup": true,
"isNewsletter": false,
"instanceId": "A20DA9C0183A2D35A260F53F5D2B9244",
"messageId": "A20DA9C0183A2D35A260F53F5D2B9244",
"phone": "120363019502650977-group",
"fromMe": false,
"momment": 1632228638000,
"status": "RECEIVED",
"chatName": "name",
"senderPhoto": "https://",
"senderName": "name",
"participantPhone": null,
"participantLid": null,
"photo": "https://",
"broadcast": false,
"type": "ReceivedCallback",
"event": {
"name": "Nome do evento",
"description": "Descrição do evento",
"canceled": false,
"joinLink": "https://call.whatsapp.com/video/v9123XNFG50L6iO79NddXNvKQr6bb3",
"scheduleTime": 1716915653,
"location": {}
}
}
```
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"isStatusReply": false,
"senderLid": "81896604192873@lid",
"connectedPhone": "554499999999",
"waitingMessage": false,
"isEdit": false,
"isGroup": true,
"isNewsletter": false,
"instanceId": "A20DA9C0183A2D35A260F53F5D2B9244",
"messageId": "A20DA9C0183A2D35A260F53F5D2B9244",
"phone": "120363019502650977-group",
"fromMe": false,
"momment": 1632228638000,
"status": "RECEIVED",
"chatName": "name",
"senderPhoto": "https://",
"senderName": "name",
"participantPhone": null,
"participantLid": null,
"photo": "https://",
"broadcast": false,
"type": "ReceivedCallback",
"eventResponse": {
"response": "GOING",
"responseFrom": "554499999999",
"time": 1714423417000,
"referencedMessage": {
"messageId": "D2D612289D9E8F62307D72409A8D9DC3",
"fromMe": false,
"phone": "120363239161320697-group",
"participant": "554499999988"
}
}
}
```
### Outras interações
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"isStatusReply": false,
"senderLid": "81896604192873@lid",
"connectedPhone": "554499999999",
"waitingMessage": false,
"isEdit": false,
"isGroup": false,
"isNewsletter": false,
"instanceId": "A20DA9C0183A2D35A260F53F5D2B9244",
"messageId": "A20DA9C0183A2D35A260F53F5D2B9244",
"phone": "5544999999999",
"fromMe": true,
"momment": 1632228955000,
"status": "RECEIVED",
"chatName": "name",
"senderPhoto": "https://",
"senderName": "name",
"participantPhone": null,
"participantLid": null,
"photo": "https://",
"broadcast": false,
"type": "ReceivedCallback",
"pinMessage": {
"action": "pin",
"pinDurationInSecs": 604800,
"referencedMessage": {
"messageId": "3EB0796DC6B777C0C7CD",
"fromMe": true,
"phone": "554499999999",
"participant": null
}
}
}
```
### Status
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"isStatusReply": true,
"chatLid": "81896604192873@lid",
"connectedPhone": "554499999999",
"waitingMessage": false,
"isEdit": false,
"isGroup": false,
"isNewsletter": false,
"instanceId": "A20DA9C0183A2D35A260F53F5D2B9244",
"messageId": "A20DA9C0183A2D35A260F53F5D2B9244",
"phone": "5544999999999",
"fromMe": false,
"momment": 1779134507000,
"status": "RECEIVED",
"chatName": "name",
"senderPhoto": null,
"senderName": "name",
"photo": "https://",
"broadcast": false,
"participantLid": null,
"referenceMessageId": "3EB054C12BAAC70228AAB6",
"messageExpirationSeconds": 0,
"forwarded": false,
"type": "ReceivedCallback",
"fromApi": false,
"text": {
"message": "teste"
}
}
```
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"isStatusReply": true,
"chatLid": "81896604192873@lid",
"connectedPhone": "554499999999",
"waitingMessage": false,
"isEdit": false,
"isGroup": false,
"isNewsletter": false,
"instanceId": "A20DA9C0183A2D35A260F53F5D2B9244",
"messageId": "A20DA9C0183A2D35A260F53F5D2B9244",
"phone": "5544999999999",
"fromMe": false,
"momment": 1779134507000,
"status": "RECEIVED",
"chatName": "name",
"senderPhoto": null,
"senderName": "name",
"photo": "https://",
"broadcast": false,
"participantLid": null,
"referenceMessageId": "3EB054C12BAAC70228AAB6",
"messageExpirationSeconds": 0,
"forwarded": false,
"type": "ReceivedCallback",
"fromApi": false,
"text": {
"message": "teste"
},
"statusImage": {
"imageUrl": "https://",
"thumbnailUrl": "https://",
"caption": "teste",
"mimeType": "image/jpeg",
"width": 960,
"height": 1280
}
}
```
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"isStatusReply": true,
"chatLid": "81896604192873@lid",
"connectedPhone": "554499999999",
"waitingMessage": false,
"isEdit": false,
"isGroup": false,
"isNewsletter": false,
"instanceId": "A20DA9C0183A2D35A260F53F5D2B9244",
"messageId": "A20DA9C0183A2D35A260F53F5D2B9244",
"phone": "5544999999999",
"fromMe": false,
"momment": 1779134507000,
"status": "RECEIVED",
"chatName": "name",
"senderPhoto": null,
"senderName": "name",
"photo": "https://",
"broadcast": false,
"participantLid": null,
"referenceMessageId": "3EB054C12BAAC70228AAB6",
"messageExpirationSeconds": 0,
"forwarded": false,
"type": "ReceivedCallback",
"fromApi": false,
"text": {
"message": "teste"
},
"statusVideo": {
"videoUrl": "https://f004.backblazeb2.com/file/temp-file-download/instances/3FXXXXXXXXXXXXXXXXXXXXXXXF/3XXXXXXXXXXXXXXXX64/9bXXXXXPu_WXXXXXYgcA==.mp4",
"caption": "Teste",
"mimeType": "video/mp4"
}
}
```
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"isStatusReply": true,
"chatLid": "81896604192873@lid",
"connectedPhone": "554499999999",
"waitingMessage": false,
"isEdit": false,
"isGroup": false,
"isNewsletter": false,
"instanceId": "A20DA9C0183A2D35A260F53F5D2B9244",
"messageId": "A20DA9C0183A2D35A260F53F5D2B9244",
"phone": "5544999999999",
"fromMe": false,
"momment": 1779134507000,
"status": "RECEIVED",
"chatName": "name",
"senderPhoto": null,
"senderName": "name",
"photo": "https://",
"broadcast": false,
"participantLid": null,
"referenceMessageId": "3EB054C12BAAC70228AAB6",
"messageExpirationSeconds": 0,
"forwarded": false,
"type": "ReceivedCallback",
"fromApi": false,
"text": {
"message": "teste"
},
"statusAudio": {
"audioUrl": "https://f004.backblazeb2.com/file/temp-file-download/instances/3FXXXXXXXXXXXXXXXXXXXXXXXF/3XXXXXXXXXXXXXXXX64/dXXXXXXXXXXXXXXXXQ==.ogg",
"mimeType": "audio/ogg; codecs=opus"
}
}
```
### Lista de transmissão
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"isStatusReply": false,
"chatLid": null,
"connectedPhone": "554499999999",
"waitingMessage": false,
"isEdit": false,
"isGroup": false,
"isNewsletter": false,
"instanceId": "3C67AB641C8AA0412F6A2242B4E23AC7",
"messageId": "702CC5F7E0A6BF4421",
"phone": "1774895799-broadcast",
"fromMe": true,
"momment": 1774895725000,
"status": "RECEIVED",
"broadcast": true,
"type": "ReceivedCallback",
"broadcastRecipients": ["126104585119999", "138955211189999"],
"text": {
"message": "Teste de mensagem de lista de transmissão"
}
}
```
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"isStatusReply": false,
"isGroup": false,
"isNewsletter": false,
"instanceId": "A20DA9C0183A2D35A260F53F5D2B9244",
"messageId": "A20DA9C0183A2D35A260F53F5D2B9244",
"momment": 1736797729000,
"status": "RECEIVED",
"fromMe": true,
"phone": "5544999999999",
"chatName": "chat",
"type": "ReceivedCallback",
"waitingMessage": true,
"viewOnce": true
}
```
***
## Notificações
Além das mensagens, o webhook também recebe notificações de chamadas, grupos e conta.
### Chamadas
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"chatLid": "999999999999@lid",
"isGroup": false,
"isNewsletter": false,
"instanceId": "A20DA9C0183A2D35A260F53F5D2B9244",
"messageId": "1779374011-59",
"phone": "999999999999@lid",
"connectedPhone": "5544999999999",
"fromMe": false,
"fromApi": false,
"momment": 1779374147000,
"expiresAt": null,
"status": "RECEIVED",
"chatName": "name",
"senderPhoto": "https://",
"senderName": "name",
"photo": "https://",
"broadcast": false,
"participantLid": null,
"referenceMessageId": null,
"externalAdReply": null,
"forwarded": false,
"type": "ReceivedCallback",
"notification": "CALL_RECEIVED",
"notificationParameters": [],
"callId": "F44E0E2011E7C784BB9A4AC11749C436",
"code": null,
"callDirection": "incoming",
"isVideo": false
}
```
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"chatLid": "999999999999@lid",
"isGroup": false,
"isNewsletter": false,
"instanceId": "A20DA9C0183A2D35A260F53F5D2B9244",
"messageId": "1779374011-59",
"phone": "999999999999@lid",
"connectedPhone": "5544999999999",
"fromMe": false,
"fromApi": false,
"momment": 1779374147000,
"expiresAt": null,
"status": "RECEIVED",
"chatName": "name",
"senderPhoto": "https://",
"senderName": "name",
"photo": "https://",
"broadcast": false,
"participantLid": null,
"referenceMessageId": null,
"externalAdReply": null,
"forwarded": false,
"type": "ReceivedCallback",
"notification": "CALL_MISSED_VOICE",
"notificationParameters": [],
"callId": "F44E0E2011E7C784BB9A4AC11749C436",
"code": null,
"callDirection": "incoming",
"isVideo": false
}
```
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"chatLid": "999999999999@lid",
"isGroup": false,
"isNewsletter": false,
"instanceId": "3EDCD745FEB360458A8DBAA76574573D",
"messageId": "1779374011-52",
"phone": "999999999999@lid",
"connectedPhone": "5544999999999",
"fromMe": false,
"fromApi": false,
"momment": 1779374129000,
"expiresAt": null,
"status": "RECEIVED",
"chatName": "name",
"senderPhoto": "https://",
"senderName": "name",
"photo": "https://",
"broadcast": false,
"participantLid": null,
"referenceMessageId": null,
"externalAdReply": null,
"forwarded": false,
"type": "ReceivedCallback",
"notification": "CALL_MISSED_VIDEO",
"notificationParameters": [],
"callId": "F44E0E2011E7C784BB9A4AC11749C436",
"code": null,
"callDirection": "incoming",
"isVideo": true
}
```
### Chamadas com funcionalidade de ligações habilitadas e contratadas
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"chatLid": "999999999999@lid",
"isGroup": false,
"isNewsletter": false,
"instanceId": "A20DA9C0183A2D35A260F53F5D2B9244",
"messageId": "F44E0E2011E7C784BB9A4AC11749C436",
"phone": "5544999999999",
"connectedPhone": "5544999999999",
"fromMe": false,
"fromApi": false,
"momment": 1779374642000,
"expiresAt": null,
"status": "RECEIVED",
"chatName": "name",
"senderPhoto": "https://",
"senderName": "name",
"photo": "https://",
"broadcast": false,
"participantLid": null,
"referenceMessageId": null,
"externalAdReply": null,
"forwarded": false,
"type": "ReceivedCallback",
"notification": "CALL_RECEIVED",
"notificationParameters": [],
"callId": "F44E0E2011E7C784BB9A4AC11749C436",
"code": null,
"callDirection": "incoming",
"isVideo": false
}
```
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"chatLid": "999999999999@lid",
"isGroup": false,
"isNewsletter": false,
"instanceId": "A20DA9C0183A2D35A260F53F5D2B9244",
"messageId": "F44E0E2011E7C784BB9A4AC11749C436",
"phone": "5544999999999",
"connectedPhone": "5544999999999",
"fromMe": false,
"fromApi": false,
"momment": 1779374642000,
"expiresAt": null,
"status": "RECEIVED",
"chatName": "name",
"senderPhoto": "https://",
"senderName": "name",
"photo": "https://",
"broadcast": false,
"participantLid": null,
"referenceMessageId": null,
"externalAdReply": null,
"forwarded": false,
"type": "ReceivedCallback",
"notification": "CALL_ACCEPTED",
"notificationParameters": [],
"callId": "F44E0E2011E7C784BB9A4AC11749C436",
"code": null,
"callDirection": "incoming",
"isVideo": false
}
```
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"chatLid": "999999999999@lid",
"isGroup": false,
"isNewsletter": false,
"instanceId": "A20DA9C0183A2D35A260F53F5D2B9244",
"messageId": "F44E0E2011E7C784BB9A4AC11749C436",
"phone": "5544999999999",
"connectedPhone": "5544999999999",
"fromMe": false,
"fromApi": false,
"momment": 1779374642000,
"expiresAt": null,
"status": "RECEIVED",
"chatName": "name",
"senderPhoto": "https://",
"senderName": "name",
"photo": "https://",
"broadcast": false,
"participantLid": null,
"referenceMessageId": null,
"externalAdReply": null,
"forwarded": false,
"type": "ReceivedCallback",
"notification": "CALL_STARTED",
"notificationParameters": [],
"callId": "F44E0E2011E7C784BB9A4AC11749C436",
"code": null,
"callDirection": "incoming",
"isVideo": false
}
```
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"chatLid": "999999999999@lid",
"isGroup": false,
"isNewsletter": false,
"instanceId": "A20DA9C0183A2D35A260F53F5D2B9244",
"messageId": "F44E0E2011E7C784BB9A4AC11749C436",
"phone": "5544999999999",
"connectedPhone": "5544999999999",
"fromMe": false,
"fromApi": false,
"momment": 1779374642000,
"expiresAt": null,
"status": "RECEIVED",
"chatName": "name",
"senderPhoto": "https://",
"senderName": "name",
"photo": "https://",
"broadcast": false,
"participantLid": null,
"referenceMessageId": null,
"externalAdReply": null,
"forwarded": false,
"type": "ReceivedCallback",
"notification": "CALL_ENDED",
"notificationParameters": [],
"callId": "F44E0E2011E7C784BB9A4AC11749C436",
"code": null,
"callDirection": "incoming",
"isVideo": false,
"callDuration": 25, //Segundos
"callRecordingUrl": "https://www.exemploDeAudio.mp3"
}
```
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"chatLid": "999999999999@lid",
"isGroup": false,
"isNewsletter": false,
"instanceId": "A20DA9C0183A2D35A260F53F5D2B9244",
"messageId": "F44E0E2011E7C784BB9A4AC11749C436",
"phone": "5544999999999",
"connectedPhone": "5544999999999",
"fromMe": false,
"fromApi": false,
"momment": 1779374642000,
"expiresAt": null,
"status": "RECEIVED",
"chatName": "name",
"senderPhoto": "https://",
"senderName": "name",
"photo": "https://",
"broadcast": false,
"participantLid": null,
"referenceMessageId": null,
"externalAdReply": null,
"forwarded": false,
"type": "ReceivedCallback",
"notification": "CALL_MISSED",
"notificationParameters": [],
"callId": "F44E0E2011E7C784BB9A4AC11749C436",
"code": null,
"callDirection": "incoming",
"isVideo": false
}
```
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"chatLid": "999999999999@lid",
"isGroup": false,
"isNewsletter": false,
"instanceId": "A20DA9C0183A2D35A260F53F5D2B9244",
"messageId": "F44E0E2011E7C784BB9A4AC11749C436",
"phone": "5544999999999",
"connectedPhone": "5544999999999",
"fromMe": false,
"fromApi": false,
"momment": 1779374642000,
"expiresAt": null,
"status": "RECEIVED",
"chatName": "name",
"senderPhoto": "https://",
"senderName": "name",
"photo": "https://",
"broadcast": false,
"participantLid": null,
"referenceMessageId": null,
"externalAdReply": null,
"forwarded": false,
"type": "ReceivedCallback",
"notification": "CALL_MISSED",
"notificationParameters": [],
"callId": "F44E0E2011E7C784BB9A4AC11749C436",
"code": null,
"callDirection": "incoming",
"isVideo": true
}
```
### Grupos
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"isGroup": true,
"isNewsletter": false,
"instanceId": "A20DA9C0183A2D35A260F53F5D2B9244",
"messageId": "A20DA9C0183A2D35A260F53F5D2B9244",
"phone": "5544999999999-group",
"connectedPhone": "5544999999999",
"fromMe": false,
"momment": 1682017970000,
"status": "RECEIVED",
"type": "ReceivedCallback",
"notification": "MEMBERSHIP_APPROVAL_REQUEST",
"notificationParameters": ["5544999999999"],
"requestMethod": "invite_link"
}
```
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"isGroup": true,
"isNewsletter": false,
"instanceId": "A20DA9C0183A2D35A260F53F5D2B9244",
"messageId": "A20DA9C0183A2D35A260F53F5D2B9244",
"phone": "5544999999999-group",
"connectedPhone": "5544999999999",
"fromMe": false,
"momment": 1682017970000,
"status": "RECEIVED",
"type": "ReceivedCallback",
"notification": "REVOKED_MEMBERSHIP_REQUESTS",
"notificationParameters": ["5544999999999"]
}
```
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"isGroup": true,
"isNewsletter": false,
"instanceId": "A20DA9C0183A2D35A260F53F5D2B9244",
"messageId": "A20DA9C0183A2D35A260F53F5D2B9244",
"phone": "5544999999999-group",
"connectedPhone": "5544999999999",
"fromMe": false,
"momment": 1682017970000,
"status": "RECEIVED",
"type": "ReceivedCallback",
"notification": "MEMBERSHIP_APPROVAL_REQUEST",
"notificationParameters": ["5544999999999", "5544888888888"],
"requestMethod": "non_admin_add"
}
```
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"chatLid": null,
"isGroup": true,
"isNewsletter": false,
"instanceId": "A20DA9C0183A2D35A260F53F5D2B9244",
"messageId": "A20DA9C0183A2D35A260F53F5D2B9244",
"phone": "5544999999999-group",
"connectedPhone": "5544999999999",
"fromMe": false,
"fromApi": false,
"momment": 1682017970000,
"expiresAt": null,
"status": "RECEIVED",
"chatName": "GROUP NAME",
"senderPhoto": null,
"senderName": "",
"photo": null,
"broadcast": false,
"participantPhone": null,
"participantLid": null,
"referenceMessageId": null,
"externalAdReply": null,
"forwarded": false,
"type": "ReceivedCallback",
"notification": "GROUP_SUSPENDED",
"notificationParameters": [],
"callId": null,
"code": null,
}
```
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"chatLid": null,
"isGroup": true,
"isNewsletter": false,
"instanceId": "A20DA9C0183A2D35A260F53F5D2B9244",
"messageId": "A20DA9C0183A2D35A260F53F5D2B9244",
"phone": "5544999999999-group",
"connectedPhone": "5544999999999",
"fromMe": false,
"fromApi": false,
"momment": 1682017970000,
"expiresAt": null,
"status": "RECEIVED",
"chatName": "GROUP NAME",
"senderPhoto": null,
"senderName": "",
"photo": null,
"broadcast": false,
"participantPhone": null,
"participantLid": null,
"referenceMessageId": null,
"externalAdReply": null,
"forwarded": false,
"type": "ReceivedCallback",
"notification": "GROUP_UNSUSPENDED",
"notificationParameters": [],
"callId": null,
"code": null,
}
```
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"chatLid": null,
"isGroup": true,
"isNewsletter": false,
"instanceId": "A20DA9C0183A2D35A260F53F5D2B9244",
"messageId": "1915651218",
"phone": "5544999999999-group",
"connectedPhone": "5544999999999",
"fromMe": false,
"fromApi": false,
"momment": 1790685207000,
"expiresAt": null,
"status": "RECEIVED",
"chatName": "GROUP NAME",
"senderPhoto": "https://pps.whatsapp.net/PHOTO_URL",
"senderName": "SENDER NAME",
"photo": null,
"broadcast": false,
"participantPhone": "5544999999999",
"participantLid": "9999999999999@lid",
"referenceMessageId": null,
"externalAdReply": null,
"forwarded": false,
"type": "ReceivedCallback",
"notification": "GROUP_GROWTH_LOCKED",
"notificationParameters": [],
"growthLockExpiration": 1790771200,
"callId": null,
"code": null
}
```
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"chatLid": null,
"isGroup": true,
"isNewsletter": false,
"instanceId": "A20DA9C0183A2D35A260F53F5D2B9244",
"messageId": "1915651218",
"phone": "5544999999999-group",
"connectedPhone": "5544999999999",
"fromMe": false,
"fromApi": false,
"momment": 1790685207000,
"expiresAt": null,
"status": "RECEIVED",
"chatName": "GROUP NAME",
"senderPhoto": "https://pps.whatsapp.net/PHOTO_URL",
"senderName": "SENDER NAME",
"photo": null,
"broadcast": false,
"participantPhone": "5544999999999",
"participantLid": "9999999999999@lid",
"referenceMessageId": null,
"externalAdReply": null,
"forwarded": false,
"type": "ReceivedCallback",
"notification": "GROUP_GROWTH_UNLOCKED",
"notificationParameters": [],
"growthLockExpiration": 0,
"callId": null,
"code": null
}
```
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"chatLid": null,
"isGroup": true,
"isNewsletter": false,
"instanceId": "A20DA9C0183A2D35A260F53F5D2B9244",
"messageId": "1915651218",
"phone": "5544999999999-group",
"connectedPhone": "5544999999999",
"fromMe": false,
"fromApi": false,
"momment": 1790685207000,
"expiresAt": null,
"status": "RECEIVED",
"chatName": "GROUP NAME",
"senderPhoto": "https://pps.whatsapp.net/PHOTO_URL",
"senderName": "SENDER NAME",
"photo": null,
"broadcast": false,
"participantPhone": "5544999999999",
"participantLid": "9999999999999@lid",
"referenceMessageId": null,
"externalAdReply": null,
"forwarded": false,
"type": "ReceivedCallback",
"notification": "GROUP_CHANGE_INVITE_LINK",
"notificationParameters": [],
"invitationCode": "AbCdEfGhIjK1234567890L",
"invitationLink": "https://chat.whatsapp.com/AbCdEfGhIjK1234567890L",
"callId": null,
"code": null
}
```
### Comunidades
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"isGroup": true,
"instanceId": "YOUR_INSTANCE_ID",
"messageId": "3EB0...",
"phone": "120363XXXXXXXXXXX-group",
"connectedPhone": "5544XXXXXXXXX",
"fromMe": false,
"fromApi": true,
"momment": 199999999,
"status": "RECEIVED",
"chatName": "Announcement Group Name",
"senderName": "Author's Name",
"participantPhone": "5544XXXXXXXXX",
"participantLid": "XXXXXXXXXXXXXXX@lid",
"type": "ReceivedCallback",
"notification": "REVOKE",
"notificationParameters": ["ANNOUNCEMENT_GUARD"]
}
```
### Canais
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"isStatusReply": false,
"senderLid": "81896604192873@lid",
"connectedPhone": "554499999999",
"waitingMessage": false,
"isEdit": false,
"isGroup": false,
"isNewsletter": false,
"instanceId": "A20DA9C0183A2D35A260F53F5D2B9244",
"messageId": "A20DA9C0183A2D35A260F53F5D2B9244",
"phone": "5544999999999",
"fromMe": false,
"momment": 1632228925000,
"status": "RECEIVED",
"chatName": "name",
"senderPhoto": "https://",
"senderName": "name",
"participantPhone": null,
"participantLid": null,
"photo": "https://",
"broadcast": false,
"type": "ReceivedCallback",
"newsletterAdminInvite": {
"newsletterId": "120363166555745933@newsletter",
"newsletterName": "Teste",
"text": "Quero convidar você para ser admin do meu canal",
"inviteExpiration": 1706809668
}
}
```
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"isStatusReply": false,
"senderLid": "81896604192873@lid",
"connectedPhone": "554499999999",
"waitingMessage": false,
"isEdit": false,
"isGroup": false,
"isNewsletter": false,
"instanceId": "A20DA9C0183A2D35A260F53F5D2B9244",
"messageId": "464201093",
"phone": "5544999999999@newsletter",
"fromMe": false,
"momment": 1682017970000,
"status": "RECEIVED",
"chatName": "name",
"senderPhoto": "https://",
"senderName": "name",
"photo": "https://",
"broadcast": false,
"type": "ReceivedCallback",
"notification": "NEWSLETTER_ADMIN_PROMOTE",
"notificationParameters": ["5544999999999", "ADMIN"]
}
```
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"isStatusReply": false,
"senderLid": "81896604192873@lid",
"connectedPhone": "554499999999",
"waitingMessage": false,
"isEdit": false,
"isGroup": false,
"isNewsletter": false,
"instanceId": "A20DA9C0183A2D35A260F53F5D2B9244",
"messageId": "464201093",
"phone": "5544999999999@newsletter",
"fromMe": false,
"momment": 1682017970000,
"status": "RECEIVED",
"chatName": "name",
"senderPhoto": "https://",
"senderName": "name",
"photo": "https://",
"broadcast": false,
"type": "ReceivedCallback",
"notification": "NEWSLETTER_ADMIN_DEMOTE",
"notificationParameters": ["5544999999999", "SUBSCRIBER"]
}
```
### Perfil
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"isGroup": false,
"isNewsletter": false,
"instanceId": "A20DA9C0183A2D35A260F53F5D2B9244",
"phone": "5544999999999",
"connectedPhone": "5544999999999",
"fromMe": true,
"momment": 1736797729000,
"status": "RECEIVED",
"type": "ReceivedCallback",
"notification": "PROFILE_NAME_UPDATED",
"profileName": "nome atualizado"
}
```
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"isGroup": false,
"isNewsletter": false,
"instanceId": "A20DA9C0183A2D35A260F53F5D2B9244",
"phone": "5544999999999",
"connectedPhone": "5544999999999",
"fromMe": true,
"momment": 1736797729000,
"status": "RECEIVED",
"type": "ReceivedCallback",
"notification": "PROFILE_PICTURE_UPDATED",
"updatedPhoto": "https://"
}
```
### Chats
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"isGroup": false,
"isNewsletter": false,
"instanceId": "A20DA9C0183A2D35A260F53F5D2B9244",
"phone": "5544999999999",
"connectedPhone": "5544999999999",
"fromMe": true,
"momment": 1736797729000,
"status": "RECEIVED",
"type": "ReceivedCallback",
"notification": "CHAT_LABEL_ASSOCIATION",
"notificationParameters": [
{
"phone": "5544977777777",
"label": "1",
"assigned": true
},
{
"phone": "5544988888888",
"label": "2",
"assigned": false
}
]
}
```
## Tipos de notificações
### Conceituação
As notificações são eventos enviados via webhook que indicam mudanças ou ações no WhatsApp, como chamadas, interações em grupos e atualizações de conta.
Esses eventos podem ser identificados pelo atributo `notification` presente no payload.
Abaixo estão listados os tipos de notificações e seus significados.
### Notificações (eventos via webhook)
Grupo foi criado
Nome do grupo foi alterado
Descrição do grupo foi alterada
Foto do grupo foi alterada
Link de convite do grupo foi redefinido. Os campos `invitationCode` e `invitationLink` trazem o novo link
Participante foi promovido a administrador
Participante foi removido da função de administrador
Participante saiu do grupo
Participante foi adicionado ao grupo
Participante foi removido do grupo
Participante aceitou o link de convite e entrou no grupo
Grupo foi suspenso
Suspensão do grupo foi removida
Link de convite do grupo foi suspenso. O campo `growthLockExpiration` traz o timestamp de expiração da suspensão
Suspensão do link de convite do grupo foi removida. O campo `growthLockExpiration` vem como `0`
Chamada de voz perdida
Chamada de vídeo perdida
Mensagem informando criptografia de ponta a ponta
Mensagem protegida por criptografia
Conta comercial não verificada pelo WhatsApp
Conta comercial verificada pelo WhatsApp
Conta comercial alterada para conta pessoal
Mensagem apagada
Envio do código de confirmação para registro do número
***
# Ao enviar
Source: https://developer.z-api.io/webhooks/on-message-send
PUT /instances/{instanceId}/token/{token}/update-webhook-delivery
Webhook de retorno de mensagens enviadas
## Conceituação
Esse é o webhook de retorno de mensagens enviadas.
O Z-API não aceita webhooks que não sejam **HTTPS**.
***
## Atualizar webhook
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Body
URL do webhook de delivery
### Request Body
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"value": "https://endereco-do-seu-sistema.com.br/instancia/SUA_INSTANCIA/delivery"
}
```
***
### Retorno do webhook
### Atributos do retorno
Número de telefone de destino da mensagem
Identificador da mensagem na conversa
Identificador da mensagem no WhatsApp
Identificador da instância
Momento em que o evento foi disparado (timestamp em milissegundos)
Tipo do evento da instância, nesse caso será `DeliveryCallback`
Presente **apenas em casos de erro**. Contém a descrição do erro ocorrido no envio da mensagem. Confira a lista completa de erros possíveis nos [Exemplos de retorno de Ao enviar](/webhooks/on-message-send-examples)
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"phone": "554499999999",
"zaapId": "A20DA9C0183A2D35A260F53F5D2B9244",
"messageId": "A20DA9C0183A2D35A260F53F5D2B9244",
"instanceId": "instance.id",
"momment": 1777494009341,
"type": "DeliveryCallback"
}
```
***
## Response
### 200
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"value": true
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou PUT conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Exemplos de retorno de Ao enviar
Source: https://developer.z-api.io/webhooks/on-message-send-examples
Exemplos de retorno do webhook de confirmação de envio de mensagens (DeliveryCallback)
## Retorno do webhook
### Atributos do retorno
Todos os retornos do webhook **Ao enviar** possuem os seguintes atributos:
Número de telefone de destino da mensagem
Identificador da mensagem no WhatsApp
Identificador da mensagem na conversa
Identificador da instância
Momento em que o evento foi disparado (timestamp em milissegundos)
Tipo do evento da instância, nesse caso será sempre `DeliveryCallback`
Presente **apenas em casos de erro**. Contém a descrição do erro ocorrido no envio da mensagem
Código identificador do erro. Presente **apenas em casos específicos de erro**.
Atualmente enviado somente quando o erro for relacionado a restrição temporária de envio de mensagens (shadow ban), com o valor `"SHADOW_BAN"`
***
## Exemplos de retorno
### Sucesso
Quando a mensagem é enviada com sucesso, o retorno **não contém** o campo `error`:
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"phone": "554499999999",
"messageId": "A800FB3697F1DE58C48D",
"instanceId": "instance.id",
"zaapId": "A20DA9C0183A2D35A260F53F5D2B9244",
"momment": 1777494009341,
"type": "DeliveryCallback"
}
```
### Erro
Quando ocorre um erro no envio, o retorno inclui o campo `error` com a descrição do problema:
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"phone": "554499999999",
"messageId": "A20DA9C0183A2D35A260F53F5D2B9244",
"error": "Phone number does not exist",
"instanceId": "instance.id",
"zaapId": "A20DA9C0183A2D35A260F53F5D2B9244",
"momment": 1777494091684,
"type": "DeliveryCallback"
}
```
Não é possível filtrar os eventos recebidos pelo webhook. Todos os eventos de envio — sejam de sucesso ou erro — são disparados juntos, sem distinção de tipo no disparo. O tratamento deve ser feito na sua aplicação verificando a presença ou ausência do campo `error` no payload recebido.
***
## Erros possíveis no campo `error`
### Permissão e Restrições do WhatsApp
O WhatsApp bloqueou o envio desta mensagem por restrições de permissão.
O WhatsApp rejeitou o envio. Isso pode ocorrer por restrições na conta, como shadow ban ou limitações para iniciar conversas.
O WhatsApp não permitiu o envio desta mensagem.
O número provavelmente está com uma restrição temporária de envio de mensagens (shadow ban).
Quando este erro ocorre, o campo `errorCode` é enviado com o valor `"SHADOW_BAN"`
Sua conta não tem autorização para enviar esta mensagem.
Você não tem permissão para enviar mensagens neste grupo.
Você não consegue enviar mensagem neste grupo pois ele foi suspenso.
Quando este erro ocorre, o campo `errorCode` é enviado com o valor `"GROUP_SUSPENDED"`
Este tipo de mensagem só pode ser enviado em grupos, não em conversas privadas.
É necessário aceitar os termos de uso de mensagens com botões no painel antes de enviar.
### Timeout e Conexão
O tempo para enviar a mensagem expirou. Isso pode acontecer por instabilidade na conexão com o WhatsApp.
Ocorreu um erro de conexão no sistema ao tentar enviar a mensagem.
### Número de Telefone Inválido
O número de telefone informado não existe no WhatsApp.
O número de telefone está em um formato inválido. Verifique e tente novamente.
### Mídia e URL
A URL da mídia (imagem, vídeo, áudio ou documento) é inválida ou está inacessível.
A URL da mídia não foi encontrada (erro 404). Verifique se o link está correto.
A URL informada não aponta para um arquivo de mídia. O link retorna uma página web em vez de um arquivo.
O formato do arquivo de sticker não é suportado. O WhatsApp aceita apenas imagens como sticker.
### Edição e Tempo Limite de Mensagens
Não é possível editar uma mensagem enviada há mais de 7 dias. O WhatsApp só permite edições dentro desse prazo.
Não é possível comentar em uma mensagem enviada há mais de 7 dias.
### Produtos e Catálogo
O ID do produto informado não foi encontrado. Verifique se o produto existe no seu catálogo.
O catálogo informado não foi encontrado. Verifique se o catálogo está configurado corretamente.
O número usado para buscar o produto no catálogo não pode ser um identificador temporário. Use o número real do telefone.
### Pedidos (Orders)
O código da moeda informado no pedido é inválido. Verifique se está usando um código de moeda válido (ex: BRL, USD).
Os dados enviados para atualizar o pedido estão inválidos. Verifique as informações e tente novamente.
### Eventos e Newsletter
Não foi possível enviar o voto na enquete porque o identificador da enquete está faltando.
Mensagens de evento só podem ser enviadas em grupos, não em conversas privadas.
A data e hora informadas para o evento são inválidas. Verifique o formato e tente novamente.
### Status e Respostas
A mensagem de status original que você tentou responder não foi encontrada.
### Encaminhamento
A mensagem que você tentou encaminhar não foi encontrada. Ela pode ter sido deletada.
### Conversão e Parâmetros
Ocorreu um erro ao converter a mensagem para o formato compatível com o WhatsApp.
Os parâmetros enviados na requisição estão inválidos. Verifique os dados e tente novamente.
### Tipos de Mensagem Não Suportados em Canais (Newsletters)
Não é possível modificar configurações de chat em canais.
Não é possível fazer chamadas para canais.
Não é possível enviar chamadas com áudio para canais.
Não é possível enviar documentos para canais.
Não é possível enviar respostas de botões para canais.
Não é possível enviar vídeos PTV para canais.
Não é possível enviar localização para canais.
Não é possível enviar contatos para canais.
Não é possível enviar botões de ação para canais.
Não é possível enviar mensagens com botões para canais.
Não é possível enviar botões com link para canais.
Não é possível enviar listas de opções para canais.
Não é possível enviar solicitações de pagamento para canais.
Não é possível configurar expiração de chat em canais.
Não é possível fixar mensagens em canais.
Não é possível enviar botões de Pix para canais.
### Falha no Processamento da Fila
A mensagem foi recebida pelo sistema, mas ocorreu uma falha no processamento interno de enfileiramento. A mensagem não foi adicionada à fila de envio.
# Ao conectar
Source: https://developer.z-api.io/webhooks/on-webhook-connected
PUT /instances/{instanceId}/token/{token}/update-webhook-connected
Webhook de retorno de conexão do celular com o Z-API
## Conceituação
Esse é o webhook de retorno de conexão do celular com o Z-API. É acionado quando o Z-API se conecta ao WhatsApp — durante a leitura do QR code, reinício da instância, etc.
O Z-API não aceita webhooks que não sejam **HTTPS**.
***
## Atualizar webhook
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Body
URL do webhook de conexão
### Request Body
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"value": "https://endereco-do-seu-sistema.com.br/instancia/SUA_INSTANCIA/connected"
}
```
***
## Retorno do webhook
Tipo do evento: `ConnectedCallback`
Status de conexão da instância
Número de telefone conectado
Timestamp da conexão
Identificador da instância
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"type": "ConnectedCallback",
"connected": true,
"momment": 26151515154,
"instanceId": "instance.id",
"phone": "5544999999999"
}
```
***
## Response
### 200
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"value": true
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou PUT conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Ao desconectar
Source: https://developer.z-api.io/webhooks/on-whatsapp-disconnected
PUT /instances/{instanceId}/token/{token}/update-webhook-disconnected
Webhook de resposta de desconexão
## Conceituação
Esse é o webhook de resposta de desconexão.
O Z-API não aceita webhooks que não sejam **HTTPS**.
***
## Atualizar webhook
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Body
URL do webhook de desconexão
### Request Body
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"value": "https://endereco-do-seu-sistema.com.br/instancia/SUA_INSTANCIA/disconnected"
}
```
***
## Retorno do webhook
Timestamp do momento da desconexão
Descrição do erro que causou a desconexão
Indicador de status de conexão
Tipo do evento: `DisconnectedCallback`
Identificador da instância
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"momment": 1580163342,
"error": "Device has been disconnected",
"disconnected": true,
"type": "DisconnectedCallback",
"instanceId": "instance.id"
}
```
***
## Response
### 200
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"value": true
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou PUT conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Status da mensagem
Source: https://developer.z-api.io/webhooks/on-whatsapp-message-status-changes
PUT /instances/{instanceId}/token/{token}/update-webhook-message-status
Webhook de retorno do status da mensagem
## Conceituação
Esse é o webhook de retorno do status da mensagem.
O Z-API não aceita webhooks que não sejam **HTTPS**.
***
## Atualizar webhook
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Body
URL do webhook de status da mensagem
### Request Body
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"value": "https://endereco-do-seu-sistema.com.br/instancia/SUA_INSTANCIA/status"
}
```
***
## Retorno do webhook
Identificador da instância
Status da mensagem: `SENT`, `RECEIVED`, `READ`, `READ_BY_ME` ou `PLAYED`
Identificador(es) da mensagem
Timestamp do evento
Tipo do dispositivo (0 = mobile)
Número de telefone de destino
Tipo do evento: `MessageStatusCallback`
Indica se o chat é um grupo
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"instanceId": "instance.id",
"status": "SENT",
"ids": ["999999999999999999999"],
"momment": 1632234645000,
"phoneDevice": 0,
"phone": "5544999999999",
"type": "MessageStatusCallback",
"isGroup": false
}
```
***
## Response
### 200
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"value": true
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou PUT conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Atualizar todos webhooks
Source: https://developer.z-api.io/webhooks/update-every-webhooks
PUT /instances/{instanceId}/token/{token}/update-every-webhooks
Atualiza todos os webhooks para a mesma URL de uma só vez
## Conceituação
Esse endpoint serve para você que deseja alterar todos os webhooks para a mesma URL de uma só vez.
O Z-API não aceita webhooks que não sejam **HTTPS**.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Obrigatórios
URL do webhook
### Opcionais
Habilita notificações de webhook para mensagens recebidas e enviadas por mim
***
## Request Body
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"value": "https://endereco-do-seu-sistema.com.br/instancia/SUA_INSTANCIA/webhook",
"notifySentByMe": true
}
```
***
## Response
### 200
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"value": true
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou PUT conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Filtros de webhook
Source: https://developer.z-api.io/webhooks/update-filters
PUT /instances/{instanceId}/token/{token}/update-filters
Configure quais tipos de mensagem e webhooks você deseja receber
## Conceituação
O endpoint de filtros permite configurar quais eventos e tipos de mensagem serão disparados pelos webhooks da sua instância. É possível:
* Filtrar **tipos de mensagem** recebidas no webhook de [Ao receber](/webhooks/on-message-received) (ex: ignorar mensagens de grupos ou apenas de áudio)
* Filtrar **tipos de webhook** que serão disparados (ex: desativar o webhook de [Status do chat](/webhooks/on-chat-presence) sem remover a URL configurada)
As mesmas configurações também podem ser feitas diretamente pelo **painel da instância**, através de botões em cada webhook.
Os filtros de `messageFilters` se aplicam **apenas** ao webhook de [Ao receber](/webhooks/on-message-received). Os demais webhooks não são afetados por esse filtro.
***
## Atualizar filtros
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Body
Lista de filtros de tipo de mensagem. Os tipos incluídos no array **não serão entregues** no webhook de [Ao receber](/webhooks/on-message-received) (ReceivedCallback).
Veja os [valores possíveis](#filtros-por-tipo-de-mensagem) abaixo.
Lista de filtros de tipo de webhook. Os webhooks incluídos no array **não serão disparados**, mesmo que possuam uma URL configurada.
Veja os [valores possíveis](#filtros-por-tipo-de-webhook) abaixo.
### Request Body
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"messageFilters": [
"FILTER_FROM_GROUP",
"FILTER_FROM_PRIVATE_CHAT",
"FILTER_TEXT_MESSAGE",
"FILTER_IMAGE_MESSAGE",
"FILTER_VIDEO_MESSAGE",
"FILTER_AUDIO_MESSAGE",
"FILTER_DOCUMENT_MESSAGE"
],
"callbackTypeFilters": [
"FILTER_DELIVERY_CALLBACK",
"FILTER_DISCONNECTED_CALLBACK",
"FILTER_RECEIVED_CALLBACK",
"FILTER_PRESENCE_CHAT_CALLBACK",
"FILTER_MESSAGE_STATUS_CALLBACK",
"FILTER_CONNECTED_CALLBACK"
]
}
```
***
## Tipos de filtro para webhooks
### Filtros por tipo de mensagem
Aplicam-se ao webhook de [Ao receber](/webhooks/on-message-received) (ReceivedCallback). Mensagens cujo tipo estiver no array `messageFilters` **não serão entregues**.
Filtra mensagens recebidas em **grupos**. Quando ativo, nenhuma mensagem recebida em um grupo será entregue no `ReceivedCallback`.
Filtra mensagens recebidas em **conversas privadas**. Quando ativo, apenas mensagens de recebidas de grupos serão entregues no `ReceivedCallback`.
Filtra mensagens do tipo **texto simples**.
Filtra mensagens do tipo **imagem**.
Filtra mensagens do tipo **vídeo**.
Filtra mensagens do tipo **áudio**.
Filtra mensagens do tipo **documento**.
***
### Filtros por tipo de webhook
Aplicam-se aos webhooks em geral. Webhooks cujo tipo estiver no array `callbackTypeFilters` **não serão disparados**, independentemente de terem uma URL configurada.
Desativa o disparo do webhook **[Ao receber](/webhooks/on-message-received) (ReceivedCallback)**
Desativa o disparo do webhook **[Ao enviar](/webhooks/on-message-send) (DeliveryCallback)**
Desativa o disparo do webhook **[Ao conectar](/webhooks/on-webhook-connected) (ConnectedCallback)**
Desativa o disparo do webhook **[Ao desconectar](/webhooks/on-whatsapp-disconnected) (DisconnectedCallback)**
Desativa o disparo do webhook **[Status do chat](/webhooks/on-chat-presence) (PresenceChatCallback)**
Desativa o disparo do webhook **[Status da mensagem](/webhooks/on-whatsapp-message-status-changes) (MessageStatusCallback)**
***
## Response
### 200
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"value": true
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o PUT conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".
# Atualizar notificar enviadas por mim
Source: https://developer.z-api.io/webhooks/update-notify-sent-by-me
PUT /instances/{instanceId}/token/{token}/update-notify-sent-by-me
Habilita a opção de receber mensagens enviadas por você através do webhook
## Conceituação
Esse endpoint serve para você habilitar a opção de receber mensagens enviadas por você através do webhook.
É necessário configurar um webhook para o evento "Ao receber" para que esta funcionalidade funcione.
***
## Atributos
### Header
ID da sua instância. Disponível no painel Z-API em **Instâncias**.
Token da sua instância Z-API.
### Obrigatórios
Ativar webhook de mensagens recebidas e enviadas por mim
***
## Request Body
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"notifySentByMe": true
}
```
***
## Response
### 200
```json theme={"theme":{"light":"github-light","dark":"poimandres"}}
{
"value": true
}
```
### 405
Neste caso certifique que esteja enviando corretamente a especificação do método, ou seja verifique se você enviou o POST ou PUT conforme especificado no início deste tópico.
### 415
Caso você receba um erro 415, certifique de adicionar na headers da requisição o "Content-Type" do objeto que você está enviando, em sua grande maioria "application/json".