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, use objetos com type e text (ex. {"type": "text", "text": "valor"}). Para cabeçalhos de imagem, use objetos com type e image.link (ex. {"type": "image", "image": {"link": "https://..."}}).
Name
body
Type
array
Optional
Optional
Description
Valores para os marcadores de posição do corpo. Cada entrada é um objeto com type e text (ex. {"type": "text", "text": "valor"}) e 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, index 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.005,
    "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.005,
            "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": [
          {"type": "text", "text": "Max Mustermann"},
          {"type": "text", "text": "ORD-12345"}
        ],
        "buttons": [
          {
            "type": "button",
            "sub_type": "url",
            "index": 0,
            "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: Use objetos de parâmetros com type e text (ex. {"type": "text", "text": "valor"})
Cabeçalho de imagem: Use objetos de parâmetros com type e image.link (ex. {"type": "image", "image": {"link": "https://..."}})

Parâmetros do corpo

Use objetos de parâmetros com type e text (ex. {"type": "text", "text": "valor"}) que substituam {{1}}, {{2}}, etc. no corpo do modelo.

Parâmetros nomeados

Se o modelo foi criado com o formato de parâmetros nomeados, adicione um parameter_name a cada objeto de parâmetro em vez de depender da posição. O nome deve corresponder à variável utilizada no modelo (ex. {{customer_name}}):

"body": [
    {"type": "text", "parameter_name": "customer_name", "text": "Max Mustermann"},
    {"type": "text", "parameter_name": "appointment_date", "text": "2026-02-15"}
]

Os valores dos parâmetros não podem conter quebras de linha, tabulações nem mais de quatro espaços consecutivos - o WhatsApp rejeita essas mensagens.

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
index
Type
integer
Description
Posição do botão no modelo, começando em zero (0 para o primeiro botão, 1 para o segundo, ...). Obrigatório em cada objeto de botão. Se index estiver ausente, a requisição é aceita com HTTP 200, mas a entrega falha depois com o código de erro 100 no journal.
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": [{"type": "text", "text": "Confirmação de consulta"}],
        "body": [
            {"type": "text", "text": "Max Mustermann"},
            {"type": "text", "text": "15/02/2026"},
            {"type": "text", "text": "14:00"},
            {"type": "text", "text": "Dr. Schmidt"}
        ],
        "buttons": [
            {
                "type": "button",
                "sub_type": "url",
                "index": 0,
                "parameters": [{"type": "text", "text": "abc123"}]
            }
        ]
    }
}

Cabeçalho de imagem + Corpo

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

Validação de modelos

As solicitações de modelo são verificadas em relação aos modelos da sua conta do WhatsApp Business antes de entrarem na fila. Se o modelo não existir no idioma solicitado, não estiver aprovado (p. ex. PENDING, REJECTED, PAUSED) ou o número de parâmetros de cabeçalho/corpo não corresponder aos seus marcadores, a solicitação é rejeitada imediatamente com HTTP 400 e uma error_message que descreve o problema, p. ex. Template "appointment_reminder" (de) expects 2 body parameter(s) (customer_name, appointment_date), got 1. Use Listar modelos para consultar nomes, idiomas, status e variáveis.

GET/api/waba/templates

Listar modelos

Retorna os modelos de mensagem da conta do WhatsApp Business associada a um número remetente, incluindo o status de aprovação e as variáveis a preencher no envio.

Parâmetros

Name
from
Type
string
Description
Seu número remetente do WhatsApp Business registrado. Determina a conta do WhatsApp Business cujos modelos são retornados.
Name
name
Type
string
Optional
Optional
Description
Retornar apenas modelos com exatamente este nome.
Name
status
Type
string
Optional
Optional
Description
Retornar apenas modelos com este status, p. ex. APPROVED, PENDING, REJECTED, PAUSED.

Campos da resposta

Name
status
Type
string
Description
Status de aprovação informado pelo WhatsApp. Somente modelos APPROVED podem ser enviados.
Name
rejected_reason
Type
string
Description
Motivo de rejeição informado pelo WhatsApp; caso contrário, null.
Name
parameter_format
Type
string
Description
POSITIONAL ({{1}}, {{2}}, ...) ou NAMED ({{customer_name}}). Em modelos NAMED, envie os nomes das variáveis como parameter_name.
Name
variables
Type
object
Description
Marcadores a preencher no envio, em ordem: header e body contêm os nomes das variáveis (ou números em modelos posicionais), buttons lista os botões que precisam de um parâmetro com seu index.
Name
components
Type
array
Description
Definição do modelo conforme fornecida pelo WhatsApp (textos, formato do cabeçalho, botões).

Alterações de status e edições são aplicadas automaticamente em segundos. Se os modelos de uma conta recém-conectada ainda não tiverem sido carregados, o endpoint responde com HTTP 503 e um cabeçalho Retry-After; tente novamente após alguns segundos.

Request

GET

/api/waba/templates

curl "https://gateway.seven.io/api/waba/templates?from=4915112345678&status=APPROVED" \
    -H "X-Api-Key: YOUR_API_KEY"

Response

{
    "templates": [
        {
            "id": "1234567890123456",
            "name": "appointment_reminder",
            "language": "de",
            "status": "APPROVED",
            "category": "UTILITY",
            "rejected_reason": null,
            "parameter_format": "NAMED",
            "variables": {
                "header": [],
                "body": ["customer_name", "appointment_date"],
                "buttons": [{"index": 0, "type": "URL"}]
            },
            "components": [
                {"type": "BODY", "text": "Hello {{customer_name}}, see you on {{appointment_date}}."},
                {"type": "BUTTONS", "buttons": [{"type": "URL", "text": "Details", "url": "https://example.com/{{1}}"}]}
            ]
        }
    ]
}

Response (templates loading)

{
    "error_code": 503,
    "error_message": "Templates are being loaded, please retry in a few seconds"
}

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
message_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",
      "message_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. O status final de entrega (entregue, lido, falhou) é informado de forma assíncrona pelo webhook dlr e no journal.
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
503
Description
Os modelos estão sendo carregados (apenas Listar modelos). Tente novamente após alguns segundos.
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.