Enviar mensagem

Envia uma mensagem de WhatsApp — texto, mídia ou interativa.

POSThttps://external-api.lip7.com.br/api/external/whatsapp/messages

Escopowhatsapp:sendAssíncrono — responde 202 com requestId

Por ser um envio, o endpoint é assíncrono: a mensagem é validada, enfileirada e a API responde 202 com um requestId. Acompanhe o resultado em /usage/status/{requestId} ou por webhook.

Suporta o header Idempotency-Key — veja Idempotência.

Body

tostringobrigatório

Número do destinatário no formato internacional (DDI 55).

messageTypestringopcional

Tipo da mensagem. Os tipos image, audio, video e document são convertidos para media automaticamente.

valorestextmediainteractiveimageaudiovideodocument

contentstringopcional

Texto da mensagem. Obrigatório para text e interactive.

mediaUrlstringopcional

URL do arquivo (pública ou assinada). Alternativa: mediaId de Upload de mídia.

mediaIdstringopcional

Handle durável retornado por POST /media. Preferível a URL assinada de curta duração.

mediaTypestringopcional

Obrigatório quando messageType=media.

valoresimageaudiovideodocument

filenamestringopcional

Nome do arquivo exibido ao destinatário.

buttonsarrayopcional

Botões de resposta para mensagens interactive.

listItemsarrayopcional

Itens de lista para mensagens interactive.

O messageId e o conversationId definitivos ficam disponíveis após o processamento, em /usage/status/{requestId} ou no evento WHATSAPP_SENT do webhook.

Regras e validações

messageType igual a image, audio, video ou document vira media automaticamente.
messageType=media exige mediaType.
messageType=interactive exige content e buttons ou listItems.
O número deve ser válido e celular (Brasil, DDI 55).

Templates não vão por aqui

Esta rota não envia templates. Para templates aprovados pela Meta, use Enviar template.

Mídia precisa ser pública

O mediaUrl precisa estar acessível publicamente pela internet — o WhatsApp baixa o arquivo a partir dessa URL no momento do envio.

Mensagens interativas

Botões de resposta

Envie buttons como uma lista de objetos com id e title.

Body

{
  "to": "5511999999999",
  "messageType": "interactive",
  "content": "Escolha uma opção",
  "buttons": [
    { "id": "btn-1", "title": "Quero falar" },
    { "id": "btn-2", "title": "Ver preço" }
  ]
}

Lista de opções

Envie listItems com id, title e description opcional.

Body

{
  "to": "5511999999999",
  "messageType": "interactive",
  "content": "Selecione um plano",
  "listItems": [
    { "id": "basic", "title": "Plano Basic", "description": "Entrada" },
    { "id": "pro", "title": "Plano Pro", "description": "Mais recursos" }
  ]
}

Outros tipos de mensagem

Imagem

{
  "to": "5511999999999",
  "messageType": "image",
  "mediaUrl": "https://cdn.seu-dominio.com/imagem.jpg",
  "filename": "imagem.jpg"
}

Documento

{
  "to": "5511999999999",
  "messageType": "document",
  "mediaUrl": "https://cdn.seu-dominio.com/contrato.pdf",
  "filename": "contrato.pdf"
}

Erros comuns

Código	Causa
`400`	Payload inválido — campo obrigatório ausente, `messageType` inválido ou número inválido
`401`	API key inválida
`403`	Escopo insuficiente
`500`	Falha ao enfileirar a mensagem

Requisição

curl -X POST "https://external-api.lip7.com.br/api/external/whatsapp/messages" \
  -H "Content-Type: application/json" \
  -H "x-api-key: lip_SUA_CHAVE" \
  -d '{
    "to": "5511999999999",
    "messageType": "text",
    "content": "Olá! Tudo bem?"
  }'

const response = await fetch(
  'https://external-api.lip7.com.br/api/external/whatsapp/messages',
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': 'lip_SUA_CHAVE',
    },
    body: JSON.stringify({
      to: '5511999999999',
      messageType: 'text',
      content: 'Olá! Tudo bem?',
    }),
  }
);

const data = await response.json();

import requests

response = requests.post(
    "https://external-api.lip7.com.br/api/external/whatsapp/messages",
    headers={
        "Content-Type": "application/json",
        "x-api-key": "lip_SUA_CHAVE",
    },
    json={
        "to": "5511999999999",
        "messageType": "text",
        "content": "Olá! Tudo bem?",
    },
)

data = response.json()

$response = file_get_contents(
    'https://external-api.lip7.com.br/api/external/whatsapp/messages',
    false,
    stream_context_create([
        'http' => [
            'method' => 'POST',
            'header' => "Content-Type: application/json\r\nx-api-key: lip_SUA_CHAVE\r\n",
            'content' => json_encode([
                'to' => '5511999999999',
                'messageType' => 'text',
                'content' => 'Olá! Tudo bem?',
            ]),
        ],
    ])
);

$data = json_decode($response, true);

Resposta

{
  "success": true,
  "data": {
    "requestId": "req_..."
  }
}