Documentação da API

Autenticação

Todas as requisições devem incluir os headers de autenticação:

Enviar Mensagem

Mensagem de Texto

{
  "to": "5547999999999",
  "type": "text",
  "text": {
    "body": "Olá! Como posso ajudar?"
  }
}

Mensagem com Imagem

{
  "to": "5547999999999",
  "type": "image",
  "image": {
    "link": "https://exemplo.com/imagem.jpg",
    "caption": "Legenda da imagem"
  }
}

Mensagem com Documento

{
  "to": "5547999999999",
  "type": "document",
  "document": {
    "link": "https://exemplo.com/arquivo.pdf",
    "filename": "contrato.pdf"
  }
}

Resposta de Sucesso

{
  "success": true,
  "message": "Mensagem enviada com sucesso",
  "message_id": "wamid.HBgNNTU0Nzk5OTk5OTk5...",
  "from": "123456789012345",
  "to": "5547999999999"
}

Enviar Template

{
  "to": "5547999999999",
  "template": {
    "name": "nome_do_template",
    "language": {
      "code": "pt_BR"
    },
    "components": [
      {
        "type": "body",
        "parameters": [
          { "type": "text", "text": "João" },
          { "type": "text", "text": "10/02/2026" }
        ]
      }
    ]
  }
}

Webhooks

Configure sua URL de webhook no dashboard para receber eventos em tempo real.

Validando Webhooks

Cada webhook inclui o header X-BSP-Signature para validação HMAC-SHA256:

$body = file_get_contents('php://input');
$secret = 'seu_webhook_secret';
$signature = hash_hmac('sha256', $body, $secret);

if (hash_equals($_SERVER['HTTP_X_BSP_SIGNATURE'], $signature)) {
    // Webhook válido
}

Eventos

Evento: message

Recebido quando uma nova mensagem chega.

{
  "event": "message",
  "timestamp": "2026-02-09T10:30:00-03:00",
  "from_number_id": "123456789012345",
  "contact": {
    "wa_id": "5547888889999",
    "name": "João Silva"
  },
  "message": {
    "id": "wamid.xxx",
    "type": "text",
    "text": "Olá, preciso de ajuda!"
  }
}

Evento: status

Recebido quando o status de uma mensagem enviada muda.

{
  "event": "status",
  "status": {
    "id": "wamid.xxx",
    "status": "delivered",
    "recipient": "5547999999999"
  }
}

Códigos de Erro

Exemplos

curl -X POST "https://api.covercut.com.br/api/v1/messages/send" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: sua_api_key" \
  -H "X-API-Secret: seu_api_secret" \
  -d '{
    "to": "5547999999999",
    "type": "text",
    "text": { "body": "Olá!" }
  }'

$ch = curl_init('https://api.covercut.com.br/api/v1/messages/send');

curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
        'X-API-Key: sua_api_key',
        'X-API-Secret: seu_api_secret'
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'to' => '5547999999999',
        'type' => 'text',
        'text' => ['body' => 'Olá!']
    ]),
    CURLOPT_RETURNTRANSFER => true
]);

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);

const response = await fetch('https://api.covercut.com.br/api/v1/messages/send', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': 'sua_api_key',
    'X-API-Secret': 'seu_api_secret'
  },
  body: JSON.stringify({
    to: '5547999999999',
    type: 'text',
    text: { body: 'Olá!' }
  })
});

const data = await response.json();