WhatsApp - seven.io API

Use esta API para enviar mensagens do WhatsApp através da API WhatsApp Business (WABA). Você pode enviar mensagens de modelo, mensagens de texto livre, mídia (imagem, vídeo, áudio, documento, sticker), localizações, contatos e mensagens interativas. As reações são enviadas através do endpoint de eventos.

Para usar este endpoint, sua chave de API deve ter o escopo waba habilitado. Você também precisa de um número de remetente WhatsApp Business registrado.

POST/api/waba/messages

Enviar mensagem

Envie uma mensagem do WhatsApp para um destinatário. Você pode enviar mensagens de modelo, mensagens de texto livre, mídia (imagem, vídeo, áudio, documento, sticker), localizações, contatos e mensagens interativas (botões, listas).

Parâmetros obrigatórios

Name
from
Type
string
Description
Seu número de remetente WhatsApp Business registrado no formato internacional (ex. 4915112345678).
Name
to
Type
string
Description
Número de telefone do destinatário no formato internacional (ex. 4917612345678).

Parâmetros de mensagem de modelo

Name
type
Type
string
Description
Defina como template para enviar uma mensagem de modelo do WhatsApp pré-aprovada.
Name
template
Type
string
Description
O nome do modelo do WhatsApp aprovado (ex. hello_world).
Name
language
Type
string
Description
Código do idioma do modelo (ex. de, en, pt).
Name
components
Type
object
Optional
Optional
Description
Valores dos parâmetros do modelo. Contém arrays opcionais para header, body e buttons. Os valores são posicionais e substituem {{1}}, {{2}}, etc. no modelo.

components

object

Parâmetros dos componentes do modelo

Name
header
Type
array
Optional
Optional
Description
Valores para os marcadores de posição do cabeçalho. Para cabeçalhos de texto, forneça strings. Para cabeçalhos de imagem, forneça uma URL.
Name
body
Type
array
Optional
Optional
Description
Valores para os marcadores de posição do corpo. Cada entrada substitui a variável {{n}} correspondente.
Name
buttons
Type
array
Optional
Optional
Description
Valores dos parâmetros de botões. Cada entrada é um objeto com type, sub_type e parameters.

Parâmetros de mensagem de texto livre

Name
type
Type
string
Description
Defina como text ou omita. O texto da mensagem é enviado dentro de uma janela de conversa de 24 horas.
Name
text
Type
string
Description
O texto da mensagem. Só pode ser enviado dentro de uma janela de conversa ativa de 24 horas.

Parâmetros de mensagem de imagem

Name
type
Type
string
Description
Defina como image.
Name
url
Type
string
Description
URL pública do arquivo de imagem (JPEG, PNG).
Name
caption
Type
string
Optional
Optional
Description
Legenda opcional para a imagem.

Parâmetros de mensagem de vídeo

Name
type
Type
string
Description
Defina como video.
Name
url
Type
string
Description
URL pública do arquivo de vídeo (MP4, 3GPP).
Name
caption
Type
string
Optional
Optional
Description
Legenda opcional para o vídeo.

Parâmetros de mensagem de áudio

Name
type
Type
string
Description
Defina como audio.
Name
url
Type
string
Description
URL pública do arquivo de áudio (MP3, OGG, AMR, AAC).

Parâmetros de mensagem de documento

Name
type
Type
string
Description
Defina como document.
Name
url
Type
string
Description
URL pública do arquivo de documento (PDF, DOC, etc.).
Name
filename
Type
string
Description
O nome do arquivo exibido ao destinatário.
Name
caption
Type
string
Optional
Optional
Description
Legenda opcional para o documento.

Parâmetros de mensagem de sticker

Name
type
Type
string
Description
Defina como sticker.
Name
url
Type
string
Description
URL pública do arquivo de sticker (WebP). Stickers estáticos: 512x512px, máx. 100KB. Stickers animados: 512x512px, máx. 500KB.

Parâmetros de mensagem de localização

Name
type
Type
string
Description
Defina como location.
Name
latitude
Type
number
Description
Latitude da localização.
Name
longitude
Type
number
Description
Longitude da localização.
Name
name
Type
string
Optional
Optional
Description
Nome da localização.
Name
address
Type
string
Optional
Optional
Description
Endereço da localização.

Parâmetros de mensagem de contatos

Name
type
Type
string
Description
Defina como contacts.
Name
contacts
Type
array
Description
Array de objetos de contato. Cada contato deve ter um objeto name (com first_name e last_name opcional) e um array phones (cada um com phone e type opcional: cell, main, iphone, home, work).

Parâmetros de mensagem interativa de botões

Name
type
Type
string
Description
Defina como interactive.
Name
interactive_type
Type
string
Description
Defina como button.
Name
body
Type
string
Description
Texto do corpo exibido ao usuário.
Name
buttons
Type
array
Description
Array de 2-3 objetos de botão, cada um com id (identificador único) e title (texto de exibição, máx. 20 caracteres).
Name
header
Type
string
Optional
Optional
Description
Texto de cabeçalho opcional.
Name
footer
Type
string
Optional
Optional
Description
Texto de rodapé opcional.

Parâmetros de mensagem interativa de lista

Name
type
Type
string
Description
Defina como interactive.
Name
interactive_type
Type
string
Description
Defina como list.
Name
body
Type
string
Description
Texto do corpo exibido ao usuário.
Name
button_text
Type
string
Description
Texto exibido no botão da lista.
Name
sections
Type
array
Description
Array de objetos de seção, cada um com title e rows (array de objetos de linha com id, title e description opcional).
Name
header
Type
string
Optional
Optional
Description
Texto de cabeçalho opcional.
Name
footer
Type
string
Optional
Optional
Description
Texto de rodapé opcional.

Parâmetros opcionais

Name
delay
Type
timestamp
Optional
Optional
Description
Data/hora para envio agendado. Formato: AAAA-MM-DD hh:mm:ss ou timestamp Unix.
Name
ttl
Type
integer
Optional
Optional
Description
Especifica o período de validade da mensagem em minutos. O padrão é 2880, ou seja, 48 horas.
Name
label
Type
string
Optional
Optional
Description
Rótulo personalizado para estatísticas. Máx. 100 caracteres, caracteres permitidos: a-z, A-Z, 0-9, .-_@.
Name
performance_tracking
Type
boolean
Optional
Optional
Description
Ativar rastreamento de cliques e desempenho para URLs encontradas no texto da mensagem. Isso também ativa o encurtador de URL.
Name
foreign_id
Type
string
Optional
Optional
Description
Seu próprio ID para esta mensagem. Retornado nos callbacks de relatórios de status. Máx. 64 caracteres, caracteres permitidos: a-z, A-Z, 0-9, .-_@.

Mensagem de modelo

POST

/api/waba/messages

curl -X POST https://gateway.seven.io/api/waba/messages \
    -H "X-Api-Key: SUA_CHAVE_API" \
    -H "Content-Type: application/json" \
    -d '{
      "from": "4915112345678",
      "to": "4917612345678",
      "type": "template",
      "template": "hello_world",
      "language": "de"
    }'

Resposta

{
    "success": "100",
    "total_price": 0.0735,
    "balance": 123.45,
    "debug": "false",
    "sms_type": "WA",
    "messages": [
        {
            "id": "12345678",
            "sender": "4915112345678",
            "recipient": "4917612345678",
            "text": "{\"type\":\"template\",\"template\":\"hello_world\",\"language\":\"de\",\"rendered\":{\"body\":\"Hallo Welt!\"}}",
            "encoding": "gsm",
            "label": null,
            "parts": 1,
            "udh": null,
            "is_binary": false,
            "price": 0.0735,
            "channel": "WA",
            "success": true,
            "error": null,
            "error_text": null
        }
    ]
}

Modelo com parâmetros

POST

/api/waba/messages

curl -X POST https://gateway.seven.io/api/waba/messages \
    -H "X-Api-Key: SUA_CHAVE_API" \
    -H "Content-Type: application/json" \
    -d '{
      "from": "4915112345678",
      "to": "4917612345678",
      "type": "template",
      "template": "order_confirmation",
      "language": "de",
      "components": {
        "body": ["Max Mustermann", "ORD-12345"],
        "buttons": [
          {
            "type": "button",
            "sub_type": "url",
            "parameters": [{"type": "text", "text": "ORD-12345"}]
          }
        ]
      }
    }'

Mensagem de texto livre

POST

/api/waba/messages

curl -X POST https://gateway.seven.io/api/waba/messages \
    -H "X-Api-Key: SUA_CHAVE_API" \
    -H "Content-Type: application/json" \
    -d '{
      "from": "4915112345678",
      "to": "4917612345678",
      "text": "Obrigado pela sua mensagem, vamos tratar disso!"
    }'

Mensagem de imagem

POST

/api/waba/messages

curl -X POST https://gateway.seven.io/api/waba/messages \
    -H "X-Api-Key: SUA_CHAVE_API" \
    -H "Content-Type: application/json" \
    -d '{
      "from": "4915112345678",
      "to": "4917612345678",
      "type": "image",
      "url": "https://example.com/photo.jpg",
      "caption": "Confira esta imagem!"
    }'

Mensagem de vídeo

POST

/api/waba/messages

curl -X POST https://gateway.seven.io/api/waba/messages \
    -H "X-Api-Key: SUA_CHAVE_API" \
    -H "Content-Type: application/json" \
    -d '{
      "from": "4915112345678",
      "to": "4917612345678",
      "type": "video",
      "url": "https://example.com/video.mp4",
      "caption": "Assista a este vídeo"
    }'

Mensagem de áudio

POST

/api/waba/messages

curl -X POST https://gateway.seven.io/api/waba/messages \
    -H "X-Api-Key: SUA_CHAVE_API" \
    -H "Content-Type: application/json" \
    -d '{
      "from": "4915112345678",
      "to": "4917612345678",
      "type": "audio",
      "url": "https://example.com/audio.mp3"
    }'

Mensagem de documento

POST

/api/waba/messages

curl -X POST https://gateway.seven.io/api/waba/messages \
    -H "X-Api-Key: SUA_CHAVE_API" \
    -H "Content-Type: application/json" \
    -d '{
      "from": "4915112345678",
      "to": "4917612345678",
      "type": "document",
      "url": "https://example.com/fatura.pdf",
      "filename": "fatura.pdf",
      "caption": "Sua fatura"
    }'

Mensagem de sticker

POST

/api/waba/messages

curl -X POST https://gateway.seven.io/api/waba/messages \
    -H "X-Api-Key: SUA_CHAVE_API" \
    -H "Content-Type: application/json" \
    -d '{
      "from": "4915112345678",
      "to": "4917612345678",
      "type": "sticker",
      "url": "https://example.com/sticker.webp"
    }'

Mensagem de localização

POST

/api/waba/messages

curl -X POST https://gateway.seven.io/api/waba/messages \
    -H "X-Api-Key: SUA_CHAVE_API" \
    -H "Content-Type: application/json" \
    -d '{
      "from": "4915112345678",
      "to": "4917612345678",
      "type": "location",
      "latitude": 48.8566,
      "longitude": 2.3522,
      "name": "Torre Eiffel",
      "address": "5 Avenue Anatole France, 75007 Paris"
    }'

Mensagem de contatos

POST

/api/waba/messages

curl -X POST https://gateway.seven.io/api/waba/messages \
    -H "X-Api-Key: SUA_CHAVE_API" \
    -H "Content-Type: application/json" \
    -d '{
      "from": "4915112345678",
      "to": "4917612345678",
      "type": "contacts",
      "contacts": [
        {
          "name": {
            "first_name": "João",
            "last_name": "Silva"
          },
          "phones": [
            {
              "phone": "+5511987654321"
            }
          ]
        }
      ]
    }'

Mensagem interativa de botões

POST

/api/waba/messages

curl -X POST https://gateway.seven.io/api/waba/messages \
    -H "X-Api-Key: SUA_CHAVE_API" \
    -H "Content-Type: application/json" \
    -d '{
      "from": "4915112345678",
      "to": "4917612345678",
      "type": "interactive",
      "interactive_type": "button",
      "header": "Suporte",
      "body": "Como podemos ajudá-lo?",
      "footer": "Toque em um botão",
      "buttons": [
        {"id": "sales", "title": "Vendas"},
        {"id": "support", "title": "Suporte"},
        {"id": "other", "title": "Outro"}
      ]
    }'

Mensagem interativa de lista

POST

/api/waba/messages

curl -X POST https://gateway.seven.io/api/waba/messages \
    -H "X-Api-Key: SUA_CHAVE_API" \
    -H "Content-Type: application/json" \
    -d '{
      "from": "4915112345678",
      "to": "4917612345678",
      "type": "interactive",
      "interactive_type": "list",
      "header": "Nossos Produtos",
      "body": "Navegue por nossas categorias:",
      "footer": "Selecione uma opção",
      "button_text": "Ver opções",
      "sections": [
        {
          "title": "Eletrônicos",
          "rows": [
            {"id": "smartphones", "title": "Smartphones", "description": "Últimos modelos"},
            {"id": "notebooks", "title": "Notebooks", "description": "Business & Gaming"}
          ]
        }
      ]
    }'

Componentes do modelo

A estrutura components suporta três arrays opcionais: header, body e buttons. Os valores são posicionais e substituem {{1}}, {{2}}, etc. no modelo.

Parâmetros do cabeçalho

Cabeçalho de texto: Forneça valores de string para os marcadores de posição
Cabeçalho de imagem: Forneça uma URL para a imagem

Parâmetros do corpo

Forneça valores de string que substituam {{1}}, {{2}}, etc. no corpo do modelo.

Parâmetros de botão

Para botões URL com sufixos dinâmicos, forneça um array de objetos de botão:

Name
type
Type
string
Description
Sempre button.
Name
sub_type
Type
string
Description
O tipo de botão, ex. url.
Name
parameters
Type
array
Description
Array de objetos de parâmetros com propriedades type e text.

Cabeçalho + Corpo + Botões

{
    "from": "4915112345678",
    "to": "4917612345678",
    "type": "template",
    "template": "appointment_reminder",
    "language": "pt",
    "components": {
        "header": ["Confirmação de consulta"],
        "body": ["Max Mustermann", "15/02/2026", "14:00", "Dr. Schmidt"],
        "buttons": [
            {
                "type": "button",
                "sub_type": "url",
                "parameters": [{"type": "text", "text": "abc123"}]
            }
        ]
    }
}

Cabeçalho de imagem + Corpo

{
    "from": "4915112345678",
    "to": "4917612345678",
    "type": "template",
    "template": "product_available",
    "language": "pt",
    "components": {
        "header": ["https://example.com/product.jpg"],
        "body": ["Premium Widget"]
    }
}

DELETE/api/waba/messages/{id}

Excluir mensagem

Exclua uma mensagem do WhatsApp agendada antes de ter sido enviada.

Name
id
Type
string
Description
O ID da mensagem a ser excluída. Passado como parâmetro de caminho URL.

Mensagens já enviadas não podem ser excluídas. O WhatsApp não suporta a revogação de mensagens.

Solicitação

DELETE

/api/waba/messages/{id}

curl -X DELETE https://gateway.seven.io/api/waba/messages/12345678 \
    -H "X-Api-Key: SUA_CHAVE_API"

Resposta (sucesso)

{
    "success": true
}

Resposta (já enviada)

{
    "error_code": 400,
    "error_message": "Message already sent. WhatsApp does not support message revocation."
}

Resposta (não encontrado)

{
    "code": 404,
    "message": "Page not found",
    "errors": []
}

POST/api/waba/events

Enviar evento

Envie eventos de conversa como confirmações de leitura, indicadores de digitação ou reações para um contato do WhatsApp.

Os eventos só podem ser enviados para mensagens dos últimos 7 dias. Conversas mais antigas não são mais elegíveis para entrega de eventos.

Pelo menos um dos parâmetros to ou msg_id deve ser fornecido para identificar a conversa ou mensagem alvo.

Parâmetros de evento de leitura/digitação

Name
from
Type
string
Description
Seu número de remetente WhatsApp Business registrado.
Name
to
Type
string
Optional
Optional
Description
Número de telefone do destinatário no formato internacional. Pelo menos to ou msg_id deve ser fornecido.
Name
event
Type
string
Description
O tipo de evento. Valores disponíveis: read, is_typing.
Name
msg_id
Type
string
Optional
Optional
Description
ID de mensagem explícito para marcar como lido. Pelo menos to ou msg_id deve ser fornecido.

Parâmetros de evento de reação

Name
event
Type
string
Description
Defina como reaction.
Name
msg_id
Type
string
Description
O ID da mensagem do WhatsApp à qual reagir.
Name
emoji
Type
string
Description
O emoji para a reação (ex. 👍). Envie uma string vazia para remover a reação.

Confirmação de leitura

POST

/api/waba/events

curl -X POST https://gateway.seven.io/api/waba/events \
    -H "X-Api-Key: SUA_CHAVE_API" \
    -H "Content-Type: application/json" \
    -d '{
      "from": "4915112345678",
      "to": "4917612345678",
      "event": "read"
    }'

Indicador de digitação

POST

/api/waba/events

curl -X POST https://gateway.seven.io/api/waba/events \
    -H "X-Api-Key: SUA_CHAVE_API" \
    -H "Content-Type: application/json" \
    -d '{
      "from": "4915112345678",
      "to": "4917612345678",
      "event": "is_typing"
    }'

Reação

POST

/api/waba/events

curl -X POST https://gateway.seven.io/api/waba/events \
    -H "X-Api-Key: SUA_CHAVE_API" \
    -H "Content-Type: application/json" \
    -d '{
      "event": "reaction",
      "msg_id": "123456789",
      "emoji": "👍"
    }'

Resposta

{
    "success": true
}

Resposta de erro

{
    "success": false,
    "error_code": 400,
    "error_message": "Invalid WhatsApp sender number"
}

Respostas de erro

Name
100
Description
A mensagem foi aceita pelo gateway e está sendo enviada.
Name
7002001
Description
Sem conversa ativa. Mensagens de texto livre só podem ser enviadas dentro de uma janela de conversa ativa de 24 horas. Use uma mensagem de modelo para iniciar uma conversa.
Name
400
Description
Solicitação inválida. Pode indicar um número de remetente inválido, número de destinatário inválido ou outros erros de validação.
Name
404
Description
Mensagem não encontrada. O ID de mensagem especificado não existe ou não pertence à sua conta.
Name
900
Description
A autenticação falhou. Verifique a chave de API usada em Autenticação.
Name
902
Description
A chave de API não tem direitos de acesso a este endpoint. Certifique-se de que o escopo waba esteja habilitado.