Ir para o conteúdo
WhatsMarketingDeveloper Hub

Mensagens

Enviar uma mensagem de WhatsApp a um número e consultar como ela ficou. Um modelo aprovado vai para qualquer número; um texto livre, só se a pessoa escreveu para você nas últimas 24 h, e fica na conversa dela na caixa de entrada para que a equipe veja. Até 1.000 envios por chave e dia (UTC) e 20 para o mesmo número. Veja o guia Enviar mensagens.

Enviar uma mensagem

POST/messages

type: template envia um modelo aprovado (templateId, e variables se tiver) a qualquer número: se o número não for de nenhum contato, ele é criado com contactName, e o custo é cobrado do saldo. type: text envia text pela conversa da caixa de entrada, só se a pessoa escreveu nas últimas 24 h. Sai por phoneNumberId ou, se faltar, pela primeira linha conectada. Nunca para quem retirou o consentimento. Envie sempre Idempotency-Key: depois de um 502 SEND_UNCERTAIN a mensagem pode ter saído, e repetir com a mesma chave não a duplica. Precisa de messages:send.

Permissões: messages:send

Parâmetros

NomeOndeTipoValores
Idempotency-Keycabeçalhostring1–255 caracteres

Corpo da requisição SendMessage

NomeTipoValores
to obrigatóriostring0–32 caracteres · ^[+\d\s().-]+$
type obrigatóriostringtemplate · text
templateIduuid
variablesobject
textstring0–4096 caracteres
phoneNumberIduuid
contactNamestring0–120 caracteres

Erros frequentes

  • 400 INVALID_PHONE O número não é válido: use o formato internacional.
  • 400 TEMPLATE_NOT_APPROVED O modelo ainda não foi aprovado pela Meta.
  • 400 CONTACT_OPTED_OUT A pessoa retirou o consentimento: nada é enviado a ela.
  • 400 NO_PHONE_NUMBER Não há linha de WhatsApp conectada (ou phoneNumberId não é sua).
  • 404 TEMPLATE_NOT_FOUND O modelo não existe ou não é da sua organização.
  • 409 OUTSIDE_SERVICE_WINDOW Passaram mais de 24 h desde a última mensagem da pessoa, ou ela nunca escreveu: envie um modelo.
  • 409 NO_INBOX A linha não tem caixa de entrada para texto livre: envie um modelo.
  • 429 DAILY_LIMIT_REACHED A chave já fez 1.000 envios hoje (UTC).
  • 429 RECIPIENT_DAILY_LIMIT_REACHED Esse número já recebeu 20 mensagens pela API hoje (UTC).
  • 502 SEND_UNCERTAIN Não sabemos se saiu. Repita só com a mesma Idempotency-Key.
  • 502 INBOX_UNAVAILABLE A caixa de entrada não respondeu; tente de novo em instantes.
curl
curl -X POST "https://micuenta.whatsmarketing.es/api/v1/messages" \
  -H "Authorization: Bearer $WM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "to": "+34600111222",
  "type": "template",
  "templateId": "6f1c2b9e-3a4d-4e5f-8a7b-9c0d1e2f3a4b",
  "variables": {
    "1": "Ana"
  },
  "contactName": "Ana García"
}'
Node.js
const res = await fetch('https://micuenta.whatsmarketing.es/api/v1/messages', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.WM_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "to": "+34600111222",
    "type": "template",
    "templateId": "6f1c2b9e-3a4d-4e5f-8a7b-9c0d1e2f3a4b",
    "variables": {
      "1": "Ana"
    },
    "contactName": "Ana García"
  }),
});
const data = await res.json();
Python
import os, requests

r = requests.post(
    "https://micuenta.whatsmarketing.es/api/v1/messages",
    headers={"Authorization": f"Bearer {os.environ['WM_API_KEY']}"},
    json={
        "to": "+34600111222",
        "type": "template",
        "templateId": "6f1c2b9e-3a4d-4e5f-8a7b-9c0d1e2f3a4b",
        "variables": {
            "1": "Ana"
        },
        "contactName": "Ana García"
    },
    timeout=30,
)
r.raise_for_status()
data = r.json()
PHP
<?php
$ch = curl_init('https://micuenta.whatsmarketing.es/api/v1/messages');
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer ' . getenv('WM_API_KEY'),
    'Content-Type: application/json',
  ],
  CURLOPT_POSTFIELDS => json_encode([
    'to' => '+34600111222',
    'type' => 'template',
    'templateId' => '6f1c2b9e-3a4d-4e5f-8a7b-9c0d1e2f3a4b',
    'variables' => [
      '1' => 'Ana'
    ],
    'contactName' => 'Ana García'
  ]),
]);
$data = json_decode(curl_exec($ch), true);
Resposta 200
{
  "id": "tpl_6f1c2b9e-3a4d-4e5f-8a7b-9c0d1e2f3a4b",
  "type": "template",
  "to": "+34600111222",
  "status": "PENDING",
  "error": null
}

Status de uma mensagem

GET/messages/{id}

Com o id que o envio devolveu: PENDING, SENT, DELIVERED, READ ou FAILED (com o motivo em error). Um texto antigo que já não aparece na conversa volta como UNKNOWN. No status de um texto, to é null. Responde 404 se a mensagem não for da sua organização. Precisa de messages:send.

Permissões: messages:send

Parâmetros

NomeOndeTipoValores
id obrigatóriorotastring
curl
curl "https://micuenta.whatsmarketing.es/api/v1/messages/{id}" \
  -H "Authorization: Bearer $WM_API_KEY"
Node.js
const res = await fetch('https://micuenta.whatsmarketing.es/api/v1/messages/{id}', {
  headers: {
    Authorization: `Bearer ${process.env.WM_API_KEY}`,
  },
});
const data = await res.json();
Python
import os, requests

r = requests.get(
    "https://micuenta.whatsmarketing.es/api/v1/messages/{id}",
    headers={"Authorization": f"Bearer {os.environ['WM_API_KEY']}"},
    timeout=30,
)
r.raise_for_status()
data = r.json()
PHP
<?php
$ch = curl_init('https://micuenta.whatsmarketing.es/api/v1/messages/{id}');
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer ' . getenv('WM_API_KEY'),
  ],
]);
$data = json_decode(curl_exec($ch), true);
Resposta 200
{
  "id": "tpl_6f1c2b9e-3a4d-4e5f-8a7b-9c0d1e2f3a4b",
  "type": "template",
  "to": "+34600111222",
  "status": "READ",
  "error": null
}