Documentação da API SMARTZAP

Painel de Controle Swagger

SMARTZAP API é uma implementação da biblioteca whatsmeow como um serviço de API RESTful simples com suporte a múltiplos dispositivos e sessões concorrentes.

A biblioteca whatsmeow não utiliza Puppeteer em Chrome headless, nem um emulador Android. Ela se comunica diretamente com os servidores websocket do WhatsApp, sendo bastante rápida e utilizando menos memória e CPU que outras soluções. A desvantagem é que uma mudança no protocolo do WhatsApp poderia quebrar as conexões e exigiria uma atualização da biblioteca.

⚠️ Atenção: Usar este software violando os Termos de Serviço do WhatsApp pode resultar no banimento do seu número. Tenha muito cuidado, não use para enviar SPAM ou algo semelhante. Use por sua conta e risco. Se você precisa desenvolver algo com interesse comercial, entre em contato com um provedor global de soluções WhatsApp e inscreva-se no serviço WhatsApp Business API.

Autenticação

A SMARTZAP API oferece dois métodos de autenticação:

Para usuários normais: Use o cabeçalho token que será correspondido com a tabela 'users' no banco de dados.
Para administradores: Use o cabeçalho Authorization com o token administrativo para acessar rotas protegidas de administração.

Exemplo de requisição com token de usuário:

curl -X POST https://seu-dominio.com/webhook \
  -H "token: seu_token_aqui" \
  -H "Content-Type: application/json" \
  -d '{ "webhook": "https://seu-webhook.com/callback", "events": ["Message", "ReadReceipt"] }'

Primeiros Passos

Para começar a usar a API SMARTZAP, siga estes passos:

Crie um usuário:
Você precisa criar um usuário no banco de dados. O administrador pode criar um novo usuário através da rota /admin/users.
Conecte ao WhatsApp:
Use o endpoint /session/connect para iniciar uma conexão com os servidores do WhatsApp.
Escaneie o código QR:
Obtenha o código QR através do endpoint /session/qr e escaneie-o com seu aplicativo WhatsApp.
Configure seu Webhook:
Use o endpoint /webhook para configurar a URL do seu webhook e os tipos de eventos que deseja receber.
Envie mensagens:
Agora você está pronto para enviar mensagens usando os diversos endpoints disponíveis em /chat/send/*.

Dica: Para testar, você pode usar o dashboard disponível em /dashboard para gerenciar suas instâncias e visualizar o código QR para conexão.

Session

Endpoints para gerenciar a conexão com os servidores do WhatsApp.

POST /session/connect

Conecta aos servidores do WhatsApp. Se não houver sessão prévia, será necessário escanear um código QR.

Parâmetros do Corpo:

Parâmetro	Tipo	Descrição
Subscribe	Array[string]	Lista de tipos de eventos para inscrição. Valores possíveis: "Message", "ReadReceipt", "Presence", "HistorySync", "ChatPresence", "All"
Immediate	boolean	Se true, retorna imediatamente sem esperar pela confirmação da conexão

Exemplo de Requisição:

{
  "Subscribe": ["Message", "ReadReceipt"],
  "Immediate": true
}

Resposta:

{
  "code": 200,
  "data": {
    "details": "Connected!",
    "events": "Message,ReadReceipt",
    "jid": "5491155555555.0:53@s.whatsapp.net",
    "webhook": "https://some.site/webhook?request=parameter"
  },
  "success": true
}

POST /session/disconnect

Desconecta dos servidores do WhatsApp sem encerrar a sessão.

Resposta:

{
  "code": 200,
  "data": {
    "Details": "Disconnected"
  },
  "success": true
}

POST /session/logout

Encerra a conexão e termina a sessão, sendo necessário escanear o QR novamente na próxima conexão.

Resposta:

{
  "code": 200,
  "data": {
    "Details": "Logged out"
  },
  "success": true
}

GET /session/status

Obtém o status atual da conexão e da sessão.

Resposta:

{
  "code": 200,
  "data": {
    "Connected": true,
    "LoggedIn": true
  },
  "success": true
}

GET /session/qr

Obtém o código QR para escaneamento no aplicativo WhatsApp.

Resposta:

{
  "code": 200,
  "data": {
    "QRCode": "data:image/png;base64,iVBORw0KGgoA..."
  },
  "success": true
}

GET /session/info

Obtém informações detalhadas sobre a sessão, incluindo status da conexão, informações do perfil e configurações.

Resposta:

{
  "code": 200,
  "data": [
    {
      "id": "user-id",
      "name": "User Name",
      "token": "user-token",
      "jid": "5511999999999@s.whatsapp.net",
      "connected": true,
      "loggedIn": true,
      "pushName": "Push Name",
      "status": "User Status",
      "pictureURL": "https://profile.pic/url",
      "pictureID": "picture-id",
      "pictureBase64": "data:image/jpeg;base64,வைக்",
      "webhook": "https://your.webhook/url",
      "events": "Message,ReadReceipt",
      "proxyURL": "socks5://user:pass@host:port",
      "qrcode": "",
      "s3Config": {
        "enabled": true,
        "endpoint": "https://s3.amazonaws.com",
        "region": "us-east-1",
        "bucket": "my-bucket",
        "accessKey": "***",
        "pathStyle": false,
        "publicURL": "https://cdn.example.com",
        "mediaDelivery": "both",
        "retentionDays": 30
      },
      "proxyConfig": {
        "enabled": true,
        "proxyURL": "socks5://user:pass@host:port"
      }
    }
  ],
  "success": true
}

POST /session/pairphone

Obtém o código para parear por número de telefone em vez de QR code.

Parâmetros do Corpo:

Parâmetro	Tipo	Descrição
Phone	string	Número de telefone para parear

Exemplo de Requisição:

{
  "Phone": "5511999999999"
}

Resposta:

{
  "code": 200,
  "data": {
    "LinkingCode": "ABC-123"
  },
  "success": true
}

GET /session/history

Solicita a sincronização do histórico de mensagens.

Resposta:

{
  "code": 200,
  "data": {
    "Details": "History sync request Sent",
    "Timestamp": 1679686148
  },
  "success": true
}

POST /session/proxy

Define a configuração de proxy para a sessão.

Parâmetros do Corpo:

Parâmetro	Tipo	Descrição
proxy_url	string	URL do proxy (ex: "socks5://user:pass@host:port" ou "http://host:port")
enable	boolean	Ativar ou desativar o proxy

Exemplo de Requisição:

{
  "proxy_url": "socks5://user:pass@host:port",
  "enable": true
}

Resposta:

{
  "code": 200,
  "data": {
    "Details": "Proxy configured successfully",
    "ProxyURL": "socks5://user:pass@host:port"
  },
  "success": true
}

POST /session/s3/config

Configura o armazenamento S3 para a sessão.

Parâmetros do Corpo:

Parâmetro	Tipo	Descrição
enabled	boolean	Ativar ou desativar o S3
endpoint	string	Endpoint do S3
region	string	Região do S3
bucket	string	Bucket do S3
access_key	string	Chave de acesso do S3
secret_key	string	Chave secreta do S3
path_style	boolean	Usar estilo de caminho
public_url	string	URL pública para os arquivos
media_delivery	string	Método de entrega de mídia ("base64", "s3", ou "both")
retention_days	integer	Dias para retenção dos arquivos

Resposta:

{
  "code": 200,
  "data": {
    "Details": "S3 configuration saved successfully",
    "Enabled": true
  },
  "success": true
}

GET /session/s3/config

Obtém a configuração S3 da sessão.

Resposta:

{
  "code": 200,
  "data": {
    "enabled": true,
    "endpoint": "https://s3.amazonaws.com",
    "region": "us-east-1",
    "bucket": "my-bucket",
    "access_key": "***",
    "path_style": false,
    "public_url": "",
    "media_delivery": "both",
    "retention_days": 30
  },
  "success": true
}

DELETE /session/s3/config

Deleta a configuração S3 da sessão.

Resposta:

{
  "code": 200,
  "data": {
    "Details": "S3 configuration deleted successfully"
  },
  "success": true
}

POST /session/s3/test

Testa a conexão com o S3.

Resposta:

{
  "code": 200,
  "data": {
    "Details": "S3 connection test successful",
    "Bucket": "my-bucket",
    "Region": "us-east-1"
  },
  "success": true
}

Webhook

Endpoints para configurar webhooks que receberão notificações de eventos.

GET /webhook

Obtém o webhook configurado e eventos inscritos.

Resposta:

{
  "code": 200,
  "data": {
    "subscribe": ["Message", "ReadReceipt"],
    "webhook": "https://example.net/webhook"
  },
  "success": true
}

POST /webhook

Configura um webhook para receber eventos.

Parâmetros do Corpo:

Parâmetro	Tipo	Descrição
webhook	string	URL do webhook que receberá as chamadas
events	Array[string]	Lista de tipos de eventos para inscrição. Consulte a seção Estrutura de Webhook para a lista completa.
active	boolean	Define se o webhook está ativo ou não. Padrão: true

Exemplo de Requisição:

{
  "webhook": "https://example.net/webhook",
  "events": ["Message", "ReadReceipt"]
}

Resposta:

{
  "code": 200,
  "data": {
    "webhook": "https://example.net/webhook",
    "events": ["Message", "ReadReceipt"]
  },
  "success": true
}

PUT /webhook

Atualiza a configuração do webhook. Pode atualizar apenas a URL, apenas os eventos, ou ambos.

Parâmetros do Corpo:

Parâmetro	Tipo	Descrição
webhook	string	Nova URL do webhook (opcional se apenas atualizando eventos)
events	Array[string]	Nova lista de eventos (opcional se apenas atualizando URL)
active	boolean	Ativar ou desativar o webhook

Exemplos de Requisição:

// Atualizar apenas eventos
{
  "events": ["Message", "Receipt", "GroupInfo"],
  "active": true
}

// Atualizar apenas URL
{
  "webhook": "https://novo-endpoint.com/webhook",
  "active": true
}

// Desativar webhook
{
  "active": false
}

DELETE /webhook

Remove o webhook e limpa a configuração de eventos.

Resposta:

{
  "code": 200,
  "data": {
    "message": "Webhook removed successfully"
  },
  "success": true
}

Chat

Endpoints para enviar mensagens e gerenciar interações de chat.

POST /chat/send/text

Envia uma mensagem de texto para um contato ou grupo, com suporte a respostas e menções.

Funcionalidades Principais

1. Envio para Contato Privado:

Para enviar uma mensagem simples para um número de telefone.

{
  "Phone": "5511999998888",
  "Body": "Olá! Esta é uma mensagem de teste."
}

2. Citar/Responder uma Mensagem:

Para responder a uma mensagem específica (funciona em privado e em grupo), use o objeto ContextInfo. Você obtém os valores de StanzaId e Participant do webhook da mensagem original.

{
  "Phone": "5511999998888",
  "Body": "Entendido, obrigado!",
  "ContextInfo": {
    "StanzaId": "ID_DA_MENSAGEM_ORIGINAL",
    "Participant": "JID_DO_AUTOR_ORIGINAL@s.whatsapp.net"
  }
}

3. Funcionalidades de Grupo:

As funcionalidades abaixo são exclusivas para grupos (o Phone deve terminar com @g.us).

Menção Individual: Para mencionar um ou mais usuários, adicione seus JIDs no array MentionedJID dentro de ContextInfo.
Mencionar Todos: Para mencionar todos os participantes, simplesmente adicione "mentionAll": true.

// Exemplo de Menção Individual
{
  "Phone": "ID_DO_GRUPO@g.us",
  "Body": "Olá @5511987654321, por favor verifique isso.",
  "ContextInfo": {
    "MentionedJID": ["5511987654321@s.whatsapp.net"]
  }
}

// Exemplo de Mencionar Todos
{
  "Phone": "ID_DO_GRUPO@g.us",
  "Body": "Atenção todos! Anúncio importante!",
  "mentionAll": true
}

Parâmetros do Corpo:

Parâmetro	Tipo	Descrição
Phone	string	Número do destinatário ou JID do grupo.
Body	string	Conteúdo da mensagem de texto.
Id	string	ID personalizado para a mensagem (opcional).
ContextInfo	object	Usado para responder a mensagens ou para menções individuais.
mentionAll	boolean	Se `true`, menciona todos no grupo (apenas para grupos).
Delay	integer	Atraso em milissegundos para simular digitação.
PresenceState	string	Define a presença como "composing" (digitando).

Resposta Padrão de Sucesso:

{
  "code": 200,
  "data": {
    "Details": "Sent",
    "Id": "ID_DA_MENSAGEM_ENVIADA",
    "Timestamp": "1679686148"
  },
  "success": true
}

POST /chat/send/image

Envia uma imagem para um contato ou grupo, com suporte a legenda, respostas e menções.

Funcionalidades

1. Envio de Imagem Privado:

{
  "Phone": "5511999998888",
  "Image": "data:image/jpeg;base64,iVBORw0KGgo...",
  "Caption": "Minha foto de teste."
}

2. Responder com Imagem:

Para responder a uma mensagem específica com uma imagem, use o ContextInfo.

{
  "Phone": "5511999998888",
  "Image": "data:image/jpeg;base64,iVBORw0KGgo...",
  "Caption": "Respondendo com imagem.",
  "ContextInfo": {
    "StanzaId": "ID_DA_MENSAGEM_ORIGINAL",
    "Participant": "JID_DO_AUTOR_ORIGINAL@s.whatsapp.net"
  }
}

3. Menções em Grupo com Imagem:

As menções são feitas na legenda da imagem.

Menção Individual: Use o array MentionedJID.
Mencionar Todos: Use o parâmetro "mentionAll": true.

Parâmetros do Corpo:

Parâmetro	Tipo	Descrição
Phone	string	Número do destinatário ou JID do grupo.
Image	string	Imagem em formato base64 (data:image/jpeg;base64,...).
Caption	string	Legenda opcional para a imagem.
Id	string	ID personalizado para a mensagem (opcional).
ContextInfo	object	Usado para responder a mensagens ou para menções individuais.
mentionAll	boolean	Se `true`, menciona todos no grupo (apenas para grupos).

Exemplo de Requisição (Menção Individual na Legenda):

{
  "Phone": "ID_DO_GRUPO@g.us",
  "Image": "data:image/jpeg;base64,iVBORw0KGgo...",
  "Caption": "Olá @5511987654321, veja isso!",
  "ContextInfo": {
    "MentionedJID": ["5511987654321@s.whatsapp.net"]
  }
}

Exemplo de Requisição (Mencionar Todos na Legenda):

{
  "Phone": "ID_DO_GRUPO@g.us",
  "Image": "data:image/jpeg;base64,iVBORw0KGgo...",
  "Caption": "Atenção todos! Nova imagem!",
  "mentionAll": true
}

POST /chat/send/audio

Envia uma mensagem de áudio para um contato ou grupo, com suporte a respostas e menções.

Funcionalidades

1. Envio de Áudio Privado:

{
  "Phone": "5511999998888",
  "Audio": "data:audio/ogg;base64,iVBORw0KGgo..."
}

2. Responder com Áudio:

Para responder a uma mensagem específica com um áudio, use o ContextInfo.

{
  "Phone": "5511999998888",
  "Audio": "data:audio/ogg;base64,iVBORw0KGgo...",
  "ContextInfo": {
    "StanzaId": "ID_DA_MENSAGEM_ORIGINAL",
    "Participant": "JID_DO_AUTOR_ORIGINAL@s.whatsapp.net"
  }
}

3. Menções em Grupo com Áudio:

Para mencionar com áudio, a mensagem não pode ter legenda, então a menção ocorre de forma "invisível" (o usuário recebe a notificação).

Menção Individual: Use o array MentionedJID.
Mencionar Todos: Use o parâmetro "mentionAll": true.

Parâmetros do Corpo:

Parâmetro	Tipo	Descrição
Phone	string	Número do destinatário ou JID do grupo.
Audio	string	Áudio em formato base64 (data:audio/ogg;base64,...).
Id	string	ID personalizado para a mensagem (opcional).
ContextInfo	object	Usado para responder a mensagens ou para menções individuais.
mentionAll	boolean	Se `true`, menciona todos no grupo (apenas para grupos).
Delay	integer	Atraso em milissegundos para simular gravação.
PresenceState	string	Define a presença como "recording" (gravando).

POST /chat/send/document

Envia um documento.

Parâmetros do Corpo:

Phone	string	Número de telefone do destinatário.
Document	string	Documento em formato base64 (data:application/octet-stream;base64,...).
FileName	string	Nome do arquivo.
Id	string	ID personalizado para a mensagem.

POST /chat/send/video

Envia uma mensagem de vídeo para um contato ou grupo, com suporte a legenda, respostas e menções.

Funcionalidades

1. Envio de Vídeo Privado:

{
  "Phone": "5511999998888",
  "Video": "data:video/mp4;base64,iVBORw0KGgo...",
  "Caption": "Vídeo de teste."
}

2. Responder com Vídeo:

Para responder a uma mensagem específica com um vídeo, use o ContextInfo.

{
  "Phone": "5511999998888",
  "Video": "data:video/mp4;base64,iVBORw0KGgo...",
  "Caption": "Respondendo com vídeo.",
  "ContextInfo": {
    "StanzaId": "ID_DA_MENSAGEM_ORIGINAL",
    "Participant": "JID_DO_AUTOR_ORIGINAL@s.whatsapp.net"
  }
}

3. Menções em Grupo com Vídeo:

As menções são feitas na legenda do vídeo.

Menção Individual: Use o array MentionedJID.
Mencionar Todos: Use o parâmetro "mentionAll": true.

Parâmetros do Corpo:

Parâmetro	Tipo	Descrição
Phone	string	Número do destinatário ou JID do grupo.
Video	string	Vídeo em formato base64 (data:video/mp4;base64,...).
Caption	string	Legenda opcional para o vídeo.
Id	string	ID personalizado para a mensagem (opcional).
ContextInfo	object	Usado para responder a mensagens ou para menções individuais.
mentionAll	boolean	Se `true`, menciona todos no grupo (apenas para grupos).
JpegThumbnail	string	Miniatura JPEG em base64 (opcional).

POST /chat/send/sticker

Envia um sticker.

Parâmetros do Corpo:

Phone	string	Número de telefone do destinatário.
Sticker	string	Sticker em formato base64 (data:image/webp;base64,...).
Id	string	ID personalizado para a mensagem.

POST /chat/send/location

Envia uma localização.

Parâmetros do Corpo:

Phone	string	Número de telefone do destinatário.
Latitude	float64	Latitude da localização.
Longitude	float64	Longitude da localização.
Name	string	Nome do local.
Id	string	ID personalizado para a mensagem.

POST /chat/send/contact

Envia um contato.

Parâmetros do Corpo:

Phone	string	Número de telefone do destinatário.
Name	string	Nome do contato.
Vcard	string	Vcard do contato.
Id	string	ID personalizado para a mensagem.

POST /chat/send/rejectCall

Rejeita uma chamada recebida e, opcionalmente, envia uma mensagem de texto para o autor da chamada.

Parâmetros do Corpo:

Parâmetro	Tipo	Descrição
callId	string	O ID da chamada, obtido do evento de webhook 'CallOffer'.
fromJid	string	O JID do autor da chamada, obtido do evento de webhook 'CallOffer'.
message	string	Mensagem de texto opcional para enviar após a recusa.

Exemplo de Requisição:

{
  "callId": "D89E7B96208F47F3677E",
  "fromJid": "5511999998888@s.whatsapp.net",
  "message": "Desculpe, não posso atender agora."
}

Resposta:

{
  "code": 200,
  "data": {
    "details": "Call rejected successfully"
  },
  "success": true
}

POST /chat/send/buttons

Envia uma mensagem com botões.

Parâmetros do Corpo:

Phone	string	Número de telefone do destinatário.
Title	string	Título da mensagem.
Buttons	array	Array de botões.
Id	string	ID personalizado para a mensagem.

POST /chat/send/list

Envia uma mensagem de lista.

Parâmetros do Corpo:

Phone	string	Número de telefone do destinatário.
ButtonText	string	Texto do botão da lista.
Desc	string	Descrição da lista.
TopText	string	Texto no topo da lista.
Sections	array	Seções da lista.
Id	string	ID personalizado para a mensagem.

POST /chat/send/poll

Envia uma enquete.

Parâmetros do Corpo:

Group	string	ID do grupo.
Header	string	Cabeçalho da enquete.
Options	array	Opções da enquete.
Id	string	ID personalizado para a mensagem.

POST /chat/send/edit

Edita uma mensagem enviada.

Parâmetros do Corpo:

Phone	string	Número de telefone do destinatário.
Id	string	ID da mensagem a ser editada.
Body	string	Novo corpo da mensagem.

POST /chat/delete

Deleta uma mensagem.

Parâmetros do Corpo:

Phone	string	Número de telefone do chat.
Id	string	ID da mensagem a ser deletada.

POST /chat/markread

Marca mensagens como lidas.

Parâmetros do Corpo:

Id	array	Array de IDs de mensagens.
Chat	string	JID do chat.
Sender	string	JID do remetente.

POST /chat/react

Reage a uma mensagem.

Parâmetros do Corpo:

Phone	string	Número de telefone do chat.
Body	string	Emoji de reação.
Id	string	ID da mensagem para reagir.

POST /chat/downloadimage

Baixa uma imagem de uma mensagem.

Parâmetros do Corpo:

Url	string	URL da imagem.
MediaKey	[]byte	Chave de mídia.
Mimetype	string	MIME type da imagem.
FileEncSHA256	[]byte	SHA256 do arquivo encriptado.
FileSHA256	[]byte	SHA256 do arquivo.
FileLength	uint64	Tamanho do arquivo.

POST /chat/downloadvideo

Baixa um vídeo de uma mensagem.

Parâmetros do Corpo:

Url	string	URL do vídeo.
MediaKey	[]byte	Chave de mídia.
Mimetype	string	MIME type do vídeo.
FileEncSHA256	[]byte	SHA256 do arquivo encriptado.
FileSHA256	[]byte	SHA256 do arquivo.
FileLength	uint64	Tamanho do arquivo.

POST /chat/downloadaudio

Baixa um áudio de uma mensagem.

Parâmetros do Corpo:

Url	string	URL do áudio.
MediaKey	[]byte	Chave de mídia.
Mimetype	string	MIME type do áudio.
FileEncSHA256	[]byte	SHA256 do arquivo encriptado.
FileSHA256	[]byte	SHA256 do arquivo.
FileLength	uint64	Tamanho do arquivo.

POST /chat/downloaddocument

Baixa um documento de uma mensagem.

Parâmetros do Corpo:

Url	string	URL do documento.
MediaKey	[]byte	Chave de mídia.
Mimetype	string	MIME type do documento.
FileEncSHA256	[]byte	SHA256 do arquivo encriptado.
FileSHA256	[]byte	SHA256 do arquivo.
FileLength	uint64	Tamanho do arquivo.

POST /chat/presence

Define a presença no chat (digitando/gravando).

Parâmetros do Corpo:

Phone	string	Número de telefone do chat.
State	string	Estado da presença ("composing", "paused" ou "recording").
Media	string	Mídia ("audio").
Delay	integer	Atraso em milissegundos para enviar automaticamente uma presença "pausada" após a presença inicial.

User

Endpoints para obter informações sobre usuários e gerenciar presença.

POST /user/check

Verifica se números de telefone têm WhatsApp.

Parâmetros do Corpo:

Parâmetro	Tipo	Descrição
Phone	Array[string]	Lista de números de telefone para verificar

Exemplo de Requisição:

{
  "Phone": ["5491155553934", "5491155553935"]
}

Resposta:

{
  "code": 200,
  "data": {
    "Users": [
      {
        "IsInWhatsapp": true,
        "JID": "5491155553934@s.whatsapp.net",
        "Query": "5491155553934",
        "VerifiedName": "Company Name"
      },
      {
        "IsInWhatsapp": false,
        "JID": "5491155553935@s.whatsapp.net",
        "Query": "5491155553935",
        "VerifiedName": ""
      }
    ]
  },
  "success": true
}

POST /user/info

Obtém informações sobre usuários do WhatsApp.

Parâmetros do Corpo:

Phone

array

Array de números de telefone.

POST /user/presence

Define a presença global do usuário.

Parâmetros do Corpo:

type

string

Tipo de presença ("available" ou "unavailable").

POST /user/avatar

Obtém o avatar de um usuário.

Parâmetros do Corpo:

Phone	string	Número de telefone do usuário.
Preview	boolean	Se deve obter uma pré-visualização.

GET /user/contacts

Obtém a lista de contatos.

Group

Endpoints para gerenciar grupos e suas propriedades.

GET /group/list

Lista todos os grupos aos quais a conta está vinculada.

Resposta:

{
  "code": 200,
  "data": {
    "Groups": [
      {
        "AnnounceVersionID": "1650572126123738",
        "DisappearingTimer": 0,
        "GroupCreated": "2022-04-21T17:15:26-03:00",
        "IsAnnounce": false,
        "IsEphemeral": false,
        "IsLocked": false,
        "JID": "120362023605733675@g.us",
        "Name": "Super Group",
        "NameSetAt": "2022-04-21T17:15:26-03:00",
        "NameSetBy": "5491155554444@s.whatsapp.net",
        "OwnerJID": "5491155554444@s.whatsapp.net",
        "ParticipantVersionID": "1650234126145738",
        "Participants": [
          {
            "IsAdmin": true,
            "IsSuperAdmin": true,
            "JID": "5491155554444@s.whatsapp.net"
          },
          {
            "IsAdmin": false,
            "IsSuperAdmin": false,
            "JID": "5491155553333@s.whatsapp.net"
          }
        ],
        "Topic": "",
        "TopicID": "",
        "TopicSetAt": "0001-01-01T00:00:00Z",
        "TopicSetBy": ""
      }
    ]
  },
  "success": true
}

POST /group/create

Cria um novo grupo.

Parâmetros do Corpo:

Name	string	Nome do grupo.
Participants	array	Array de números de telefone dos participantes.

GET /group/info

Obtém informações sobre um grupo.

Parâmetros de URL:

groupJID

string

JID do grupo.

GET /group/invitelink

Obtém o link de convite de um grupo.

Parâmetros de URL:

groupJID	string	JID do grupo.
reset	boolean	Se deve resetar o link de convite.

POST /group/photo

Define a foto de um grupo.

Parâmetros do Corpo:

GroupJID	string	JID do grupo.
Image	string	Imagem em formato base64.

POST /group/photo/remove

Remove a foto de um grupo.

Parâmetros do Corpo:

GroupJID

string

JID do grupo.

POST /group/leave

Sai de um grupo.

Parâmetros do Corpo:

GroupJID

string

JID do grupo.

POST /group/name

Define o nome de um grupo.

Parâmetros do Corpo:

GroupJID	string	JID do grupo.
Name	string	Novo nome do grupo.

POST /group/topic

Define o tópico (descrição) de um grupo.

Parâmetros do Corpo:

GroupJID	string	JID do grupo.
Topic	string	Novo tópico do grupo.

POST /group/announce

Define o modo de anúncio de um grupo.

Parâmetros do Corpo:

GroupJID	string	JID do grupo.
Announce	boolean	Se o grupo deve ser apenas para anúncios.

POST /group/locked

Define o modo de bloqueio de um grupo.

Parâmetros do Corpo:

GroupJID	string	JID do grupo.
Locked	boolean	Se o grupo deve ser bloqueado.

POST /group/ephemeral

Define o timer de mensagens efêmeras de um grupo.

Parâmetros do Corpo:

GroupJID	string	JID do grupo.
Duration	string	Duração ("24h", "7d", "90d", "off").

POST /group/join

Entra em um grupo através de um link de convite.

Parâmetros do Corpo:

Code

string

Código de convite.

POST /group/inviteinfo

Obtém informações sobre um convite de grupo.

Parâmetros do Corpo:

Code

string

Código de convite.

POST /group/updateparticipants

Adiciona, remove, promove ou rebaixa participantes de um grupo.

Parâmetros do Corpo:

GroupJID	string	JID do grupo.
Phone	array	Array de números de telefone dos participantes.
Action	string	Ação a ser executada ("add", "remove", "promote", "demote").

Admin

Endpoints administrativos para gerenciar usuários e instâncias.

GET /admin/users

Lista todos os usuários registrados no sistema.

Cabeçalhos:

Cabeçalho	Valor	Descrição
Authorization	string	Token administrativo para autenticação

Resposta:

{
  "code": 200,
  "data": [
    {
      "id": 1,
      "name": "John",
      "token": "1234ABCD",
      "webhook": "https://example.com/webhook",
      "jid": "5491155553934@s.whatsapp.net",
      "qrcode": "",
      "connected": true,
      "expiration": 0,
      "events": "Message,ReadReceipt"
    }
  ],
  "success": true
}

POST /admin/users

Cria um novo usuário no sistema.

Cabeçalhos:

Cabeçalho	Valor	Descrição
Authorization	string	Token administrativo para autenticação

Parâmetros do Corpo:

Parâmetro	Tipo	Descrição
name	string	Nome do usuário
token	string	Token de autenticação para o novo usuário
webhook	string	URL de webhook para o usuário (opcional)
events	string	Eventos para inscrever o usuário (opcional)

Exemplo de Requisição:

{
  "name": "Novo Usuário",
  "token": "token-secreto-123"
}

Resposta:

{
  "code": 201,
  "data": {
    "id": "5663e0c52063ec35d0ba45f7c2011c06",
    "name": "Novo Usuário",
    "token": "token-secreto-123",
    "webhook": "",
    "events": "",
    "proxy_config": {
      "enabled": false,
      "proxy_url": ""
    },
    "s3_config": {
      "enabled": false,
      "endpoint": "",
      "region": "",
      "bucket": "",
      "access_key": "***",
      "path_style": false,
      "public_url": "",
      "media_delivery": "base64",
      "retention_days": 0
    }
  },
  "success": true
}

DELETE /admin/users/{id}

Deleta um usuário do banco de dados pelo ID.

Cabeçalhos:

Cabeçalho	Valor	Descrição
Authorization	string	Token administrativo para autenticação

Parâmetros de URL:

Parâmetro	Tipo	Descrição
id	string	ID do usuário a ser deletado

Resposta:

{
  "code": 200,
  "data": {
    "id": "6b927654cada7635a4586bf8fad260a3"
  },
  "details": "User deleted successfully",
  "success": true
}

DELETE /admin/users/{id}/full

Deleta um usuário completamente, incluindo dados do S3, faz logout e desconecta do WhatsApp, e limpa da memória.

Cabeçalhos:

Cabeçalho	Valor	Descrição
Authorization	string	Token administrativo para autenticação

Parâmetros de URL:

Parâmetro	Tipo	Descrição
id	string	ID do usuário a ser deletado

Resposta:

{
  "code": 200,
  "data": {
    "id": "4e4942c7dee1deef99ab8fd9f7350de5",
    "jid": "",
    "name": "mariano"
  },
  "details": "User instance removed completely",
  "success": true
}

Endpoints para acessar newsletters do WhatsApp.

GET /newsletter/list

Lista todas as newsletters inscritas.

Resposta:

{
  "code": 200,
  "data": {
    "Newsletter": [
      {
        "id": "120363144038483540@newsletter",
        "state": {"type": "active"},
        "thread_metadata": {
          "creation_time": "1688746895",
          "description": {
            "text": "WhatsApp's official channel. Follow for our latest feature launches, updates, exclusive drops and more."
          },
          "name": {"text": "WhatsApp"},
          "picture": {"type": "IMAGE"},
          "subscribers_count": "0"
        },
        "viewer_metadata": {"role": "subscriber"}
      }
    ]
  },
  "success": true
}

S3 Storage

Configure o armazenamento S3-compatível para armazenar arquivos de mídia do WhatsApp. Suporta AWS S3, MinIO, DigitalOcean Spaces e outros provedores compatíveis.

GET /s3/config

Obtém a configuração atual do S3.

Resposta:

{
  "code": 200,
  "data": {
    "endpoint": "https://s3.amazonaws.com",
    "bucket": "meu-bucket",
    "region": "us-east-1",
    "path_prefix": "uploads/whatsapp/",
    "force_path_style": false
  },
  "success": true
}

PUT /s3/config

Configura o armazenamento S3 para esta instância.

Parâmetros do Corpo:

Parâmetro	Tipo	Descrição
endpoint	string	URL do endpoint S3 (padrão: https://s3.amazonaws.com)
access_key	string	Chave de acesso S3
secret_key	string	Chave secreta S3
bucket	string	Nome do bucket S3
region	string	Região do S3 (obrigatório para AWS S3)
path_prefix	string	Prefixo do caminho para organizar arquivos
force_path_style	boolean	Usar estilo de caminho forçado (necessário para MinIO)

Exemplo de Requisição:

{
  "endpoint": "https://s3.amazonaws.com",
  "access_key": "AKIAIOSFODNN7EXAMPLE",
  "secret_key": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
  "bucket": "meu-bucket-whatsapp",
  "region": "us-east-1",
  "path_prefix": "uploads/",
  "force_path_style": false
}

Resposta:

{
  "code": 200,
  "data": {
    "message": "S3 configuration saved successfully"
  },
  "success": true
}

POST /s3/test

Testa a conexão com o S3 usando a configuração fornecida.

Parâmetros do Corpo:

Mesmos parâmetros do endpoint PUT /s3/config

Resposta:

{
  "code": 200,
  "data": {
    "message": "S3 connection test successful"
  },
  "success": true
}

Exemplos de Configuração:

AWS S3: Use o endpoint padrão e especifique a região
MinIO: Use seu endpoint customizado (ex: http://localhost:9000) e ative force_path_style
DigitalOcean Spaces: Use https://nyc3.digitaloceanspaces.com como endpoint

Proxy

Configure um proxy HTTP/HTTPS ou SOCKS5 para conexões do WhatsApp. Útil para restrições de rede ou privacidade aprimorada.

GET /proxy/config

Obtém a configuração atual do proxy.

Resposta:

{
  "code": 200,
  "data": {
    "proxy_url": "socks5://proxy.example.com:1080",
    "username": "user",
    "bypass_list": ["localhost", "127.0.0.1", "*.local"]
  },
  "success": true
}

PUT /proxy/config

Configura o proxy para esta instância.

Parâmetros do Corpo:

Parâmetro	Tipo	Descrição
proxy_url	string	URL completa do proxy incluindo protocolo e porta
username	string	Nome de usuário para autenticação do proxy
password	string	Senha para autenticação do proxy
bypass_list	Array[string]	Lista de domínios/IPs que devem ignorar o proxy

Exemplo de Requisição:

{
  "proxy_url": "socks5://proxy.example.com:1080",
  "username": "usuario",
  "password": "senha123",
  "bypass_list": ["localhost", "127.0.0.1", "*.local", "192.168.*"]
}

Resposta:

{
  "code": 200,
  "data": {
    "message": "Proxy configuration saved successfully"
  },
  "success": true
}

POST /proxy/test

Testa a conexão através do proxy configurado.

Parâmetros do Corpo:

Mesmos parâmetros do endpoint PUT /proxy/config (exceto bypass_list)

Resposta:

{
  "code": 200,
  "data": {
    "message": "Proxy connection test successful",
    "response_time": "245ms"
  },
  "success": true
}

Formatos de URL suportados:

HTTP/HTTPS: http://proxy.example.com:8080
SOCKS5: socks5://proxy.example.com:1080
Com autenticação: socks5://user:pass@proxy.example.com:1080

Estrutura de Webhook

Quando seu webhook é chamado, ele recebe uma requisição POST com um corpo JSON. A estrutura desse JSON varia dependendo do evento que o disparou. Todos os webhooks incluem os seguintes dados no corpo da requisição, encapsulados em um objeto JSON:

{
  "jsonData": "...",
  "token": "seu_token_de_usuario",
  "instanceName": "NomeDaSuaInstancia"
}

O campo jsonData é uma string JSON que contém o payload real do evento. Você precisará fazer o parse dessa string para acessar os dados do evento.

Tipos de Eventos Disponíveis

Esta é a lista completa de eventos que podem ser inscritos e que disparam um webhook:

Mensagens e Comunicação

Message - Mensagem recebida/enviada (formato legado).
messages.upsert.private - Mensagem privada (novo formato estruturado).
messages.upsert.groups - Mensagem em grupo (formato legado).
MediaRetry - Solicitação de nova tentativa de download de mídia.

Recibos e Presença

ReadReceipt - Recibos de leitura/entrega (Read, ReadSelf, Delivered).
Presence - Presença do contato (online/offline).
ChatPresence - Presença no chat (composing/paused).

Conexão e Sessão

Connected - Conectado com sucesso.
Disconnected - Desconectado.
ConnectFailure - Falha na conexão.
LoggedOut - Sessão encerrada.
QR - Código QR gerado para conexão.
PairError - Erro durante o pareamento.
KeepAliveRestored - Conexão KeepAlive restaurada.
KeepAliveTimeout - Timeout da conexão KeepAlive.

Grupos

GroupInfo - Informações do grupo atualizadas.
JoinedGroup - Entrada em um novo grupo.

Newsletter (Canais)

NewsletterJoin - Inscrição em um canal.
NewsletterLeave - Saída de um canal.
NewsletterMuteChange - Alteração no status de mudo de um canal.
NewsletterLiveUpdate - Atualização ao vivo de um canal.

Chamadas

CallOffer - Oferta de chamada recebida.
CallAccept - Chamada aceita.
CallTerminate - Chamada encerrada.
CallOfferNotice - Notificação de oferta de chamada.
CallRelayLatency - Latência do relay da chamada.

Sincronização e Estado

HistorySync - Evento de sincronização de histórico.
OfflineSyncCompleted - Sincronização offline de mensagens concluída.
OfflineSyncPreview - Pré-visualização da sincronização offline.

Privacidade, Perfil e Bloqueios

Blocklist - Lista de contatos bloqueados recebida.
BlocklistChange - Alteração na lista de bloqueados.
PrivacySettings - Configurações de privacidade atualizadas.
UserAbout - Status/Recado do usuário atualizado.

Outros Eventos de Cliente

IdentityChange - Mudança de identidade de um contato.
ClientOutdated - A versão do cliente está desatualizada.
TemporaryBan - Banimento temporário detectado.
StreamError - Erro no stream de comunicação.

Geral

All - Assina todos os eventos disponíveis.

Estrutura de Payloads

Evento: `messages.upsert.private`

Este é o novo evento para mensagens privadas, com uma estrutura rica e detalhada. É recomendado para novos desenvolvimentos.

{
  "event": "messages.upsert.private",
  "type": "messages.upsert.private",
  "instanceName": "MinhaInstancia",
  "apikey": "seu-token",
  "timestamp": 1679686148,
  "messageType": "textMessage",
  "instanceId": "seu-user-id",
  "sender": "5511999998888@s.whatsapp.net",
  "server_url": "https://api.seudominio.com",
  "data": {
    "key": {
      "remoteJid": "5511999998888@s.whatsapp.net",
      "fromMe": false,
      "id": "3EB012A34B56C7D9D87E"
    },
    "message": {
      "conversation": "Olá, esta é uma mensagem de teste!"
    },
    "messageTimestamp": 1679686148,
    "pushName": "Nome do Contato",
    "source": "5511999998888@s.whatsapp.net",
    "status": "received"
  }
}

Para mensagens de mídia (imagem, vídeo, áudio, documento), o objeto data e o objeto message conterão campos adicionais, como base64, mimeType, fileName, e s3.

Eventos: `Message` e `messages.upsert.groups`

Estes eventos usam um formato legado. messages.upsert.groups é o evento para mensagens em grupo.

{
  "event": {
    "Info": {
      "ID": "3EB012A34B56C7D9D87E",
      "Source": "5521999998888@s.whatsapp.net",
      "Timestamp": "2023-03-24T15:49:08-03:00",
      "PushName": "Nome do Contato",
      "IsFromMe": false,
      "IsGroup": true,
      "Chat": "120363043935926897@g.us"
    },
    "Message": {
      "conversation": "Olá, grupo!"
    }
  },
  "type": "Message"
}

Evento: `ReadReceipt`

Indica uma mudança no status de uma mensagem enviada.

{
  "event": {
    "Source": "5521999998888@s.whatsapp.net",
    "Timestamp": "2023-03-24T15:50:10-03:00",
    "Type": 1,
    "MessageIDs": ["3EB012A34B56C7D9D87E"]
  },
  "type": "ReadReceipt",
  "state": "Read"
}

O campo state pode ser Read (lida), ReadSelf (lida por você em outro dispositivo) ou Delivered (entregue).

Evento: `Presence`

Informa quando um contato fica online ou offline.

{
  "event": {
    "From": "5521999998888@s.whatsapp.net",
    "Unavailable": false,
    "LastSeen": "0001-01-01T00:00:00Z"
  },
  "type": "Presence",
  "state": "online"
}

O campo state pode ser online ou offline.

Evento: `ChatPresence`

Informa quando um contato está digitando ou gravando em um chat.

{
  "event": {
    "From": "120363043935926897@g.us",
    "State": "composing",
    "Media": 1
  },
  "type": "ChatPresence",
  "state": "composing"
}

O campo state pode ser composing (digitando) ou paused.

Evento: `Connected`

Disparado quando a conexão com o WhatsApp é estabelecida com sucesso.

{
  "type": "Connected",
  "event": {
    "Version": 18,
    "LongConnect": true
  }
}

Evento: `QR`

Fornece o código QR para conectar uma nova sessão.

{
  "event": "code",
  "qrCodeBase64": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUg...",
  "type": "QR"
}

Eventos de Chamada (Ex: `CallOffer`)

Eventos relacionados a chamadas de voz e vídeo.

{
  "type": "CallOffer",
  "event": {
    "CallID": "...",
    "Timestamp": "...",
    "IsVideo": false,
    "From": "5521999998888@s.whatsapp.net",
    "Capabilities": [...]
  }
}

Eventos de Grupo (Ex: `GroupInfo`)

Informações sobre atualizações em grupos, como mudança de nome, descrição ou participantes.

{
  "type": "GroupInfo",
  "event": {
    "JID": "120363043935926897@g.us",
    "OwnerJID": "5511999998888@s.whatsapp.net",
    "GroupName": {
      "Name": "Nome do Grupo",
      "NameSetAt": "...",
      "NameSetBy": "..."
    },
    "Participants": [...]
  }
}

Outros Eventos

Muitos outros eventos seguem uma estrutura semelhante, onde o payload contém o tipo do evento (type) e o objeto de evento bruto correspondente (event) da biblioteca whatsmeow. Isso inclui eventos como MediaRetry, BlocklistChange, PrivacySettings, HistorySync, ClientOutdated, eventos de Newsletter, entre outros.

A estrutura geral é:

{
  "type": "NomeDoEvento",
  "event": {
    // ... campos do objeto de evento bruto ...
  }
}

Como os campos dentro de event podem variar, recomenda-se inspecionar o payload recebido no seu webhook para ver a estrutura exata de cada tipo de evento que você assinar.

Melhores Práticas

Para usar a API SMARTZAP API de forma eficiente e evitar problemas, considere estas melhores práticas:

Segurança

Mantenha seus tokens de autenticação seguros e não os exponha publicamente.
Use HTTPS para todas as comunicações com a API e com seus webhooks.
Implemente validação adequada para os webhooks recebidos para evitar processamento de dados maliciosos.

Limites de Uso

Evite enviar muitas mensagens em um curto período para evitar bloqueios por parte do WhatsApp.
Implemente mecanismos de retry com backoff exponencial para lidar com falhas temporárias.
Monitore o status da conexão regularmente e reconecte quando necessário.

Webhooks

Certifique-se de que seu endpoint de webhook pode processar as requisições rapidamente (menos de 5 segundos).
Implemente uma fila para processar eventos assincronamente se o processamento for demorado.
Configure seu servidor para lidar com picos de tráfego, especialmente se você gerencia vários números.

Perguntas Frequentes

Sim, a SMARTZAP API suporta múltiplas instâncias. Cada instância possui seu próprio token e pode se conectar a um número de WhatsApp diferente. Você pode gerenciar todas as instâncias através do painel administrativo.

Se o WhatsApp desconectar sua sessão (por exemplo, ao conectar no aplicativo ou ao clicar em "Sair de todos os dispositivos"), você precisará se reconectar através do endpoint /session/connect e escanear o QR novamente. A SMARTZAP API não reconecta automaticamente em caso de logout forçado.

Para reduzir o risco de bloqueio:

Não envie mensagens em massa para pessoas que não te conhecem
Não envie a mesma mensagem para muitos contatos em sequência
Respeite os limites de envio (aproximadamente 50-100 mensagens por dia para novos números)
Use um número que já tenha histórico de uso no WhatsApp
Não use a API para enviar spam ou conteúdo inadequado