Manual de API para Delphi - Envio de Mensagens WhatsApp

Este manual explica como integrar a API WhatsApp SaaS com aplicações Delphi para enviar mensagens.

📋 Pré-requisitos

• Delphi 7 ou superior
• Componente TIdHTTP (Indy) ou TRESTClient (FireDAC)
• Token de API de uma instância ativa

🔑 Autenticação

Todas as requisições devem incluir o token da instância no header:

X-API-Key: seu-token-da-instancia

ou

Authorization: Bearer seu-token-da-instancia

📡 Endpoints Principais

Base URL

https://seu-dominio.com

ou em desenvolvimento:

http://localhost:3000

📤 Enviar Mensagem de Texto

Endpoint

POST /client/sendMessage/{sessionId}

Headers

Content-Type: application/json
X-API-Key: seu-token-da-instancia

Body (JSON)

{
  "chatId": "5511999999999@c.us",
  "contentType": "string",
  "content": "Olá! Esta é uma mensagem de teste."
}

Parâmetros

• chatId: Número do WhatsApp com código do país + @c.us (ex: 5511999999999@c.us)
• contentType: Tipo de conteúdo (sempre "string" para texto)
• content: Texto da mensagem

Resposta de Sucesso

{
  "success": true,
  "message": {
    "id": {
      "fromMe": true,
      "remote": "5511999999999@c.us",
      "id": "3EB0C767F26BXXXXXX"
    },
    "body": "Olá! Esta é uma mensagem de teste.",
    "type": "chat",
    "timestamp": 1234567890
  }
}

Resposta de Erro

{
  "success": false,
  "message": "Mensagem de erro aqui"
}

📸 Enviar Imagem

Endpoint

POST /client/sendMessage/{sessionId}

Body (JSON)

{
  "chatId": "5511999999999@c.us",
  "contentType": "MessageMedia",
  "content": {
    "mimetype": "image/jpeg",
    "data": "base64-encoded-image-data",
    "filename": "imagem.jpg"
  }
}

Como obter Base64 da imagem

1. Ler o arquivo de imagem
2. Converter para Base64
3. Incluir no campo data

📄 Enviar Documento/Arquivo

Body (JSON)

{
  "chatId": "5511999999999@c.us",
  "contentType": "MessageMedia",
  "content": {
    "mimetype": "application/pdf",
    "data": "base64-encoded-file-data",
    "filename": "documento.pdf"
  }
}

🔗 Enviar Imagem por URL

Body (JSON)

{
  "chatId": "5511999999999@c.us",
  "contentType": "MessageMediaFromURL",
  "content": "https://exemplo.com/imagem.jpg"
}

📍 Enviar Localização

Body (JSON)

{
  "chatId": "5511999999999@c.us",
  "contentType": "Location",
  "content": {
    "latitude": -23.5505,
    "longitude": -46.6333,
    "description": "São Paulo, SP"
  }
}

📋 Verificar Status da Sessão

Endpoint

GET /session/status/{sessionId}

Headers

X-API-Key: seu-token-da-instancia

Resposta

{
  "success": true,
  "state": "CONNECTED",
  "message": "session_connected"
}

Estados possíveis:

• CONNECTED: Conectado e pronto
• CONNECTING: Conectando
• OPENING: Abrindo
• PAIRING: Pareando

📞 Outros Endpoints Úteis

Obter Contatos

GET /client/getContacts/{sessionId}
X-API-Key: seu-token-da-instancia

Obter Chats

GET /client/getChats/{sessionId}
X-API-Key: seu-token-da-instancia

Verificar se número está no WhatsApp

POST /client/isRegisteredUser/{sessionId}
X-API-Key: seu-token-da-instancia

Body:
{
  "contactId": "5511999999999@c.us"
}

🔒 Códigos de Status HTTP

• 200: Sucesso
• 400: Requisição inválida
• 401: Não autenticado (token inválido)
• 403: Acesso negado
• 404: Sessão não encontrada ou não conectada
• 422: Dados inválidos
• 500: Erro interno do servidor

📝 Notas Importantes

1. Formato do número: Sempre use o formato internacional com código do país (ex: 5511999999999)
2. Session ID: Use o session_id da sua instância (não o ID numérico)
3. Token: Mantenha o token seguro, não compartilhe
4. Rate Limit: Respeite os limites de requisições
5. Tamanho de arquivo: Máximo definido em MAX_ATTACHMENT_SIZE (padrão: 10MB)

🐛 Tratamento de Erros

Sempre verifique:

1. Status HTTP da resposta
2. Campo success no JSON
3. Campo message para detalhes do erro

📚 Exemplos de Código

Veja a pasta demo/delphi/ para exemplos completos de implementação.

Ver Exemplos Delphi