Documentação da API IntegraWhats
🔐 Autenticação
Todas as requisições à API devem ser autenticadas. Para obter seu token, acesse seu painel na IntegraWhats no menu API > Token.
O token deve ser enviado no header Authorization e o header Client-Service também é obrigatório.
Headers Obrigatórios
Client-Service: frontend-client
Authorization: Bearer {SEU_TOKEN_AQUI}
Mensagens
Enviar Mensagem de Texto
POST /api/messages/text
Envia uma mensagem de texto simples para um número de telefone válido.
Parâmetros do Corpo (JSON)
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
phone | string | Sim | Número do destinatário (ex: 5516999999999). |
message | string | Sim | Conteúdo da mensagem. |
Exemplo de Resposta (Sucesso 200)
{ "status": 200, "message": "Mensagem enviada para a fila.", "messageId": "xyz-123-abc-456" }Enviar Mídia (Imagem)
POST /api/messages/media
Envia uma imagem (JPG, PNG) para um número de telefone. A imagem deve ser acessível via URL pública.
Parâmetros do Corpo (JSON)
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
phone | string | Sim | Número do destinatário. |
mediaUrl | string | Sim | URL pública da imagem a ser enviada. |
caption | string | Não | Legenda opcional para a imagem. |
Verificar Status da Mensagem
GET /api/status/{messageId}
Consulta o status de uma mensagem específica enviada anteriormente.
Exemplo de Resposta (Sucesso 200)
{ "messageId": "xyz-123-abc-456", "status": "read", "timestamp": "2025-09-22T14:30:00Z" }Gerenciamento de Contatos
Criar um Novo Contato
POST /api/contacts
Adiciona um novo contato à sua lista.
Parâmetros do Corpo (JSON)
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
name | string | Sim | Nome do contato. |
phone | string | Sim | Número do contato (ex: 5516999999999). |
Exemplo de Resposta (Sucesso 201)
{ "id": "ct_12345", "name": "João da Silva", "phone": "5516999999999", "createdAt": "2025-09-22T11:30:00Z" }Listar Contatos
GET /api/contacts
Retorna uma lista paginada dos seus contatos.
Parâmetros de Query
| Parâmetro | Tipo | Padrão | Descrição |
|---|---|---|---|
page | integer | 1 | Número da página. |
limit | integer | 20 | Quantidade de contatos por página. |
Gerenciar um Contato Específico
GET PUT DELETE /api/contacts/{contactId}
Use o ID do contato (contactId) para obter, atualizar ou excluir.
- GET: Retorna os detalhes do contato.
- PUT: Atualiza os dados do contato (envie `name` e/ou `phone`).
- DELETE: Remove o contato. Retorna status
204 No Content.
Gerenciamento de Campanhas
Criar e Enviar uma Campanha
POST /api/campaigns
Cria uma nova campanha de envio de mensagens.
Parâmetros do Corpo (JSON)
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
name | string | Sim | Nome da campanha. |
message | string | Sim | Conteúdo da mensagem. |
contactIds | array[string] | Sim | Array com os IDs dos contatos. |
scheduledAt | string | Não | Agendar envio (formato ISO 8601: YYYY-MM-DDTHH:MM:SSZ). |
Listar Campanhas
GET /api/campaigns
Retorna uma lista paginada de todas as suas campanhas.
Gerenciar uma Campanha Específica
GET DELETE /api/campaigns/{campaignId}
Use o ID da campanha (campaignId) para obter detalhes ou cancelar.
- GET: Retorna os detalhes e o status da campanha.
- DELETE: Cancela uma campanha agendada.
Exemplo de Resposta GET (Sucesso 200)
{ "id": "camp_abcde", "name": "Promoção", "status": "completed", "stats": { "total": 150, "sent": 148, "failed": 2 } }Outros
Buscar Dados da Conta
GET /api/business
Retorna informações sobre a conta associada ao token.
Exemplo de Resposta (Sucesso 200)
{ "token": "f6b7...", "expires_token": "2035-04-19 22:30:18", "plan_id": "2" }↩️ Webhooks
Webhooks são a forma como a IntegraWhats envia informações para o seu sistema em tempo real, como ao receber uma nova mensagem.
Para configurar, forneça uma URL no painel da IntegraWhats. Faremos uma requisição POST para sua URL com os dados do evento.
Exemplo de Payload de Nova Mensagem
{ "event": "message.received", "from": "5516988887777", "message": { "type": "text", "content": "Olá, gostaria de mais informações." } }