Documentação API — Think Messenger

📖 Visão Geral

A API Think Messenger permite enviar e receber mensagens WhatsApp de forma programática. Integre seu sistema em minutos com nossa API REST simples e segura.

Base URL:

https://seu-dominio.com/api/v1

Todos os endpoints retornam JSON. Autenticação é feita via header X-API-Key.

🔐 Autenticação

Todas as requisições à API devem incluir o header X-API-Key com sua chave de API. A chave é gerada automaticamente ao criar sua instância e tem o prefixo tm_.

Headers

X-API-Key: tm_SuaChaveAquiGeradaAutomaticamente
Content-Type: application/json
        

⚠️

Importante: Sua API Key é exibida apenas uma vez ao ser gerada. Guarde-a em local seguro. Nunca a exponha em código front-end ou repositórios públicos.

⚡ Início Rápido

Em 3 passos simples você estará enviando mensagens:

Crie sua conta — Acesse o registro e crie sua conta.
Crie uma instância — No dashboard, crie uma nova instância e escaneie o QR Code com seu WhatsApp.
Envie sua primeira mensagem — Use a API Key da instância para fazer sua primeira chamada:

cURL

curl -X POST \
  "https://seu-dominio.com/api/v1/messages/send" \
  -H "X-API-Key: tm_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "5511999999999",
    "message": "Olá! 👋 Primeira mensagem via API!"
  }'
        

📱 Criar Instância

Instâncias representam um número WhatsApp conectado. Cada instância possui sua própria API Key, webhooks e configurações independentes.

Passo a passo

Acesse o Dashboard → Instâncias → Nova Instância
Defina um nome identificador (ex: "Atendimento", "Vendas")
Escolha a forma de pagamento (PIX ou Cartão de Crédito)
Após confirmação de pagamento, a instância será provisionada automaticamente
Copie sua API Key (exibida apenas uma vez!)

💡

Você pode criar múltiplas instâncias na mesma conta, cada uma com um número WhatsApp diferente.

🔗 Conectar WhatsApp

Após criar a instância, conecte seu WhatsApp escaneando o QR Code:

Na página da instância, clique em "Conectar"
Um QR Code será gerado na tela
Abra o WhatsApp no seu celular → Aparelhos Conectados → Conectar Aparelho
Escaneie o QR Code
O status mudará para Conectado ✅

Status possíveis da instância:

Status	Descrição
`connected`	WhatsApp conectado e pronto para uso
`connecting`	Aguardando escaneamento do QR Code
`disconnected`	WhatsApp desconectado
`pending_payment`	Aguardando confirmação de pagamento

💬 Enviar Texto

POST /api/v1/messages/send

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

Parâmetros (Body JSON)

Campo	Tipo		Descrição
`phone`	string	Obrigatório	Número do destinatário com DDI+DDD (ex: `5511999999999`)
`message`	string	Obrigatório	Texto da mensagem (máx. 5000 caracteres)

Exemplo

cURL
curl -X POST \
  "https://seu-dominio.com/api/v1/messages/send" \
  -H "X-API-Key: tm_sua_chave" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "5511999999999",
    "message": "Olá! Como posso ajudar?"
  }'

PHP
$response = Http::withHeaders([
    'X-API-Key' => 'tm_sua_chave',
])->post('https://seu-dominio.com/api/v1/messages/send', [
    'phone'   => '5511999999999',
    'message' => 'Olá! Como posso ajudar?',
]);

JavaScript
const res = await fetch('https://seu-dominio.com/api/v1/messages/send', {
  method: 'POST',
  headers: {
    'X-API-Key': 'tm_sua_chave',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    phone: '5511999999999',
    message: 'Olá! Como posso ajudar?',
  }),
});

Python
import requests

response = requests.post(
    'https://seu-dominio.com/api/v1/messages/send',
    headers={'X-API-Key': 'tm_sua_chave'},
    json={'phone': '5511999999999', 'message': 'Olá!'},
)

Resposta de Sucesso 200 OK

JSON
{
  "success": true,
  "message_id": "3EB0A1B2C3D4E5F6",
  "phone": "5511999999999",
  "status": "sent"
}

📎 Enviar Mídia

POST /api/v1/messages/send-media

Envia imagem, vídeo, áudio ou documento via URL pública.

Parâmetros (Body JSON)

Campo	Tipo		Descrição
`phone`	string	Obrigatório	Número com DDI+DDD
`media_url`	string	Obrigatório	URL pública do arquivo de mídia
`media_type`	string	Obrigatório	`image`, `video`, `audio` ou `document`
`caption`	string	Opcional	Legenda da mídia (máx. 1000 caracteres)

Exemplos por tipo

cURL — Imagem
curl -X POST "https://seu-dominio.com/api/v1/messages/send-media" \
  -H "X-API-Key: tm_sua_chave" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "5511999999999",
    "media_url": "https://exemplo.com/foto.jpg",
    "media_type": "image",
    "caption": "Veja esta foto! 📸"
  }'

cURL — Vídeo
curl -X POST "https://seu-dominio.com/api/v1/messages/send-media" \
  -H "X-API-Key: tm_sua_chave" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "5511999999999",
    "media_url": "https://exemplo.com/video.mp4",
    "media_type": "video",
    "caption": "Assista ao vídeo! 🎬"
  }'

cURL — Áudio
curl -X POST "https://seu-dominio.com/api/v1/messages/send-media" \
  -H "X-API-Key: tm_sua_chave" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "5511999999999",
    "media_url": "https://exemplo.com/audio.mp3",
    "media_type": "audio"
  }'

cURL — Documento
curl -X POST "https://seu-dominio.com/api/v1/messages/send-media" \
  -H "X-API-Key: tm_sua_chave" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "5511999999999",
    "media_url": "https://exemplo.com/relatorio.pdf",
    "media_type": "document",
    "caption": "Segue o relatório em anexo"
  }'

Resposta de Sucesso 200 OK

JSON
{
  "success": true,
  "message_id": "3EB0A1B2C3D4E5F6",
  "phone": "5511999999999",
  "media_type": "image",
  "status": "sent"
}

✏️ Editar Mensagem

PUT /api/v1/messages/edit

Edita o conteúdo de uma mensagem já enviada. O destinatário verá a mensagem atualizada com indicação de "editada".

Parâmetros (Body JSON)

Campo	Tipo		Descrição
`phone`	string	Obrigatório	Número do destinatário com DDI+DDD
`message_id`	string	Obrigatório	ID da mensagem original (retornado no `message_id` ao enviar)
`message`	string	Obrigatório	Novo conteúdo da mensagem (máx. 5000 caracteres)

Exemplo

cURL
curl -X PUT \
  "https://seu-dominio.com/api/v1/messages/edit" \
  -H "X-API-Key: tm_sua_chave" \
  -H "Content-Type: application/json" \
  -d '{  
    "phone": "5511999999999",
    "message_id": "BAE5EABBD912C4E2",
    "message": "Texto corrigido da mensagem"
  }'

Resposta de Sucesso 200 OK

JSON
{
  "success": true,
  "message_id": "BAE5EABBD912C4E2",
  "phone": "5511999999999",
  "status": "edited"
}

⚠️

Importante: Somente mensagens enviadas pela instância (fromMe: true) podem ser editadas. Guarde o message_id retornado ao enviar para usar neste endpoint.

🗑️ Apagar Mensagem

DELETE /api/v1/messages/delete

Apaga uma mensagem para todos os participantes da conversa. Equivale à ação "Apagar para todos" no WhatsApp.

Parâmetros (Body JSON)

Campo	Tipo		Descrição
`phone`	string	Obrigatório	Número do destinatário com DDI+DDD
`message_id`	string	Obrigatório	ID da mensagem a apagar
`from_me`	boolean	Opcional	Se a mensagem foi enviada pela instância (padrão: `true`)

Exemplo

cURL
curl -X DELETE \
  "https://seu-dominio.com/api/v1/messages/delete" \
  -H "X-API-Key: tm_sua_chave" \
  -H "Content-Type: application/json" \
  -d '{  
    "phone": "5511999999999",
    "message_id": "BAE5EABBD912C4E2"
  }'

Resposta de Sucesso 200 OK

JSON
{
  "success": true,
  "message_id": "BAE5EABBD912C4E2",
  "phone": "5511999999999",
  "status": "deleted"
}

💡

Dica: O WhatsApp possui um limite de tempo para apagar mensagens (geralmente até ~2 dias). Mensagens mais antigas não poderão ser apagadas.

🔔 Webhooks — Configuração

Webhooks permitem que seu sistema receba notificações em tempo real sobre mensagens e eventos. Configure URLs diferentes para cada tipo de evento no painel da instância.

URLs Configuráveis

Campo	Evento	Descrição
`webhook_url`	Fallback geral	URL usada quando não há URL específica para o evento
`webhook_messages_upsert`	Mensagem recebida	Disparado quando uma mensagem é recebida na instância
`webhook_send_message`	Mensagem enviada	Disparado quando uma mensagem é enviada pela API
`webhook_presence_update`	Status de presença	Disparado quando o status online/offline de um contato muda
`webhook_messages_update`	Status de entrega/leitura	Disparado quando uma mensagem é entregue (✓✓) ou lida (✓✓ azul)

💡

Se uma URL específica não estiver configurada, o evento será enviado para o webhook_url (fallback). Se nenhum estiver configurado, o evento será descartado silenciosamente.

📡 Webhooks — Eventos

Seu endpoint receberá requisições POST com payloads JSON normalizados. Think Messenger abstrai toda a complexidade do provedor subjacente.

Eventos disponíveis

Evento	Descrição
`message.received`	Mensagem recebida de um contato
`message.sent`	Confirmação de mensagem enviada
`presence.update`	Mudança de status online/offline
`message.status`	Status de entrega/leitura da mensagem (entregue, lida, reproduzida)

📦 Webhooks — Payloads

Mensagem de Texto (recebida)

JSON — message.received (text)
{
  "event": "message.received",
  "instance": "Minha Instância",
  "timestamp": "2026-04-06T18:30:00-03:00",
  "message": {
    "id": "3EB0A1B2C3D4E5F6",
    "from_me": false,
    "phone": "5511999999999",
    "name": "João Silva",
    "is_group": false,
    "type": "text",
    "content": "Olá, preciso de ajuda!"
  }
}

Imagem recebida

JSON — message.received (image)
{
  "event": "message.received",
  "instance": "Minha Instância",
  "timestamp": "2026-04-06T18:31:00-03:00",
  "message": {
    "id": "3EB0B2C3D4E5F6A1",
    "from_me": false,
    "phone": "5511999999999",
    "name": "João Silva",
    "is_group": false,
    "type": "image",
    "content": "Legenda da foto",
    "mimetype": "image/jpeg"
  }
}

Tipos de mensagem suportados

type	Campos extras	Descrição
`text`	—	Mensagem de texto simples
`image`	`mimetype`	Imagem (JPEG, PNG, etc)
`video`	`mimetype`	Vídeo (MP4, etc)
`audio`	`mimetype`, `is_voice_note`	Áudio ou mensagem de voz
`document`	`mimetype`	Documento (PDF, DOC, etc)
`sticker`	—	Figurinha / Sticker
`contact`	—	Cartão de contato
`location`	`latitude`, `longitude`	Localização
`reaction`	`reacted_message_id`	Reação a mensagem

Payload de Presença

JSON — presence.update
{
  "event": "presence.update",
  "instance": "Minha Instância",
  "timestamp": "2026-04-06T18:32:00-03:00",
  "presence": {
    "phone": "5511999999999",
    "states": [
      { "phone": "5511999999999", "status": "available" }
    ]
  }
}

Payload de Status de Mensagem

JSON — message.status
{
  "event": "message.status",
  "instance": "Minha Instância",
  "timestamp": "2026-04-06T18:33:00-03:00",
  "status": {
    "message_id": "3EB0A1B2C3D4E5F6",
    "from_me": true,
    "phone": "5511999999999",
    "status": "read",
    "ack": 3
  }
}

Valores de `status` (ack)

ack	status	Descrição
`0`	`error`	Erro no envio
`1`	`server`	Mensagem chegou ao servidor WhatsApp
`2`	`delivered`	✓✓ Entregue no dispositivo do destinatário
`3`	`read`	✓✓ Azul — Mensagem lida pelo destinatário
`4`	`played`	Áudio ou vídeo reproduzido pelo destinatário

🔄 Rotação de Chaves

A rotação automática de API Keys garante segurança contínua. A cada 30 dias, uma nova chave é gerada e disponibilizada para seu sistema buscar automaticamente.

Como funciona

Ative a rotação no painel da instância e configure a URL de webhook de rotação
A cada 30 dias, o sistema gera uma nova chave e envia uma notificação para seu webhook
Seu sistema busca a nova chave via endpoint GET /api/v1/key/rotate
Ao usar a nova chave pela primeira vez, a antiga é revogada automaticamente
Se a nova chave não for buscada em 5 dias, a rotação expira

GET /api/v1/key/rotate

Busca a nova chave pendente de rotação. Autentique com a chave atual.

Resposta de Sucesso 200 OK

JSON
{
  "api_key": "tm_NovaChaveGeradaAutomaticamente...",
  "available_at": "2026-04-06T18:00:00+00:00",
  "expires_at": "2026-04-11T18:00:00+00:00",
  "message": "Use esta chave em suas requisições..."
}

⚠️

Transição suave: Ambas as chaves (atual e nova) são aceitas simultaneamente. Ao usar a nova chave pela primeira vez, a antiga é automaticamente revogada.

🚨 Erros

A API utiliza códigos HTTP padrão para indicar sucesso ou falha.

Código	Significado	Descrição
`200`	OK	Requisição processada com sucesso
`401`	Unauthorized	API Key inválida ou ausente
`422`	Unprocessable	Instância não conectada ou parâmetros inválidos
`400`	Bad Request	Rotação de chave desativada
`404`	Not Found	Nenhuma rotação pendente
`410`	Gone	Chave/rotação expirada

Formato de erro padrão

JSON — Erro
{
  "error": "unauthorized",
  "message": "API key inválida ou instância não encontrada."
}

JSON — Instância desconectada
{
  "error": "instance_not_connected",
  "message": "A instância não está conectada ao WhatsApp.",
  "status": "disconnected"
}

🏢 Enterprise API

A Enterprise API permite criar e gerenciar instâncias WhatsApp de forma programática. Ideal para plataformas SaaS, integradores e operações de grande escala.

Autenticação

Todas as requisições Enterprise usam o header X-Enterprise-Key com a chave gerada no painel de configurações (prefixo tmek_).

Headers

X-Enterprise-Key: tmek_SuaChaveEnterpriseAqui
Content-Type: application/json
        

💡

A chave Enterprise é separada das API Keys das instâncias. Ela autentica operações na conta como um todo, não em uma instância específica.

⚠️

Pré-requisito: Antes de criar instâncias via API, é necessário contratar a primeira instância pelo painel (com cartão de crédito recorrente). Instâncias adicionais criadas via API são provisionadas imediatamente, com cobrança proporcional ao período restante do ciclo atual. O valor da assinatura recorrente é ajustado automaticamente em até 5 minutos.

🚀 Criar Instância

POST /api/v1/enterprise/instances

Cria uma nova instância WhatsApp e retorna os dados de conexão incluindo QR Code.

Parâmetros (Body JSON)

Campo	Tipo		Descrição
`name`	string	Obrigatório	Nome identificador da instância (2-100 caracteres)
`webhook_url`	string	Opcional	URL para receber eventos (mensagens, conexão, etc)
`webhook_events`	array	Opcional	Eventos desejados: `MESSAGES_UPSERT`, `MESSAGES_UPDATE`, `SEND_MESSAGE`, `PRESENCE_UPDATE`, `CONNECTION_UPDATE`

Exemplo

cURL
curl -X POST \
  "https://seu-dominio.com/api/v1/enterprise/instances" \
  -H "X-Enterprise-Key: tmek_sua_chave" \
  -H "Content-Type: application/json" \
  -d '{  
    "name": "Atendimento Vendas",
    "webhook_url": "https://meuapp.com/webhooks/whatsapp",
    "webhook_events": ["MESSAGES_UPSERT", "CONNECTION_UPDATE"]
  }'

PHP
$response = Http::withHeaders([
    'X-Enterprise-Key' => 'tmek_sua_chave',
])->post('https://seu-dominio.com/api/v1/enterprise/instances', [
    'name'           => 'Atendimento Vendas',
    'webhook_url'    => 'https://meuapp.com/webhooks/whatsapp',
    'webhook_events' => ['MESSAGES_UPSERT', 'CONNECTION_UPDATE'],
]);

JavaScript
const res = await fetch('https://seu-dominio.com/api/v1/enterprise/instances', {
  method: 'POST',
  headers: {
    'X-Enterprise-Key': 'tmek_sua_chave',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Atendimento Vendas',
    webhook_url: 'https://meuapp.com/webhooks/whatsapp',
    webhook_events: ['MESSAGES_UPSERT', 'CONNECTION_UPDATE'],
  }),
});

Python
import requests

response = requests.post(
    'https://seu-dominio.com/api/v1/enterprise/instances',
    headers={'X-Enterprise-Key': 'tmek_sua_chave'},
    json={
        'name': 'Atendimento Vendas',
        'webhook_url': 'https://meuapp.com/webhooks/whatsapp',
        'webhook_events': ['MESSAGES_UPSERT', 'CONNECTION_UPDATE'],
    },
)

Resposta de Sucesso 201 Created

JSON
{
  "success": true,
  "instance": {
    "id": 42,
    "name": "Atendimento Vendas",
    "instance_name": "tm_ent_atendimento_vendas_a8f3c2",
    "api_key": "tm_AbCdEfGhIjKlMnOpQrStUv...",
    "status": "disconnected",
    "webhook_url": "https://meuapp.com/webhooks/whatsapp",
    "webhook_events": ["MESSAGES_UPSERT", "CONNECTION_UPDATE"],
    "qrcode": {
      "base64": "data:image/png;base64,iVBOR...",
      "code": "2@AbCdEf..."
    },
    "created_at": "2026-04-11T13:00:00+00:00"
  }
}

💡

API Key da instância: A api_key retornada é a chave para enviar mensagens via /api/v1/messages/send. Guarde-a — ela é exibida apenas neste momento.

⚠️

QR Code: Escaneie o QR Code retornado para conectar o WhatsApp à instância. Caso o QR expire, use o endpoint GET /api/v1/enterprise/instances/{id} para obter um novo.

📋 Listar Instâncias

GET /api/v1/enterprise/instances

Lista todas as instâncias da conta Enterprise.

Resposta de Sucesso 200 OK

JSON
{
  "success": true,
  "instances": [
    {
      "id": 42,
      "name": "Atendimento Vendas",
      "instance_name": "tm_ent_atendimento_vendas_a8f3c2",
      "status": "connected",
      "phone_number": "5511999999999",
      "webhook_url": "https://meuapp.com/webhooks/whatsapp",
      "connected_at": "2026-04-11T13:05:00+00:00",
      "created_at": "2026-04-11T13:00:00+00:00"
    }
  ],
  "total": 1
}

🔍 Detalhar Instância

GET /api/v1/enterprise/instances/{id}

Retorna detalhes da instância. Se não estiver conectada, retorna um novo QR Code para conexão.

💡

Use este endpoint para obter um novo QR Code caso o anterior tenha expirado ou para verificar o status atualizado da conexão.

📲 Renovar QR Code

POST /api/v1/enterprise/instances/{id}/qrcode

Solicita um novo QR Code para conectar uma instância ao WhatsApp. Use quando o QR Code anterior expirou ou após desconectar a instância.

Path Parameters

Campo	Tipo		Descrição
`id`	integer	Obrigatório	ID da instância

Exemplo

cURL
curl -X POST \
  "https://seu-dominio.com/api/v1/enterprise/instances/42/qrcode" \
  -H "X-Enterprise-Key: tmek_sua_chave"

PHP
$response = Http::withHeaders([
    'X-Enterprise-Key' => 'tmek_sua_chave',
])->post('https://seu-dominio.com/api/v1/enterprise/instances/42/qrcode');

JavaScript
const res = await fetch('https://seu-dominio.com/api/v1/enterprise/instances/42/qrcode', {
  method: 'POST',
  headers: { 'X-Enterprise-Key': 'tmek_sua_chave' },
});

Python
import requests

response = requests.post(
    'https://seu-dominio.com/api/v1/enterprise/instances/42/qrcode',
    headers={'X-Enterprise-Key': 'tmek_sua_chave'},
)

Resposta de Sucesso 200 OK

JSON
{
  "success": true,
  "status": "awaiting_scan",
  "qrcode": {
    "base64": "data:image/png;base64,iVBOR...",
    "code": "2@AbCdEf..."
  },
  "instance": {
    "id": 42,
    "name": "Atendimento Vendas",
    "instance_name": "tm_ent_atendimento_vendas_a8f3c2"
  }
}

Se já conectada 422

JSON — Erro
{
  "error": "qrcode_failed",
  "message": "A instância já está conectada. Desconecte antes de solicitar um novo QR Code."
}

💡

O QR Code tem validade de ~60 segundos. Se não for escaneado a tempo, chame este endpoint novamente para obter um novo.

🗑️ Remover Instância

DELETE /api/v1/enterprise/instances/{id}

Agenda o cancelamento de uma instância. A instância permanece ativa e utilizável até o fim do ciclo de faturamento já pago. A remoção efetiva ocorre na data agendada (cancels_at), e o valor da assinatura recorrente é ajustado automaticamente.

Path Parameters

Campo	Tipo		Descrição
`id`	integer	Obrigatório	ID da instância

Exemplo

cURL
curl -X DELETE \
  "https://seu-dominio.com/api/v1/enterprise/instances/42" \
  -H "X-Enterprise-Key: tmek_sua_chave"

Resposta de Sucesso 200 OK

JSON
{
  "success": true,
  "message": "Cancelamento agendado com sucesso.",
  "cancels_at": "2026-05-09",
  "subscription_status": "canceling"
}

⏳

Cancelamento agendado: A instância não é removida imediatamente. Ela continua ativa até cancels_at (1 dia antes da próxima renovação), garantindo que o cliente utilize o período já pago. A assinatura recorrente é ajustada automaticamente após a remoção efetiva.

🔔 Webhook Administrativo

O webhook administrativo é a URL base centralizada para receber eventos de todas as instâncias da sua conta Enterprise. Ele funciona como fallback: se uma instância não tiver webhook próprio configurado, todos os eventos (mensagens, presença, conexão) são enviados para esta URL.

Ao criar instâncias via API sem especificar webhook_url, o webhook admin é automaticamente utilizado como URL padrão.

Configuração

Configure via API ou pelo painel em Configurações → Webhook Administrativo.

PUT /api/v1/enterprise/webhook

Configura a URL do webhook administrativo. Envie null para remover.

Parâmetros (Body JSON)

Campo	Tipo		Descrição
`webhook_url`	string	Opcional	URL HTTPS para receber notificações. `null` para remover.

Exemplo

cURL
curl -X PUT \
  "https://seu-dominio.com/api/v1/enterprise/webhook" \
  -H "X-Enterprise-Key: tmek_sua_chave" \
  -H "Content-Type: application/json" \
  -d '{
    "webhook_url": "https://meuapp.com/webhooks/admin"
  }'

PHP
$response = Http::withHeaders([
    'X-Enterprise-Key' => 'tmek_sua_chave',
])->put('https://seu-dominio.com/api/v1/enterprise/webhook', [
    'webhook_url' => 'https://meuapp.com/webhooks/admin',
]);

JavaScript
const res = await fetch('https://seu-dominio.com/api/v1/enterprise/webhook', {
  method: 'PUT',
  headers: {
    'X-Enterprise-Key': 'tmek_sua_chave',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    webhook_url: 'https://meuapp.com/webhooks/admin',
  }),
});

Python
import requests

response = requests.put(
    'https://seu-dominio.com/api/v1/enterprise/webhook',
    headers={'X-Enterprise-Key': 'tmek_sua_chave'},
    json={'webhook_url': 'https://meuapp.com/webhooks/admin'},
)

Resposta de Sucesso 200 OK

JSON
{
  "success": true,
  "webhook_url": "https://meuapp.com/webhooks/admin",
  "message": "Webhook administrativo configurado."
}

GET /api/v1/enterprise/webhook

Consulta a configuração atual do webhook administrativo.

Resposta 200 OK

JSON
{
  "success": true,
  "webhook_url": "https://meuapp.com/webhooks/admin",
  "events": ["message.received", "message.sent", "presence.update", "instance.connected", "instance.disconnected"]
}

Eventos Recebidos

O webhook admin recebe todos os eventos das instâncias que não possuem webhook próprio, além de notificações de conexão/desconexão de todas as instâncias.

Evento	Quando é disparado
`message.received`	Mensagem recebida em qualquer instância
`message.sent`	Mensagem enviada via API em qualquer instância
`presence.update`	Mudança de status online/offline de contato
`instance.connected`	Uma instância conectou ao WhatsApp (QR Code escaneado com sucesso)
`instance.disconnected`	Uma instância perdeu a conexão com o WhatsApp

Payload — instance.connected

JSON — instance.connected
{
  "event": "instance.connected",
  "timestamp": "2026-04-11T13:05:00-03:00",
  "instance": {
    "id": 42,
    "name": "Atendimento Vendas",
    "instance_name": "tm_ent_atendimento_vendas_a8f3c2",
    "status": "connected",
    "phone_number": "5511999999999"
  }
}

Payload — instance.disconnected

JSON — instance.disconnected
{
  "event": "instance.disconnected",
  "timestamp": "2026-04-11T14:30:00-03:00",
  "instance": {
    "id": 42,
    "name": "Atendimento Vendas",
    "instance_name": "tm_ent_atendimento_vendas_a8f3c2",
    "status": "disconnected",
    "phone_number": null
  }
}

💡

Caso de uso: Configure um webhook admin para monitorar todas as suas instâncias. Quando uma instância desconectar, seu sistema pode automaticamente solicitar um novo QR Code via POST /instances/{id}/qrcode e notificar o operador.

Resumo de Todos os Endpoints Enterprise

Método	Endpoint	Descrição
`POST`	`/api/v1/enterprise/instances`	Criar nova instância
`GET`	`/api/v1/enterprise/instances`	Listar todas as instâncias
`GET`	`/api/v1/enterprise/instances/{id}`	Detalhar instância (com QR code se desconectada)
`POST`	`/api/v1/enterprise/instances/{id}/qrcode`	Renovar QR Code
`DELETE`	`/api/v1/enterprise/instances/{id}`	Remover instância
`GET`	`/api/v1/enterprise/webhook`	Consultar webhook admin
`PUT`	`/api/v1/enterprise/webhook`	Configurar webhook admin

📖 Visão Geral

🔐 Autenticação

⚡ Início Rápido

📱 Criar Instância

Passo a passo

🔗 Conectar WhatsApp

💬 Enviar Texto

Parâmetros (Body JSON)

Exemplo

Resposta de Sucesso 200 OK

📎 Enviar Mídia

Parâmetros (Body JSON)

Exemplos por tipo

Resposta de Sucesso 200 OK

✏️ Editar Mensagem

Parâmetros (Body JSON)

Exemplo

Resposta de Sucesso 200 OK

🗑️ Apagar Mensagem

Parâmetros (Body JSON)

Exemplo

Resposta de Sucesso 200 OK

🔔 Webhooks — Configuração

URLs Configuráveis

📡 Webhooks — Eventos

Eventos disponíveis

📦 Webhooks — Payloads

Mensagem de Texto (recebida)

Imagem recebida

Tipos de mensagem suportados

Payload de Presença

Payload de Status de Mensagem

Valores de status (ack)

🔄 Rotação de Chaves

Como funciona

Resposta de Sucesso 200 OK

🚨 Erros

Formato de erro padrão

🏢 Enterprise API

Autenticação

🚀 Criar Instância

Parâmetros (Body JSON)

Exemplo

Resposta de Sucesso 201 Created

📋 Listar Instâncias

Resposta de Sucesso 200 OK

🔍 Detalhar Instância

📲 Renovar QR Code

Path Parameters

Exemplo

Resposta de Sucesso 200 OK

Se já conectada 422

🗑️ Remover Instância

Path Parameters

Exemplo

Resposta de Sucesso 200 OK

🔔 Webhook Administrativo

Configuração

Parâmetros (Body JSON)

Exemplo

Resposta de Sucesso 200 OK

Resposta 200 OK

Eventos Recebidos

Payload — instance.connected

Payload — instance.disconnected

Resumo de Todos os Endpoints Enterprise

Valores de `status` (ack)