VIP API 48 Ações Reais Webhooks em Tempo Real

API WhatsApp (Instâncias) — EditaCódigo

Documentação técnica completa para desenvolvedores integrarem suas instâncias contratadas de WhatsApp em sistemas proprietários, bots, automações de CRM e plataformas de atendimento.

Seu Token de API: Encontre seu token na aba Instâncias → "Seu token da API VIP". Ele concede acesso total ao envio e leitura de dados das suas instâncias — nunca compartilhe nem exponha no código front-end!

Ações documentadas prontas para uso

JSON

Padrão simplificado de entrada e saída

100%

Campos intuitivos em português

🛠️ Gerenciar Mensagens

🗂️ Conversas & Histórico

5 ações

Endpoint Único

Endpoint Base

POST/GET http://109.199.96.201/gowa-alunos/api.php

Todas as ações da API utilizam exatamente a mesma URL base. A operação desejada é especificada através do parâmetro acao (via query string na URL: ?acao=nome_da_acao).

Ações de leitura (consulta): Aceitam o método GET com os parâmetros na URL.
Ações de escrita (envio/alteração): Utilizam o método POST com o cabeçalho Content-Type: application/json e os parâmetros no corpo em formato JSON.

Atenção sobre HTTP (Servidor para Servidor): O endpoint utiliza o protocolo HTTP padrão. Caso você tente efetuar chamadas a partir de navegadores em páginas hospedadas com HTTPS, o navegador bloqueará a requisição por "Conteúdo Misto" (Mixed Content). Sempre execute as chamadas da API a partir do backend da sua aplicação (PHP, Node.js, Python, Ruby, C#, Java, Go, etc.).

Autenticação

Todas as requisições autenticam-se com o seu token pessoal:

Em requisições POST: Inclua a chave "token": "SEU_TOKEN_AQUI" no JSON enviado no corpo da requisição.
Em requisições GET: Adicione o token como parâmetro de query string na URL: ?acao=...&token=SEU_TOKEN_AQUI.

Identificador de Instância (device_id)

Cada WhatsApp contratado no site possui um identificador único denominado device_id. Para localizá-lo:

Acesse a página Instâncias.
No card da instância desejada, clique no botão ℹ️ Mais detalhes.
Copie o código exibido no campo Device ID (ex: dev_abc12345).

⚡ Instância

Gerencie a conexão, QR Code, webhooks e ciclo de vida de cada uma das suas instâncias de WhatsApp.

GET

`minhas_instancias`

Lista todas as instâncias vinculadas ao seu token da API VIP, informando o status de conexão ao vivo (se o QR Code já foi pareado e se está conectada no momento), apelido, data de expiração e webhooks configurados.

Campo	Tipo	Obrigatório	Descrição
`token`	`string`	sim	Seu token da API VIP.

Exemplo cURL

curl "http://109.199.96.201/gowa-alunos/api.php?acao=minhas_instancias&token=SEU_TOKEN"

Exemplo de Resposta

{
  "ok": true,
  "instancias": [
    {
      "device_id": "dev_abc12345",
      "apelido": "Atendimento Comercial",
      "is_logged_in": true,
      "is_connected": true,
      "webhook_url": "https://meusite.com.br/api/whatsapp-webhook",
      "cron_url": "https://meusite.com.br/api/whatsapp-ping",
      "criado_em": "2026-09-01 10:00:00",
      "expira_em": "2026-10-01 10:00:00"
    }
  ]
}

GET

`status_instancia`

Verifica se uma instância específica está conectada e com sessão ativa (QR Code já escaneado e validado no WhatsApp do celular).

Campo	Tipo	Obrigatório	Descrição
`token`	`string`	sim	Seu token da API VIP.
`device_id`	`string`	sim	Identificador exclusivo da instância.

Exemplo cURL

curl "http://109.199.96.201/gowa-alunos/api.php?acao=status_instancia&device_id=SEU_DEVICE_ID&token=SEU_TOKEN"

Exemplo de Resposta

{
  "ok": true,
  "results": {
    "is_logged_in": true,
    "is_connected": true
  }
}

GET

`login_instancia`

Inicia o processo de conexão da instância gerando a string de pareamento do QR Code. Você pode renderizar essa string como imagem na sua interface (usando bibliotecas como QRCode no seu backend ou serviços como api.qrserver.com).

Campo	Tipo	Obrigatório	Descrição
`token`	`string`	sim	Seu token da API VIP.
`device_id`	`string`	sim	Identificador exclusivo da instância.

Exemplo cURL

curl "http://109.199.96.201/gowa-alunos/api.php?acao=login_instancia&device_id=SEU_DEVICE_ID&token=SEU_TOKEN"

Exemplo de Resposta

{
  "ok": true,
  "results": {
    "qr": "2@4w8kLp7...string_bruta_do_qr_code...==",
    "is_logged_in": false
  }
}

POST

`logout_instancia`

Desconecta a sessão ativa do WhatsApp na instância. O cadastro da sua instância e seus créditos permanecem intactos, permitindo que você reconecte um novo número ou gere outro QR Code a qualquer momento.

Campo	Tipo	Obrigatório	Descrição
`token`	`string`	sim	Seu token da API VIP.
`device_id`	`string`	sim	Identificador da instância a desconectar.

Exemplo cURL

curl -X POST "http://109.199.96.201/gowa-alunos/api.php?acao=logout_instancia" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "SEU_TOKEN",
    "device_id": "SEU_DEVICE_ID"
  }'

Exemplo de Resposta

{
  "ok": true,
  "message": "Instância desconectada com sucesso."
}

POST

`atualizar_instancia`

⚡ Recurso Principal para Recebimento de Mensagens

Configura os destinos de automação da sua instância: a webhook_url (onde sua aplicação receberá mensagens recebidas em tempo real) e a cron_url (URL pingada periodicamente para validação de integridade).

Importante: Pelo menos um dos dois campos deve ser enviado. Passar uma string vazia "" apaga o valor previamente configurado. Caso omita um campo, a configuração atual daquele campo será preservada.

Destaque de Arquitetura Como funciona o Webhook de Mensagens Recebidas

Quando alguém envia uma mensagem de texto, foto, áudio ou documento para o WhatsApp conectado à sua instância, nosso servidor dispara uma requisição HTTP POST em formato JSON para a sua webhook_url em tempo real.

Exemplo de Payload que o seu servidor recebe:

{
  "event": "message_received",
  "device_id": "dev_abc12345",
  "chat_id": "5511999999999@s.whatsapp.net",
  "from": "5511999999999",
  "is_from_me": false,
  "message_id": "3EB09F218C7A48E9D012",
  "timestamp": 1726915200,
  "tipo": "text",
  "mensagem": "Olá! Gostaria de falar com o suporte sobre meu pedido.",
  "push_name": "Mariana Santos",
  "midia": null
}

Formato aproximado — os campos chat_id e is_from_me são confirmados, mas o payload completo pode variar. Recomendamos logar o corpo bruto recebido na primeira mensagem de teste pra confirmar a estrutura exata antes de decodificar em produção.

Dicas para implementar o seu Webhook:

Resposta Rápida: Responda imediatamente com HTTP 200 OK ao receber o POST (idealmente em menos de 3 segundos). Processe regras pesadas ou chamadas de IA em segundo plano (fila/jobs).
Mensagens com Mídia: Quando tipo for diferente de text (ex: image, audio, file), use a ação baixar_midia_mensagem com o id_mensagem para obter o arquivo binário ou base64.
Segurança: Utilize endpoints HTTPS públicos para sua webhook_url.

Campo	Tipo	Obrigatório	Descrição
`token`	`string`	sim	Seu token da API VIP.
`device_id`	`string`	sim	Identificador da instância.
`webhook_url`	`string`	opcional*	URL HTTPS no seu servidor que receberá os eventos e mensagens recebidas via POST JSON. Enviar string vazia `""` remove a URL configurada.
`cron_url`	`string`	opcional*	URL no seu servidor que o nosso serviço pingará periodicamente para auditar a saúde da instância. Enviar string vazia `""` remove a URL configurada.

Exemplo cURL

curl -X POST "http://109.199.96.201/gowa-alunos/api.php?acao=atualizar_instancia" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "SEU_TOKEN",
    "device_id": "SEU_DEVICE_ID",
    "webhook_url": "https://meusite.com.br/api/whatsapp-webhook",
    "cron_url": "https://meusite.com.br/api/whatsapp-healthcheck"
  }'

Exemplo de Resposta

{
  "ok": true,
  "message": "Instância atualizada com sucesso."
}

💬 Envio de Mensagens

Envie mensagens individuais de texto, mídias em base64 (imagens, áudios, figurinhas, vídeos, documentos), enquetes interativas, cartões de contato, links com prévia e localização.

POST

`enviar_mensagem`

Envia uma mensagem de texto tradicional para um número de WhatsApp individual.

Campo	Tipo	Obrigatório	Descrição
`token`	`string`	sim	Seu token da API VIP.
`device_id`	`string`	sim	Identificador da instância que enviará a mensagem.
`telefone`	`string`	sim	Número de telefone com DDI + DDD e apenas dígitos (ex: `5511999999999`).
`mensagem`	`string`	sim	Conteúdo do texto a enviar.

Exemplo cURL

curl -X POST "http://109.199.96.201/gowa-alunos/api.php?acao=enviar_mensagem" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "SEU_TOKEN",
    "device_id": "SEU_DEVICE_ID",
    "telefone": "5511999999999",
    "mensagem": "Olá! Seu pedido #1248 foi aprovado com sucesso."
  }'

Exemplo de Resposta

{
  "code": "SUCCESS",
  "message": "Mensagem enviada com sucesso.",
  "results": {
    "message_id": "3EB07A65B901C4E8",
    "timestamp": 1726915200
  }
}

POST

`enviar_midia`

Envia arquivos de imagem, áudio/voz, vídeo, figurinhas (stickers) ou documentos em geral codificados em base64.

Campo	Tipo	Obrigatório	Descrição
`token`	`string`	sim	Seu token da API VIP.
`device_id`	`string`	sim	Identificador da instância.
`telefone`	`string`	sim	Número de telefone com DDI e DDD (apenas dígitos).
`tipo`	`string`	sim	Tipo do arquivo: `image`, `audio`, `file`, `video` ou `sticker`.
`conteudo_base64`	`string`	sim	Conteúdo binário do arquivo codificado em Base64.
`nome_arquivo`	`string`	não	Nome exibido com extensão (ex: `relatorio.pdf`, `foto.jpg`).
`legenda`	`string`	não	Texto de legenda que acompanha a mídia (não se aplica a `sticker`).

Exemplo cURL

curl -X POST "http://109.199.96.201/gowa-alunos/api.php?acao=enviar_midia" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "SEU_TOKEN",
    "device_id": "SEU_DEVICE_ID",
    "telefone": "5511999999999",
    "tipo": "image",
    "conteudo_base64": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNk+A8AAQUBAScY42YAAAAASUVORK5CYII=",
    "nome_arquivo": "comprovante.png",
    "legenda": "Segue o seu comprovante de pagamento."
  }'

Exemplo de Resposta

{
  "code": "SUCCESS",
  "message": "Mídia enviada com sucesso.",
  "results": {
    "message_id": "3EB08B12C4509F71"
  }
}

POST

`enviar_enquete`

Envia uma enquete nativa do WhatsApp com opções de múltipla escolha ou voto único clicáveis.

Atenção: Por limitações do protocolo do próprio WhatsApp, não é possível consultar via API quais opções foram votadas pelo contato.

Campo	Tipo	Obrigatório	Descrição
`token`	`string`	sim	Seu token da API VIP.
`device_id`	`string`	sim	Identificador da instância.
`telefone`	`string`	sim	Número de telefone destinatário.
`pergunta`	`string`	sim	Título/pergunta principal da enquete.
`opcoes`	`array`	sim	Lista de opções em texto (strings), ex: `["Sim", "Não", "Talvez"]`.
`max_respostas`	`int`	não	Número máximo de opções que cada participante pode marcar (padrão: `1`).

Exemplo cURL

curl -X POST "http://109.199.96.201/gowa-alunos/api.php?acao=enviar_enquete" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "SEU_TOKEN",
    "device_id": "SEU_DEVICE_ID",
    "telefone": "5511999999999",
    "pergunta": "Qual o melhor turno para seu atendimento?",
    "opcoes": ["Manhã (09h - 12h)", "Tarde (14h - 18h)", "Noite (19h - 21h)"],
    "max_respostas": 1
  }'

Exemplo de Resposta

{
  "code": "SUCCESS",
  "message": "Enquete enviada com sucesso.",
  "results": {
    "message_id": "3EB09F88A123BC04"
  }
}

POST

`enviar_contato`

Envia um cartão de contato nativo (vCard) para a conversa, permitindo que o destinatário salve o número com um toque.

Campo	Tipo	Obrigatório	Descrição
`token`	`string`	sim	Seu token da API VIP.
`device_id`	`string`	sim	Identificador da instância.
`telefone`	`string`	sim	Destinatário que receberá o cartão.
`nome_contato`	`string`	sim	Nome da pessoa ou empresa do contato a ser compartilhado.
`telefone_contato`	`string`	sim	Número de telefone do contato compartilhado.

Exemplo cURL

curl -X POST "http://109.199.96.201/gowa-alunos/api.php?acao=enviar_contato" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "SEU_TOKEN",
    "device_id": "SEU_DEVICE_ID",
    "telefone": "5511999999999",
    "nome_contato": "Dra. Ana Paula - Consultório",
    "telefone_contato": "5511988887777"
  }'

Exemplo de Resposta

{
  "code": "SUCCESS",
  "message": "Contato enviado com sucesso.",
  "results": {
    "message_id": "3EB0A559E817DC42"
  }
}

POST

`enviar_link`

Envia um link com geração automática do cartão de pré-visualização (título da página, favicon/imagem e descrição extraídos dos metadados Open Graph da URL).

Campo	Tipo	Obrigatório	Descrição
`token`	`string`	sim	Seu token da API VIP.
`device_id`	`string`	sim	Identificador da instância.
`telefone`	`string`	sim	Número destinatário.
`link`	`string`	sim	URL completa a ser enviada (ex: `https://editacodigo.com.br`).
`legenda`	`string`	não	Texto descritivo adicional exibido junto ao link.

Exemplo cURL

curl -X POST "http://109.199.96.201/gowa-alunos/api.php?acao=enviar_link" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "SEU_TOKEN",
    "device_id": "SEU_DEVICE_ID",
    "telefone": "5511999999999",
    "link": "https://www.editacodigo.com.br",
    "legenda": "Confira nossos cursos e tutoriais completos."
  }'

Exemplo de Resposta

{
  "code": "SUCCESS",
  "message": "Link enviado com sucesso.",
  "results": {
    "message_id": "3EB0B1299C71AE53"
  }
}

POST

`enviar_localizacao`

Envia coordenadas geográficas de latitude e longitude que são renderizadas como um pin de mapa interativo no WhatsApp.

Campo	Tipo	Obrigatório	Descrição
`token`	`string`	sim	Seu token da API VIP.
`device_id`	`string`	sim	Identificador da instância.
`telefone`	`string`	sim	Número destinatário.
`latitude`	`float/string`	sim	Coordenada de latitude (ex: `-23.550520`).
`longitude`	`float/string`	sim	Coordenada de longitude (ex: `-46.633308`).

Exemplo cURL

curl -X POST "http://109.199.96.201/gowa-alunos/api.php?acao=enviar_localizacao" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "SEU_TOKEN",
    "device_id": "SEU_DEVICE_ID",
    "telefone": "5511999999999",
    "latitude": -23.550520,
    "longitude": -46.633308
  }'

Exemplo de Resposta

{
  "code": "SUCCESS",
  "message": "Localização enviada com sucesso.",
  "results": {
    "message_id": "3EB0C3301E88DB99"
  }
}

🛠️ Gerenciar Mensagens

Interaja com mensagens enviadas ou recebidas: reaja com emojis, revogue (apague para todos), exclua localmente, edite textos, marque como lida, favorite, encaminhe ou faça download de mídias.

POST

`reagir_mensagem`

Adiciona ou remove uma reação com emoji em uma mensagem específica (o id_mensagem é o message_id retornado no envio ou recebido via webhook).

Campo	Tipo	Obrigatório	Descrição
`token`	`string`	sim	Seu token da API VIP.
`device_id`	`string`	sim	Identificador da instância.
`telefone`	`string`	sim	Número da conversa onde está a mensagem.
`id_mensagem`	`string`	sim	Identificador da mensagem (`message_id`).
`emoji`	`string`	sim	Emoji da reação (ex: `"👍"`, `"❤️"`, `"🔥"`). Para remover a reação, passe uma string vazia `""`.

Exemplo cURL

curl -X POST "http://109.199.96.201/gowa-alunos/api.php?acao=reagir_mensagem" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "SEU_TOKEN",
    "device_id": "SEU_DEVICE_ID",
    "telefone": "5511999999999",
    "id_mensagem": "3EB07A65B901C4E8",
    "emoji": "👍"
  }'

Exemplo de Resposta

{
  "ok": true,
  "message": "Reação aplicada com sucesso."
}

POST

`revogar_mensagem`

Apaga a mensagem para todos os participantes da conversa ("Apagar para todos").

Regra nativa do WhatsApp: Só é possível revogar mensagens que foram enviadas pela própria instância.

Campo	Tipo	Obrigatório	Descrição
`token`	`string`	sim	Seu token da API VIP.
`device_id`	`string`	sim	Identificador da instância.
`telefone`	`string`	sim	Número ou chat da conversa.
`id_mensagem`	`string`	sim	Identificador da mensagem enviada pela instância.

Exemplo cURL

curl -X POST "http://109.199.96.201/gowa-alunos/api.php?acao=revogar_mensagem" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "SEU_TOKEN",
    "device_id": "SEU_DEVICE_ID",
    "telefone": "5511999999999",
    "id_mensagem": "3EB07A65B901C4E8"
  }'

Exemplo de Resposta

{
  "ok": true,
  "message": "Mensagem revogada para todos."
}

POST

`apagar_mensagem_local`

Exclui a mensagem apenas da visão local dessa instância ("Apagar para mim"), sem afetar o dispositivo do outro contato.

Campo	Tipo	Obrigatório	Descrição
`token`	`string`	sim	Seu token da API VIP.
`device_id`	`string`	sim	Identificador da instância.
`telefone`	`string`	sim	Número do contato/chat.
`id_mensagem`	`string`	sim	Identificador da mensagem.

Exemplo cURL

curl -X POST "http://109.199.96.201/gowa-alunos/api.php?acao=apagar_mensagem_local" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "SEU_TOKEN",
    "device_id": "SEU_DEVICE_ID",
    "telefone": "5511999999999",
    "id_mensagem": "3EB07A65B901C4E8"
  }'

Exemplo de Resposta

{
  "ok": true,
  "message": "Mensagem apagada localmente."
}

POST

`editar_mensagem`

Edita o texto de uma mensagem já enviada anteriormente pela instância (sujeito à janela de tolerância de edição permitida pelo WhatsApp).

Campo	Tipo	Obrigatório	Descrição
`token`	`string`	sim	Seu token da API VIP.
`device_id`	`string`	sim	Identificador da instância.
`telefone`	`string`	sim	Número destinatário.
`id_mensagem`	`string`	sim	Identificador da mensagem a editar.
`mensagem`	`string`	sim	Novo texto corrigido da mensagem.

Exemplo cURL

curl -X POST "http://109.199.96.201/gowa-alunos/api.php?acao=editar_mensagem" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "SEU_TOKEN",
    "device_id": "SEU_DEVICE_ID",
    "telefone": "5511999999999",
    "id_mensagem": "3EB07A65B901C4E8",
    "mensagem": "Olá! O horário correto do atendimento é às 15:00."
  }'

Exemplo de Resposta

{
  "ok": true,
  "message": "Mensagem editada com sucesso."
}

POST

`marcar_lida`

Envia a confirmação de leitura da mensagem recebida (ativa o tique duplo azul no aplicativo do remetente).

Campo	Tipo	Obrigatório	Descrição
`token`	`string`	sim	Seu token da API VIP.
`device_id`	`string`	sim	Identificador da instância.
`telefone`	`string`	sim	Número do remetente.
`id_mensagem`	`string`	sim	Identificador da mensagem recebida.

Exemplo cURL

curl -X POST "http://109.199.96.201/gowa-alunos/api.php?acao=marcar_lida" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "SEU_TOKEN",
    "device_id": "SEU_DEVICE_ID",
    "telefone": "5511999999999",
    "id_mensagem": "3EB09F218C7A48E9D012"
  }'

Exemplo de Resposta

{
  "ok": true,
  "message": "Mensagem marcada como lida."
}

POST

`favoritar_mensagem`

Marca ou desmarca uma mensagem como favorita (com estrela) no WhatsApp.

Campo	Tipo	Obrigatório	Descrição
`token`	`string`	sim	Seu token da API VIP.
`device_id`	`string`	sim	Identificador da instância.
`telefone`	`string`	sim	Número da conversa.
`id_mensagem`	`string`	sim	Identificador da mensagem.
`favoritar`	`bool`	não	`true` para adicionar estrela, `false` para remover (padrão: `true`).

Exemplo cURL

curl -X POST "http://109.199.96.201/gowa-alunos/api.php?acao=favoritar_mensagem" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "SEU_TOKEN",
    "device_id": "SEU_DEVICE_ID",
    "telefone": "5511999999999",
    "id_mensagem": "3EB07A65B901C4E8",
    "favoritar": true
  }'

Exemplo de Resposta

{
  "ok": true,
  "message": "Status de favorito atualizado."
}

POST

`encaminhar_mensagem`

Encaminha uma mensagem já existente para outro número ou grupo sem precisar baixar o arquivo ou redigitar o texto.

Campo	Tipo	Obrigatório	Descrição
`token`	`string`	sim	Seu token da API VIP.
`device_id`	`string`	sim	Identificador da instância.
`telefone`	`string`	sim	Número da conversa de origem da mensagem.
`id_mensagem`	`string`	sim	Identificador da mensagem a ser encaminhada.
`telefone_destino`	`string`	sim	Número de telefone ou JID de grupo de destino.

Exemplo cURL

curl -X POST "http://109.199.96.201/gowa-alunos/api.php?acao=encaminhar_mensagem" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "SEU_TOKEN",
    "device_id": "SEU_DEVICE_ID",
    "telefone": "5511999999999",
    "id_mensagem": "3EB07A65B901C4E8",
    "telefone_destino": "5511988887777"
  }'

Exemplo de Resposta

{
  "ok": true,
  "message": "Mensagem encaminhada com sucesso.",
  "results": {
    "message_id": "3EB0F44199A7"
  }
}

GET / POST

`baixar_midia_mensagem`

Faz o download e devolve o conteúdo de mídia (imagem, áudio, vídeo, documento) associado a uma mensagem recebida.

Campo	Tipo	Obrigatório	Descrição
`token`	`string`	sim	Seu token da API VIP.
`device_id`	`string`	sim	Identificador da instância.
`telefone`	`string`	sim	Número do remetente/chat.
`id_mensagem`	`string`	sim	Identificador da mensagem que contém a mídia.

Exemplo cURL

curl "http://109.199.96.201/gowa-alunos/api.php?acao=baixar_midia_mensagem&device_id=SEU_DEVICE_ID&telefone=5511999999999&id_mensagem=3EB09F218C7A48E9D012&token=SEU_TOKEN"

Exemplo de Resposta

{
  "ok": true,
  "results": {
    "mimetype": "image/jpeg",
    "nome_arquivo": "foto.jpg",
    "tamanho_bytes": 145890,
    "conteudo_base64": "/9j/4AAQSkZJRgABAQEASABIAAD..."
  }
}

👥 Grupos do WhatsApp

Controle completo sobre grupos: criar grupos, entrar via link, alterar nome/descrição/foto, gerenciar participantes, promover/rebaixar administradores, links de convite e pedidos de entrada. O identificador (JID) de um grupo sempre termina com @g.us.

GET

`listar_grupos`

Lista todos os grupos do WhatsApp dos quais a instância participa no momento.

Campo	Tipo	Obrigatório	Descrição
`token`	`string`	sim	Seu token da API VIP.
`device_id`	`string`	sim	Identificador da instância.

Exemplo cURL

curl "http://109.199.96.201/gowa-alunos/api.php?acao=listar_grupos&device_id=SEU_DEVICE_ID&token=SEU_TOKEN"

Exemplo de Resposta

{
  "ok": true,
  "grupos": [
    {
      "id_grupo": "120363025492928192@g.us",
      "nome": "Clientes VIP 2026",
      "topico": "Grupo de avisos e suporte aos membros VIP.",
      "total_participantes": 84,
      "is_admin": true,
      "trancado": true,
      "somente_admin": true
    }
  ]
}

GET

`info_grupo`

Retorna informações detalhadas de um grupo específico: título, tópico, se está trancado para edição, se é somente anúncio, contagem e lista com os dados dos participantes.

Campo	Tipo	Obrigatório	Descrição
`token`	`string`	sim	Seu token da API VIP.
`device_id`	`string`	sim	Identificador da instância.
`id_grupo`	`string`	sim	JID do grupo (ex: `120363025492928192@g.us`).

Exemplo cURL

curl "http://109.199.96.201/gowa-alunos/api.php?acao=info_grupo&device_id=SEU_DEVICE_ID&id_grupo=120363025492928192@g.us&token=SEU_TOKEN"

Exemplo de Resposta

{
  "ok": true,
  "grupo": {
    "id_grupo": "120363025492928192@g.us",
    "nome": "Comunidade EditaCódigo",
    "topico": "Tire suas dúvidas técnicas sobre os tutoriais.",
    "trancado": false,
    "somente_admin": false,
    "total_participantes": 120,
    "participantes": [
      { "telefone": "5511999999999", "is_admin": true, "is_superadmin": true },
      { "telefone": "5511988887777", "is_admin": false, "is_superadmin": false }
    ]
  }
}

GET

`listar_participantes_grupo`

Retorna a relação de telefones e papéis de todos os membros participantes de um grupo.

Campo	Tipo	Obrigatório	Descrição
`token`	`string`	sim	Seu token da API VIP.
`device_id`	`string`	sim	Identificador da instância.
`id_grupo`	`string`	sim	JID do grupo (`@g.us`).

Exemplo cURL

curl "http://109.199.96.201/gowa-alunos/api.php?acao=listar_participantes_grupo&device_id=SEU_DEVICE_ID&id_grupo=120363025492928192@g.us&token=SEU_TOKEN"

Exemplo de Resposta

{
  "ok": true,
  "participantes": [
    { "telefone": "5511999999999", "is_admin": true },
    { "telefone": "5511988887777", "is_admin": false }
  ]
}

POST

`enviar_msg_grupo`

Envia mensagens de texto ou mídia para um grupo. Com o parâmetro opcional mentions, você notifica (marca) números específicos sem precisar digitar explicitamente @número no corpo do texto. Também aceita os mesmos campos de enviar_midia (como tipo, conteudo_base64 e nome_arquivo).

Campo	Tipo	Obrigatório	Descrição
`token`	`string`	sim	Seu token da API VIP.
`device_id`	`string`	sim	Identificador da instância.
`id_grupo`	`string`	sim	JID do grupo (`@g.us`).
`mensagem`	`string`	sim*	Texto da mensagem (obrigatório para texto ou quando enviado com mídia).
`mentions`	`array`	não	Lista de telefones a marcar/notificar, ex: `["5511999999999"]`.
`tipo`	`string`	não	Para envio de mídia: `image`, `audio`, `file`, `video` ou `sticker`.
`conteudo_base64`	`string`	não	Conteúdo do arquivo em Base64 (quando enviar mídia).
`nome_arquivo`	`string`	não	Nome do arquivo (ex: `comunicado.pdf`).

Exemplo cURL

curl -X POST "http://109.199.96.201/gowa-alunos/api.php?acao=enviar_msg_grupo" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "SEU_TOKEN",
    "device_id": "SEU_DEVICE_ID",
    "id_grupo": "120363025492928192@g.us",
    "mensagem": "Atenção a todos os membros: a aula de hoje começa às 20h!",
    "mentions": ["5511999999999", "5511988887777"]
  }'

Exemplo de Resposta

{
  "code": "SUCCESS",
  "message": "Mensagem de grupo enviada com sucesso.",
  "results": {
    "message_id": "3EB0D498112C"
  }
}

POST

`criar_grupo`

Cria um novo grupo no WhatsApp e adiciona os contatos informados como participantes iniciais.

Campo	Tipo	Obrigatório	Descrição
`token`	`string`	sim	Seu token da API VIP.
`device_id`	`string`	sim	Identificador da instância.
`titulo`	`string`	sim	Nome / assunto do novo grupo.
`participantes`	`array`	sim	Lista de telefones dos contatos iniciais a serem adicionados.

Exemplo cURL

curl -X POST "http://109.199.96.201/gowa-alunos/api.php?acao=criar_grupo" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "SEU_TOKEN",
    "device_id": "SEU_DEVICE_ID",
    "titulo": "Turma de Robótica 2026",
    "participantes": ["5511999999999", "5511988887777"]
  }'

Exemplo de Resposta

{
  "ok": true,
  "id_grupo": "120363039182736152@g.us",
  "message": "Grupo criado com sucesso."
}

POST

`entrar_grupo_link`

Faz a instância entrar em um grupo existente através de um link de convite público.

Campo	Tipo	Obrigatório	Descrição
`token`	`string`	sim	Seu token da API VIP.
`device_id`	`string`	sim	Identificador da instância.
`link`	`string`	sim	Link de convite do grupo (ex: `https://chat.whatsapp.com/AbCdEfGhIjK12345`).

Exemplo cURL

curl -X POST "http://109.199.96.201/gowa-alunos/api.php?acao=entrar_grupo_link" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "SEU_TOKEN",
    "device_id": "SEU_DEVICE_ID",
    "link": "https://chat.whatsapp.com/AbCdEfGhIjK12345"
  }'

Exemplo de Resposta

{
  "ok": true,
  "id_grupo": "120363025492928192@g.us",
  "message": "Entrou no grupo com sucesso."
}

GET

`info_grupo_link`

Consulta metadados e informações básicas de um grupo a partir do link de convite sem precisar entrar nele.

Campo	Tipo	Obrigatório	Descrição
`token`	`string`	sim	Seu token da API VIP.
`device_id`	`string`	sim	Identificador da instância.
`link`	`string`	sim	Link de convite (`https://chat.whatsapp.com/...`).

Exemplo cURL

curl "http://109.199.96.201/gowa-alunos/api.php?acao=info_grupo_link&device_id=SEU_DEVICE_ID&link=https://chat.whatsapp.com/AbCdEfGhIjK12345&token=SEU_TOKEN"

Exemplo de Resposta

{
  "ok": true,
  "grupo": {
    "id_grupo": "120363025492928192@g.us",
    "nome": "Turma de Python e Automação",
    "total_participantes": 45,
    "criador": "5511999999999"
  }
}

POST

`sair_grupo`

Faz com que a instância saia definitivamente do grupo especificado.

Campo	Tipo	Obrigatório	Descrição
`token`	`string`	sim	Seu token da API VIP.
`device_id`	`string`	sim	Identificador da instância.
`id_grupo`	`string`	sim	JID do grupo (`@g.us`).

Exemplo cURL

curl -X POST "http://109.199.96.201/gowa-alunos/api.php?acao=sair_grupo" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "SEU_TOKEN",
    "device_id": "SEU_DEVICE_ID",
    "id_grupo": "120363025492928192@g.us"
  }'

Exemplo de Resposta

{
  "ok": true,
  "message": "Saiu do grupo com sucesso."
}

POST

`definir_nome_grupo`

Altera o assunto / nome de exibição do grupo (requer permissão de administrador se o grupo estiver trancado).

Campo	Tipo	Obrigatório	Descrição
`token`	`string`	sim	Seu token da API VIP.
`device_id`	`string`	sim	Identificador da instância.
`id_grupo`	`string`	sim	JID do grupo (`@g.us`).
`nome`	`string`	sim	Novo nome do grupo.

Exemplo cURL

curl -X POST "http://109.199.96.201/gowa-alunos/api.php?acao=definir_nome_grupo" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "SEU_TOKEN",
    "device_id": "SEU_DEVICE_ID",
    "id_grupo": "120363025492928192@g.us",
    "nome": "Comunidade VIP EditaCódigo 2026"
  }'

Exemplo de Resposta

{
  "ok": true,
  "message": "Nome do grupo alterado com sucesso."
}

POST

`definir_topico_grupo`

Altera a descrição / tópico fixado do grupo.

Campo	Tipo	Obrigatório	Descrição
`token`	`string`	sim	Seu token da API VIP.
`device_id`	`string`	sim	Identificador da instância.
`id_grupo`	`string`	sim	JID do grupo (`@g.us`).
`topico`	`string`	sim	Nova descrição/tópico do grupo.

Exemplo cURL

curl -X POST "http://109.199.96.201/gowa-alunos/api.php?acao=definir_topico_grupo" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "SEU_TOKEN",
    "device_id": "SEU_DEVICE_ID",
    "id_grupo": "120363025492928192@g.us",
    "topico": "Regras: Seja respeitoso, sem spam, tire dúvidas das aulas."
  }'

Exemplo de Resposta

{
  "ok": true,
  "message": "Tópico do grupo atualizado com sucesso."
}

POST

`foto_grupo`

Altera a imagem de foto/avatar do grupo.

Campo	Tipo	Obrigatório	Descrição
`token`	`string`	sim	Seu token da API VIP.
`device_id`	`string`	sim	Identificador da instância.
`id_grupo`	`string`	sim	JID do grupo (`@g.us`).
`conteudo_base64`	`string`	sim	Imagem em formato Base64.
`nome_arquivo`	`string`	não	Nome da imagem (ex: `avatar.jpg`).

Exemplo cURL

curl -X POST "http://109.199.96.201/gowa-alunos/api.php?acao=foto_grupo" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "SEU_TOKEN",
    "device_id": "SEU_DEVICE_ID",
    "id_grupo": "120363025492928192@g.us",
    "conteudo_base64": "iVBORw0KGgoAAAANSUhEUgAA...",
    "nome_arquivo": "icone-grupo.jpg"
  }'

Exemplo de Resposta

{
  "ok": true,
  "message": "Foto do grupo alterada com sucesso."
}

POST

`definir_trancado_grupo`

Define as permissões de edição das informações do grupo (nome, foto e descrição). Requer que a instância seja administradora do grupo.

Campo	Tipo	Obrigatório	Descrição
`token`	`string`	sim	Seu token da API VIP.
`device_id`	`string`	sim	Identificador da instância.
`id_grupo`	`string`	sim	JID do grupo (`@g.us`).
`trancado`	`bool`	sim	`true` = somente administradores podem editar dados do grupo; `false` = todos os participantes podem.

Exemplo cURL

curl -X POST "http://109.199.96.201/gowa-alunos/api.php?acao=definir_trancado_grupo" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "SEU_TOKEN",
    "device_id": "SEU_DEVICE_ID",
    "id_grupo": "120363025492928192@g.us",
    "trancado": true
  }'

Exemplo de Resposta

{
  "ok": true,
  "message": "Configuração de restrição do grupo atualizada."
}

POST

`definir_anuncio_grupo`

Define se o grupo funciona no formato canal/somente anúncios. Requer que a instância seja administradora do grupo.

Campo	Tipo	Obrigatório	Descrição
`token`	`string`	sim	Seu token da API VIP.
`device_id`	`string`	sim	Identificador da instância.
`id_grupo`	`string`	sim	JID do grupo (`@g.us`).
`somente_admin`	`bool`	sim	`true` = somente administradores podem enviar mensagens; `false` = todos os participantes podem enviar.

Exemplo cURL

curl -X POST "http://109.199.96.201/gowa-alunos/api.php?acao=definir_anuncio_grupo" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "SEU_TOKEN",
    "device_id": "SEU_DEVICE_ID",
    "id_grupo": "120363025492928192@g.us",
    "somente_admin": true
  }'

Exemplo de Resposta

{
  "ok": true,
  "message": "Configuração de envio de mensagens do grupo atualizada."
}

POST

`gerenciar_participantes_grupo`

Adiciona novos participantes, remove membros, promove participantes a administrador do grupo ou rebaixa administradores de volta a participantes comuns.

Campo	Tipo	Obrigatório	Descrição
`token`	`string`	sim	Seu token da API VIP.
`device_id`	`string`	sim	Identificador da instância.
`id_grupo`	`string`	sim	JID do grupo (`@g.us`).
`participantes`	`array`	sim	Lista de telefones dos participantes a alterar.
`acao_participante`	`string`	sim	Uma das seguintes ações: `add` (adicionar), `remove` (remover), `promote` (promover a administrador) ou `demote` (rebaixar a membro comum).

Exemplo cURL

curl -X POST "http://109.199.96.201/gowa-alunos/api.php?acao=gerenciar_participantes_grupo" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "SEU_TOKEN",
    "device_id": "SEU_DEVICE_ID",
    "id_grupo": "120363025492928192@g.us",
    "participantes": ["5511999999999"],
    "acao_participante": "promote"
  }'

Exemplo de Resposta

{
  "ok": true,
  "message": "Participantes atualizados com sucesso."
}

GET

`link_convite_grupo`

Retorna o link de convite público atual do grupo. Opcionalmente revoga o link anterior e gera um novo código de convite se resetar=true for enviado.

Campo	Tipo	Obrigatório	Descrição
`token`	`string`	sim	Seu token da API VIP.
`device_id`	`string`	sim	Identificador da instância.
`id_grupo`	`string`	sim	JID do grupo (`@g.us`).
`resetar`	`bool`	não	Se `true`, revoga o link anterior e gera um novo (padrão: `false`).

Exemplo cURL

curl "http://109.199.96.201/gowa-alunos/api.php?acao=link_convite_grupo&device_id=SEU_DEVICE_ID&id_grupo=120363025492928192@g.us&token=SEU_TOKEN"

Exemplo de Resposta

{
  "ok": true,
  "link": "https://chat.whatsapp.com/AbCdEfGhIjK12345",
  "codigo": "AbCdEfGhIjK12345"
}

GET

`listar_pedidos_entrada_grupo`

Lista as solicitações pendentes de entrada em grupos que possuem o recurso de aprovação manual por administradores ativado.

Campo	Tipo	Obrigatório	Descrição
`token`	`string`	sim	Seu token da API VIP.
`device_id`	`string`	sim	Identificador da instância.
`id_grupo`	`string`	sim	JID do grupo (`@g.us`).

Exemplo cURL

curl "http://109.199.96.201/gowa-alunos/api.php?acao=listar_pedidos_entrada_grupo&device_id=SEU_DEVICE_ID&id_grupo=120363025492928192@g.us&token=SEU_TOKEN"

Exemplo de Resposta

{
  "ok": true,
  "pedidos": [
    {
      "telefone": "5511977776666",
      "solicitado_em": "2026-09-20 18:30:00"
    }
  ]
}

POST

`responder_pedido_entrada_grupo`

Aprova ou rejeita solicitações pendentes de novos participantes para entrar no grupo.

Campo	Tipo	Obrigatório	Descrição
`token`	`string`	sim	Seu token da API VIP.
`device_id`	`string`	sim	Identificador da instância.
`id_grupo`	`string`	sim	JID do grupo (`@g.us`).
`participantes`	`array`	sim	Lista de telefones cujos pedidos serão respondidos.
`acao_pedido`	`string`	sim	`approve` para aceitar no grupo ou `reject` para recusar.

Exemplo cURL

curl -X POST "http://109.199.96.201/gowa-alunos/api.php?acao=responder_pedido_entrada_grupo" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "SEU_TOKEN",
    "device_id": "SEU_DEVICE_ID",
    "id_grupo": "120363025492928192@g.us",
    "participantes": ["5511977776666"],
    "acao_pedido": "approve"
  }'

Exemplo de Resposta

{
  "ok": true,
  "message": "Solicitações respondidas com sucesso."
}

👤 Conta & Perfil

Consulte dados de contas, valide números no WhatsApp antes de disparos, altere nome e foto da sua instância, veja perfis comerciais e canais seguidos.

GET

`verificar_numero_whatsapp`

Valida se determinado número de telefone possui conta cadastrada e ativa no WhatsApp.

Recomendação de ouro: Sempre utilize esta ação para higienizar sua base de contatos antes de realizar disparos automatizados, evitando mensagens perdidas em números inexistentes.

Campo	Tipo	Obrigatório	Descrição
`token`	`string`	sim	Seu token da API VIP.
`device_id`	`string`	sim	Identificador da instância.
`telefone`	`string`	sim	Número a ser checado (DDI + DDD + número).

Exemplo cURL

curl "http://109.199.96.201/gowa-alunos/api.php?acao=verificar_numero_whatsapp&device_id=SEU_DEVICE_ID&telefone=5511999999999&token=SEU_TOKEN"

Exemplo de Resposta

{
  "ok": true,
  "is_on_whatsapp": true,
  "jid": "5511999999999@s.whatsapp.net"
}

GET

`info_usuario`

Retorna informações públicas do perfil de um usuário: nome público (push name), URL da foto de perfil e se a conta é do tipo WhatsApp Business.

Campo	Tipo	Obrigatório	Descrição
`token`	`string`	sim	Seu token da API VIP.
`device_id`	`string`	sim	Identificador da instância.
`telefone`	`string`	sim	Número do usuário consultado.

Exemplo cURL

curl "http://109.199.96.201/gowa-alunos/api.php?acao=info_usuario&device_id=SEU_DEVICE_ID&telefone=5511999999999&token=SEU_TOKEN"

Exemplo de Resposta

{
  "ok": true,
  "usuario": {
    "telefone": "5511999999999",
    "nome": "Carlos Mendes",
    "foto_url": "https://pps.whatsapp.net/v/...",
    "is_business": false
  }
}

POST

`trocar_nome_exibicao`

Altera o nome de exibição público da própria instância (o nome que as pessoas verão ao interagir com o seu número).

Campo	Tipo	Obrigatório	Descrição
`token`	`string`	sim	Seu token da API VIP.
`device_id`	`string`	sim	Identificador da instância.
`nome`	`string`	sim	Novo nome de exibição.

Exemplo cURL

curl -X POST "http://109.199.96.201/gowa-alunos/api.php?acao=trocar_nome_exibicao" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "SEU_TOKEN",
    "device_id": "SEU_DEVICE_ID",
    "nome": "Suporte EditaCódigo"
  }'

Exemplo de Resposta

{
  "ok": true,
  "message": "Nome de exibição alterado com sucesso."
}

POST

`trocar_foto_perfil_propria`

Atualiza a foto de perfil do WhatsApp conectada à sua instância.

Campo	Tipo	Obrigatório	Descrição
`token`	`string`	sim	Seu token da API VIP.
`device_id`	`string`	sim	Identificador da instância.
`conteudo_base64`	`string`	sim	Imagem em formato Base64.
`nome_arquivo`	`string`	não	Nome da foto (ex: `perfil.jpg`).

Exemplo cURL

curl -X POST "http://109.199.96.201/gowa-alunos/api.php?acao=trocar_foto_perfil_propria" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "SEU_TOKEN",
    "device_id": "SEU_DEVICE_ID",
    "conteudo_base64": "/9j/4AAQSkZJRgABAQEASABIAAD...",
    "nome_arquivo": "perfil.jpg"
  }'

Exemplo de Resposta

{
  "ok": true,
  "message": "Foto de perfil atualizada com sucesso."
}

GET

`perfil_comercial`

Consulta detalhes comerciais avançados de um número de WhatsApp Business (descrição da empresa, categoria, endereço físico, e-mail e websites).

Campo	Tipo	Obrigatório	Descrição
`token`	`string`	sim	Seu token da API VIP.
`device_id`	`string`	sim	Identificador da instância.
`telefone`	`string`	sim	Número da conta comercial a consultar.

Exemplo cURL

curl "http://109.199.96.201/gowa-alunos/api.php?acao=perfil_comercial&device_id=SEU_DEVICE_ID&telefone=5511999999999&token=SEU_TOKEN"

Exemplo de Resposta

{
  "ok": true,
  "perfil": {
    "descricao": "Plataforma de cursos e tutoriais de programação.",
    "categoria": "Educação / Cursos",
    "email": "contato@editacodigo.com.br",
    "websites": ["https://www.editacodigo.com.br"]
  }
}

GET

`listar_newsletters`

Lista os canais e newsletters do WhatsApp que a conta da instância segue atualmente.

Campo	Tipo	Obrigatório	Descrição
`token`	`string`	sim	Seu token da API VIP.
`device_id`	`string`	sim	Identificador da instância.

Exemplo cURL

curl "http://109.199.96.201/gowa-alunos/api.php?acao=listar_newsletters&device_id=SEU_DEVICE_ID&token=SEU_TOKEN"

Exemplo de Resposta

{
  "ok": true,
  "newsletters": [
    {
      "id": "120363158912345@newsletter",
      "nome": "Canal Notícias EditaCódigo",
      "seguidores": 3540
    }
  ]
}

GET

`listar_contatos`

Lista os contatos sincronizados na agenda e histórico da instância.

Campo	Tipo	Obrigatório	Descrição
`token`	`string`	sim	Seu token da API VIP.
`device_id`	`string`	sim	Identificador da instância.

Exemplo cURL

curl "http://109.199.96.201/gowa-alunos/api.php?acao=listar_contatos&device_id=SEU_DEVICE_ID&token=SEU_TOKEN"

Exemplo de Resposta

{
  "ok": true,
  "contatos": [
    {
      "jid": "5511999999999@s.whatsapp.net",
      "nome": "Mariana Santos",
      "telefone": "5511999999999"
    }
  ]
}

🗂️ Conversas & Histórico

Acesse a lista de conversas ativas, consulte histórico de mensagens trocadas, fixe ou arquive chats e configure temporizadores para mensagens temporárias.

GET

`listar_conversas`

Retorna a relação de conversas (chats individuais e grupos) ativas da instância, com suporte a paginação e busca por nome ou número.

Campo	Tipo	Obrigatório	Descrição
`token`	`string`	sim	Seu token da API VIP.
`device_id`	`string`	sim	Identificador da instância.
`limite`	`int`	não	Quantidade de conversas por página (padrão: `20`).
`offset`	`int`	não	Deslocamento de paginação (padrão: `0`).
`busca`	`string`	não	Termo de filtro para pesquisar por nome ou número.

Exemplo cURL

curl "http://109.199.96.201/gowa-alunos/api.php?acao=listar_conversas&device_id=SEU_DEVICE_ID&limite=20&token=SEU_TOKEN"

Exemplo de Resposta

{
  "ok": true,
  "conversas": [
    {
      "chat_jid": "5511999999999@s.whatsapp.net",
      "nome": "Mariana Santos",
      "nao_lidas": 0,
      "fixada": true,
      "arquivada": false,
      "ultima_mensagem": "Obrigada pelo suporte!",
      "timestamp": 1726915200
    }
  ]
}

GET

`historico_conversa`

Retorna o histórico de mensagens trocadas em uma conversa específica (individual ou grupo).

Campo	Tipo	Obrigatório	Descrição
`token`	`string`	sim	Seu token da API VIP.
`device_id`	`string`	sim	Identificador da instância.
`chat_jid`	`string`	sim	Telefone com DDI + DDD (ex: `5511999999999`) ou ID do grupo (`...g.us`).
`limite`	`int`	não	Quantidade de mensagens a retornar (padrão: `50`).
`offset`	`int`	não	Deslocamento de paginação (padrão: `0`).

Exemplo cURL

curl "http://109.199.96.201/gowa-alunos/api.php?acao=historico_conversa&device_id=SEU_DEVICE_ID&chat_jid=5511999999999&limite=20&token=SEU_TOKEN"

Exemplo de Resposta

{
  "ok": true,
  "mensagens": [
    {
      "id_mensagem": "3EB07A65B901C4E8",
      "from": "5511999999999",
      "is_from_me": false,
      "mensagem": "Olá! Preciso de ajuda.",
      "tipo": "text",
      "timestamp": 1726915100
    },
    {
      "id_mensagem": "3EB08B12C4509F71",
      "from": "5511988887777",
      "is_from_me": true,
      "mensagem": "Olá Mariana, em que posso te ajudar hoje?",
      "tipo": "text",
      "timestamp": 1726915150
    }
  ]
}

POST

`fixar_conversa`

Fixa ou desafixa um chat no topo da lista de conversas da instância.

Campo	Tipo	Obrigatório	Descrição
`token`	`string`	sim	Seu token da API VIP.
`device_id`	`string`	sim	Identificador da instância.
`chat_jid`	`string`	sim	Telefone do contato ou ID de grupo.
`fixar`	`bool`	não	`true` para fixar no topo, `false` para desafixar (padrão: `true`).

Exemplo cURL

curl -X POST "http://109.199.96.201/gowa-alunos/api.php?acao=fixar_conversa" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "SEU_TOKEN",
    "device_id": "SEU_DEVICE_ID",
    "chat_jid": "5511999999999",
    "fixar": true
  }'

Exemplo de Resposta

{
  "ok": true,
  "message": "Status de fixação do chat atualizado."
}

POST

`arquivar_conversa`

Move um chat para as conversas arquivadas ou desarquiva de volta para a listagem principal.

Campo	Tipo	Obrigatório	Descrição
`token`	`string`	sim	Seu token da API VIP.
`device_id`	`string`	sim	Identificador da instância.
`chat_jid`	`string`	sim	Telefone do contato ou ID de grupo.
`arquivar`	`bool`	não	`true` para arquivar, `false` para desarquivar (padrão: `true`).

Exemplo cURL

curl -X POST "http://109.199.96.201/gowa-alunos/api.php?acao=arquivar_conversa" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "SEU_TOKEN",
    "device_id": "SEU_DEVICE_ID",
    "chat_jid": "5511999999999",
    "arquivar": true
  }'

Exemplo de Resposta

{
  "ok": true,
  "message": "Status de arquivamento atualizado."
}

POST

`definir_timer_sumico`

Configura o temporizador de mensagens temporárias para a conversa. As mensagens enviadas após essa ativação desaparecerão automaticamente após o tempo estipulado.

Valores comuns: 86400 (24 horas / 1 dia), 604800 (7 dias), 7776000 (90 dias) ou 0 (desativar temporizador).

Campo	Tipo	Obrigatório	Descrição
`token`	`string`	sim	Seu token da API VIP.
`device_id`	`string`	sim	Identificador da instância.
`chat_jid`	`string`	sim	Telefone do contato ou ID de grupo.
`segundos`	`int`	sim	Duração em segundos até a mensagem expirar (`0` para desativar).

Exemplo cURL

curl -X POST "http://109.199.96.201/gowa-alunos/api.php?acao=definir_timer_sumico" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "SEU_TOKEN",
    "device_id": "SEU_DEVICE_ID",
    "chat_jid": "5511999999999",
    "segundos": 86400
  }'

Exemplo de Resposta

{
  "ok": true,
  "message": "Timer de mensagens temporárias configurado."
}

🤖 Guia Rápido para Construir com Ajuda de IA / LLM

Prompt Pronto Como orientar seu assistente de IA (Claude, ChatGPT, Cursor, Copilot)

Se você utiliza modelos de linguagem (como Claude 3.7 / 3.5 Sonnet, ChatGPT GPT-4o, GitHub Copilot ou Cursor) para acelerar a escrita do código de integração, copie e cole o bloco de instruções abaixo no prompt inicial do seu projeto.

IAs frequentemente tentam adivinhar nomes de endpoints em inglês (como send_message, group_id ou cabeçalhos Bearer) quando não têm restrições explícitas. Ao fornecer a diretriz exata abaixo, o modelo utilizará estritamente a URL base, os nomes em português e o formato JSON da nossa API, sem alucinações.

Instrução para a IA

Você vai me ajudar a integrar com uma API de WhatsApp. Use SOMENTE as ações e campos da lista abaixo — não invente nome de ação, nem de campo, nem endpoint alternativo. Quando eu pedir uma funcionalidade, escolha a ação certa desta lista de acordo com o que eu descrever e implemente usando exatamente esses nomes. ENDPOINT (sempre o mesmo, só troca o "acao" e os campos): http://109.199.96.201/gowa-alunos/api.php?acao=NOME_DA_ACAO REGRAS GERAIS: - Ações de escrita: POST, corpo JSON. - Ações de leitura (marcadas GET): podem ir por querystring. - Quase toda ação leva "token" (meu token da API) + "device_id" (id da minha instância) — só as de "Conta/perfil" pedem device_id mas não giram em torno de outro contato específico, e leitura pode variar GET/POST. - Nomes de campo são em português (ex: id_grupo, não group_id; conteudo_base64, não file_base64). - Resposta sempre tem "ok" (true/false) e, se der erro, "erro" com o motivo. - id de grupo sempre termina em "@g.us". LISTA COMPLETA DE AÇÕES (ação: campos além de token/device_id — o que faz): Instância: - status_instancia (GET): (nenhum extra) — diz se o WhatsApp está conectado - login_instancia (GET): (nenhum extra) — gera/renova o QR Code - logout_instancia (POST): (nenhum extra) — desconecta sem apagar a instância - atualizar_instancia (POST): webhook_url?, cron_url? — configura URL que recebe mensagens em tempo real (webhook_url) e URL de ping periódico (cron_url); "" apaga, campo ausente não mexe - minhas_instancias (GET): (nenhum extra, só token) — lista todas as instâncias da conta com status Mensagens: - enviar_mensagem (POST): telefone, mensagem - enviar_midia (POST): telefone, tipo (image|audio|file|video|sticker), conteudo_base64, nome_arquivo?, legenda? - enviar_enquete (POST): telefone, pergunta, opcoes[], max_respostas? - enviar_contato (POST): telefone, nome_contato, telefone_contato - enviar_link (POST): telefone, link, legenda? - enviar_localizacao (POST): telefone, latitude, longitude Gerenciar mensagem já enviada/recebida (todas: id_mensagem, telefone): - reagir_mensagem (POST): + emoji - revogar_mensagem (POST): apaga pra todo mundo (só funciona se foi essa instância que enviou) - apagar_mensagem_local (POST): apaga só da visão desta instância - editar_mensagem (POST): + mensagem (texto novo) - marcar_lida (POST): marca como lida - favoritar_mensagem (POST): + favoritar (bool, default true) - encaminhar_mensagem (POST): usa telefone_destino em vez de telefone - baixar_midia_mensagem (GET ou POST): devolve o arquivo de uma mensagem recebida Grupos: - listar_grupos (GET): (nenhum extra) — todos os grupos que a instância participa - info_grupo (GET): id_grupo — nome, tópico, trancado, participantes - listar_participantes_grupo (GET): id_grupo - enviar_msg_grupo (POST): id_grupo, mensagem, mentions[]? (também aceita campos de mídia) - criar_grupo (POST): titulo, participantes[] - entrar_grupo_link (POST): link - info_grupo_link (GET): link — vê o grupo sem entrar - sair_grupo (POST): id_grupo - definir_nome_grupo (POST): id_grupo, nome - definir_topico_grupo (POST): id_grupo, topico - foto_grupo (POST): id_grupo, conteudo_base64, nome_arquivo? - definir_trancado_grupo (POST): id_grupo, trancado (bool) - definir_anuncio_grupo (POST): id_grupo, somente_admin (bool) - gerenciar_participantes_grupo (POST): id_grupo, participantes[], acao_participante (add|remove|promote|demote) - link_convite_grupo (GET): id_grupo, resetar (bool) - listar_pedidos_entrada_grupo (GET): id_grupo - responder_pedido_entrada_grupo (POST): id_grupo, participantes[], acao_pedido (approve|reject) Conta / perfil: - verificar_numero_whatsapp (GET): telefone — {"is_on_whatsapp": true|false} - info_usuario (GET): telefone - trocar_nome_exibicao (POST): nome - trocar_foto_perfil_propria (POST): conteudo_base64, nome_arquivo? - perfil_comercial (GET): telefone - listar_newsletters (GET): (nenhum extra) Conversas: - listar_conversas (GET): limite?, offset?, busca? - historico_conversa (GET): chat_jid, limite?, offset? - fixar_conversa (POST): chat_jid, fixar (bool) - arquivar_conversa (POST): chat_jid, arquivar (bool) - definir_timer_sumico (POST): chat_jid, segundos (86400=1 dia, 604800=7 dias, 7776000=90 dias, 0=desativa) Antes de escrever o código, confirme comigo qual ação da lista acima resolve o que eu pedi, e não use nenhuma ação/campo que não esteja nesta lista.

Erros Comuns e Boas Práticas

Ao realizar requisições, sempre verifique o campo de status (ok: true ou code: "SUCCESS") para validar o sucesso da operação.

Erro Retornado	Causa Raiz	Como Solucionar
`"ação desconhecida"`	O valor informado no parâmetro `?acao=...` não existe ou foi digitado com grafia incorreta.	Consulte a tabela de ações e confirme a grafia exata (ex: `enviar_mensagem` e não `sendMessage`).
`"informe telefone e mensagem"`	Faltou enviar um dos campos obrigatórios exigidos pela ação.	Verifique a tabela de parâmetros da respectiva ação e envie todos os campos marcados como `sim`.
`"token ausente ou inválido"`	O token não foi informado ou não possui autorização para operar o `device_id` especificado.	Acesse a aba Instâncias, copie seu token VIP e certifique-se de que a instância pertence à sua conta.
`"instância desconectada"`	Tentativa de envio de mensagem em uma instância cujo WhatsApp foi deslogado ou cujo QR Code ainda não foi lido.	Chame `status_instancia` ou `login_instancia` para escanear novamente o QR Code.
`"permissão negada no grupo"`	A instância tentou alterar configurações de um grupo trancado sem ser administradora dele.	Promova a instância a administradora do grupo antes de tentar renomear, trancar ou alterar anúncios.
`"conteúdo base64 inválido"`	A string enviada no campo `conteudo_base64` não pôde ser decodificada pelo servidor.	Certifique-se de enviar a codificação base64 pura ou remova caracteres extras que corrompam os dados binários.

Recomendações e Boas Práticas de Integração

Formato dos Números de Telefone: O formato exigido em todos os endpoints é o padrão internacional com DDI (55 para o Brasil) + DDD (2 dígitos) + Número (8 ou 9 dígitos), contendo apenas números (sem espaços, parênteses ou traços). Exemplo correto: 5511999999999.
Validação Prévia de Números: Antes de disparar mensagens para uma lista de contatos, execute a ação verificar_numero_whatsapp. Números que não possuem WhatsApp consomem tempo de fila desnecessário.
Timeout de Mídia: Ao enviar arquivos pesados em base64 (vídeos, PDFs ou áudios), configure o timeout HTTP do seu cliente para ao menos 45 a 60 segundos.
Arquitetura de Webhook Resiliente: O endpoint configurado em webhook_url deve retornar HTTP 200 em menos de 3 segundos para liberar a fila de entrega. Delegue processamentos demorados (como salvar arquivos ou consultar bancos de dados externos) para filas assíncronas no seu backend.