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
| Nome | Onde | Tipo | Valores |
|---|---|---|---|
Idempotency-Key | cabeçalho | string | 1–255 caracteres |
Corpo da requisição SendMessage
| Nome | Tipo | Valores |
|---|---|---|
to obrigatório | string | 0–32 caracteres · ^[+\d\s().-]+$ |
type obrigatório | string | template · text |
templateId | uuid | |
variables | object | |
text | string | 0–4096 caracteres |
phoneNumberId | uuid | |
contactName | string | 0–120 caracteres |
Erros frequentes
- 400
INVALID_PHONEO número não é válido: use o formato internacional. - 400
TEMPLATE_NOT_APPROVEDO modelo ainda não foi aprovado pela Meta. - 400
CONTACT_OPTED_OUTA pessoa retirou o consentimento: nada é enviado a ela. - 400
NO_PHONE_NUMBERNão há linha de WhatsApp conectada (ouphoneNumberIdnão é sua). - 404
TEMPLATE_NOT_FOUNDO modelo não existe ou não é da sua organização. - 409
OUTSIDE_SERVICE_WINDOWPassaram mais de 24 h desde a última mensagem da pessoa, ou ela nunca escreveu: envie um modelo. - 409
NO_INBOXA linha não tem caixa de entrada para texto livre: envie um modelo. - 429
DAILY_LIMIT_REACHEDA chave já fez 1.000 envios hoje (UTC). - 429
RECIPIENT_DAILY_LIMIT_REACHEDEsse número já recebeu 20 mensagens pela API hoje (UTC). - 502
SEND_UNCERTAINNão sabemos se saiu. Repita só com a mesmaIdempotency-Key. - 502
INBOX_UNAVAILABLEA caixa de entrada não respondeu; tente de novo em instantes.
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"
}'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();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
$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);{
"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
| Nome | Onde | Tipo | Valores |
|---|---|---|---|
id obrigatório | rota | string |
curl "https://micuenta.whatsmarketing.es/api/v1/messages/{id}" \
-H "Authorization: Bearer $WM_API_KEY"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();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
$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);{
"id": "tpl_6f1c2b9e-3a4d-4e5f-8a7b-9c0d1e2f3a4b",
"type": "template",
"to": "+34600111222",
"status": "READ",
"error": null
}