VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/WhatsApp: caixa de entrada

Mensagens enviadas

Envia mensagens avulsas (teste, texto ou template), consulta o histórico de envios e reenfileira os que falharam.

Esta página trata das mensagens que a plataforma envia (notificações de pedido, campanhas, envios manuais), separadas das conversas da caixa de entrada. Cada envio é um registro com status. Fora da janela de 24 horas o WhatsApp só aceita templates: modelos de mensagem pré-aprovados pela Meta, com variáveis numeradas ({{1}}, {{2}}).

Enviar mensagem de teste

Manda um texto simples pelo número configurado. Serve para provar que o token e o número funcionam.

POST/api/v1/admin/whatsapp/testAdmin

Envia um texto de teste para conferir a configuração

Corpo da requisição

phone_numberstringobrigatório
Telefone com código do país, 10 a 15 dígitos, + opcional.
messagestring
Texto. Vazio usa uma mensagem de teste padrão.

Exemplo de requisição (Enviar mensagem de teste)

bash
curl -X POST "$BASE_URL/api/v1/admin/whatsapp/test" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+5511999998888",
    "message": "Teste de integração"
  }'

Resposta (Enviar mensagem de teste)

200Enviada
json
{
  "success": true,
  "message": {
    "id": 2092,
    "phone_number": "5511999998888",
    "message_type": "text",
    "params": {
      "body": "Teste de integração"
    },
    "status": "sent",
    "whatsapp_message_id": "wamid.HBgNNTUx..."
  }
}

Campos da resposta

successboolean
true.
messageobject
O registro da mensagem (campos na rota de histórico, abaixo).

Erros (Enviar mensagem de teste)

StatusQuandoCorpo
400Corpo inválido, phone_number ausente ou fora do formato.{"error":"invalid phone number format: must start with country code and contain 10-15 digits (e.g. +5511999998888)"}
401Sem token, token inválido ou expirado.{"error":"missing authorization header"}
403O módulo WhatsApp Commerce está desligado na loja, o usuário não é administrador ou não tem o privilégio exigido.{"error":"module_disabled","module":"whatsapp-commerce"} ou {"error":"insufficient privileges","required":"manage_settings"} ou {"error":"admin access required"}
500A Meta recusou o envio.{"error":"Failed to send test message: ..."}
Envia mesmo

Esta rota entrega a mensagem a um telefone real. Use o seu número.

Enviar mensagem avulsa

Envia template (permitido a qualquer momento) ou text (só dentro da janela de 24 horas). Os parâmetros do template são lidos nas chaves "1", "2", em sequência: se faltar uma chave no meio, as seguintes são ignoradas.

POST/api/v1/admin/whatsapp/sendAdmin

Envia um template ou um texto a um telefone

Corpo da requisição

phone_numberstringobrigatório
Telefone com código do país, 10 a 15 dígitos.
message_typestringobrigatório
templatetext
Tipo de envio.
template_namestring
Nome do template aprovado. Obrigatório com template.
paramsobject
Variáveis do template como {"1":"...","2":"..."}.
text_bodystring
Texto. Obrigatório com text.

Exemplo de requisição (Enviar mensagem avulsa)

bash
curl -X POST "$BASE_URL/api/v1/admin/whatsapp/send" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+5511999998888",
    "message_type": "template",
    "template_name": "order_confirmation",
    "params": {
      "1": "PEDIDO-20261011-0004",
      "2": "R$ 225,00"
    }
  }'

Resposta (Enviar mensagem avulsa)

200Enviada
json
{
  "success": true,
  "message": {
    "id": 2093,
    "phone_number": "5511999998888",
    "template_name": "order_confirmation",
    "message_type": "template",
    "params": {
      "1": "PEDIDO-20261011-0004",
      "2": "R$ 225,00"
    },
    "status": "sent",
    "whatsapp_message_id": "wamid.HBgNNTUx..."
  }
}

Campos da resposta

successboolean
true.
messageobject
O registro da mensagem.

Erros (Enviar mensagem avulsa)

StatusQuandoCorpo
400Campo obrigatório ausente, telefone fora do formato, ou message_type diferente de template/text.{"error":"message_type must be 'template' or 'text'"}
401Sem token, token inválido ou expirado.{"error":"missing authorization header"}
403O módulo WhatsApp Commerce está desligado na loja, o usuário não é administrador ou não tem o privilégio exigido.{"error":"module_disabled","module":"whatsapp-commerce"} ou {"error":"insufficient privileges","required":"manage_settings"} ou {"error":"admin access required"}
500A Meta recusou. A resposta traz error e a message registrada com status: failed.{"error":"...","message":{"status":"failed"}}

Histórico de envios

Mostra cada envio, do mais novo para o mais antigo, com o status. Use para auditar notificações e achar falhas.

GET/api/v1/admin/whatsapp/messagesAdmin

Lista as mensagens enviadas pela plataforma, com filtros

Parâmetros de consulta

pageintegerpadrão: 1
Página.
per_pageintegerpadrão: 20
Itens por página.
statusstring
pendingsentdeliveredreadfailed
Status do envio.
template_namestring
Nome exato do template.
phone_numberstring
Telefone exato.
order_idstring
UUID do pedido relacionado.

Exemplo de requisição (Histórico de envios)

bash
curl "$BASE_URL/api/v1/admin/whatsapp/messages?status=failed&per_page=20" \
  -H "Authorization: Bearer $TOKEN"

Resposta (Histórico de envios)

200Histórico
json
{
  "messages": [
    {
      "id": 2079,
      "phone_number": "5511996225151",
      "template_name": "vendor_new_order",
      "message_type": "template",
      "params": {
        "1": "PEDIDO-20261011-0009",
        "2": "R$ 52,66"
      },
      "status": "failed",
      "error_message": "whatsapp api error (100): ...",
      "vendor_id": "9d9d9d56-eb43-4719-889d-055632f7c7da",
      "created_at": "2026-10-11T20:59:55Z"
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 20,
  "total_pages": 1
}

Campos da resposta

messagesarray

Envios da página.

idinteger
Id do envio.
phone_numberstring
Telefone de destino (só dígitos ou com +, como foi registrado).
template_namestring
Template usado, se houve.
message_typestring
template, text ou interactive.
paramsobject
Variáveis do template ou {"body": ...} para texto.
statusstring
pendingsentdeliveredreadfailed
Situação: pending, sent, delivered, read ou failed.
whatsapp_message_idstring
Id na Meta, quando enviado.
error_messagestring
Motivo da falha, quando failed.
order_idstring
Pedido relacionado, se houver.
vendor_idstring
Seller relacionado, se houver.
created_atstring
Registro, RFC 3339.
totalinteger
Total.
pageinteger
Página.
per_pageinteger
Itens por página.
total_pagesinteger
Páginas.

Erros (Histórico de envios)

StatusQuandoCorpo
401Sem token, token inválido ou expirado.{"error":"missing authorization header"}
403O módulo WhatsApp Commerce está desligado na loja, o usuário não é administrador ou não tem o privilégio exigido.{"error":"module_disabled","module":"whatsapp-commerce"} ou {"error":"insufficient privileges","required":"manage_settings"} ou {"error":"admin access required"}
Duas formas de status

Aqui o status vem por extenso (failed). Nas mensagens da conversa ele vem como letra (F). Não compare os dois sem converter.

Reenfileirar um envio que falhou

Recoloca na fila de envio uma linha que esteja em falha, zerando as tentativas, para a plataforma tentar de novo na hora. Só afeta linhas em falha. Sem corpo.

POST/api/v1/admin/whatsapp/queue/{id}/retryAdmin

Coloca de volta na fila um envio que falhou

Parâmetros de caminho

idstringobrigatório
UUID da linha da fila de envio.

Exemplo de requisição (Reenfileirar um envio que falhou)

bash
curl -X POST "$BASE_URL/api/v1/admin/whatsapp/queue/3f0f7c1e-5b0a-4f3e-9d1a-2c3b4a5d6e7f/retry" \
  -H "Authorization: Bearer $TOKEN"

Resposta (Reenfileirar um envio que falhou)

200Reenfileirado
json
{
  "retried": true
}

Campos da resposta

retriedboolean
true.

Erros (Reenfileirar um envio que falhou)

StatusQuandoCorpo
401Sem token, token inválido ou expirado.{"error":"missing authorization header"}
403O módulo WhatsApp Commerce está desligado na loja, o usuário não é administrador ou não tem o privilégio exigido.{"error":"module_disabled","module":"whatsapp-commerce"} ou {"error":"insufficient privileges","required":"manage_settings"} ou {"error":"admin access required"}
404A linha não existe ou não está em estado de falha.{"error":"queue row not found or not in failed state"}

Veja também

  • Responder ao cliente
  • Templates da Meta
Anterior
Busca de mensagens e métricas
Próxima
Representantes e aprovação de desconto
Nesta página
  • Enviar mensagem de teste
  • Exemplo de requisição (Enviar mensagem de teste)
  • Resposta (Enviar mensagem de teste)
  • Erros (Enviar mensagem de teste)
  • Enviar mensagem avulsa
  • Exemplo de requisição (Enviar mensagem avulsa)
  • Resposta (Enviar mensagem avulsa)
  • Erros (Enviar mensagem avulsa)
  • Histórico de envios
  • Exemplo de requisição (Histórico de envios)
  • Resposta (Histórico de envios)
  • Erros (Histórico de envios)
  • Reenfileirar um envio que falhou
  • Exemplo de requisição (Reenfileirar um envio que falhou)
  • Resposta (Reenfileirar um envio que falhou)
  • Erros (Reenfileirar um envio que falhou)
  • Veja também