Enviar un mensaje#
/v1/messagesEncola un texto, una plantilla (con sus datos y, si la tiene, el archivo del encabezado), una foto o un documento. Responde 202 con el mensaje en cola: el estado llega después (consúltalo con GET /v1/messages/{id}). Lo que envía la API no reabre ni asigna la conversación en la bandeja, y pasa por detrás de lo que escriben las personas. Usa siempre Idempotency-Key: un reintento con la misma clave no envía dos veces.
Parámetros
| Campo | Dónde | Tipo | Descripción |
|---|---|---|---|
Idempotency-Key | cabecera | string | Una clave única por operación lógica (un UUID), de 1 a 255 caracteres ASCII visibles. Vale 24 horas: un reintento con la misma clave y el mismo contenido repite la respuesta sin repetir el efecto. |
Cuerpo · application/json
Un mensaje: texto, plantilla, foto o documento. type dice cuál de text, template, image o document va; los demás no.
Con type: "text"
| Campo | Tipo | Descripción |
|---|---|---|
numberobligatorio | string | Desde qué número se envía. |
toobligatorio | string | El destino: un teléfono en formato internacional (+593991234567) o el BSUID del contacto. |
client_reference | string | Tu referencia (una factura, una cita). Vuelve en el mensaje y sirve para filtrar. No es única. |
ttl | integer | Segundos que se intenta enviar antes de darlo por vencido (expired). Por omisión, 86.400 (24 horas). |
typeobligatorio | "text" | |
textobligatorio | object | |
text.bodyobligatorio | string | El texto: hasta 1.024 caracteres. Solo dentro de las 24 horas desde el último mensaje del contacto. |
Con type: "template"
| Campo | Tipo | Descripción |
|---|---|---|
numberobligatorio | string | Desde qué número se envía. |
toobligatorio | string | El destino: un teléfono en formato internacional (+593991234567) o el BSUID del contacto. |
client_reference | string | Tu referencia (una factura, una cita). Vuelve en el mensaje y sirve para filtrar. No es única. |
ttl | integer | Segundos que se intenta enviar antes de darlo por vencido (expired). Por omisión, 86.400 (24 horas). |
typeobligatorio | "template" | |
templateobligatorio | object | |
template.nameobligatorio | string | |
template.language | string | El idioma de la plantilla (es, es_MX…). Por omisión, es. |
template.params | object | Los datos que pide la plantilla: GET /v1/templates dice cuáles, con su ruta. |
template.params.header | object (clave → string) | Nombre de la variable (o su posición, o el índice del botón) → texto. Hasta 30 datos. |
template.params.body | object (clave → string) | Nombre de la variable (o su posición, o el índice del botón) → texto. Hasta 30 datos. |
template.params.buttons | object (clave → string) | Nombre de la variable (o su posición, o el índice del botón) → texto. Hasta 30 datos. |
template.params.header_media | object | El archivo del encabezado, si la plantilla lleva imagen o documento. |
Con type: "image"
| Campo | Tipo | Descripción |
|---|---|---|
numberobligatorio | string | Desde qué número se envía. |
toobligatorio | string | El destino: un teléfono en formato internacional (+593991234567) o el BSUID del contacto. |
client_reference | string | Tu referencia (una factura, una cita). Vuelve en el mensaje y sirve para filtrar. No es única. |
ttl | integer | Segundos que se intenta enviar antes de darlo por vencido (expired). Por omisión, 86.400 (24 horas). |
typeobligatorio | "image" | |
imageobligatorio | object | |
image.media_idobligatorio | string | El archivo subido con POST /v1/media. |
image.caption | string | Hasta 1.024 caracteres. |
Con type: "document"
| Campo | Tipo | Descripción |
|---|---|---|
numberobligatorio | string | Desde qué número se envía. |
toobligatorio | string | El destino: un teléfono en formato internacional (+593991234567) o el BSUID del contacto. |
client_reference | string | Tu referencia (una factura, una cita). Vuelve en el mensaje y sirve para filtrar. No es única. |
ttl | integer | Segundos que se intenta enviar antes de darlo por vencido (expired). Por omisión, 86.400 (24 horas). |
typeobligatorio | "document" | |
documentobligatorio | object | |
document.media_idobligatorio | string | El archivo subido con POST /v1/media. |
document.caption | string | Hasta 1.024 caracteres. |
Respuesta · 202
El mensaje, en cola. Location apunta a él.
| Campo | Tipo | Descripción |
|---|---|---|
objectobligatorio | "message" | |
idobligatorio | string | El id del mensaje (msg_…). |
numberobligatorio | object | |
number.idobligatorio | string | El id del número (num_…). |
number.phoneobligatorio | string o null | El teléfono del número, en E.164. |
contactobligatorio | object | El contacto: por su teléfono o, si no lo muestra, por su BSUID. |
contact.phoneobligatorio | string o null | El teléfono del contacto, en E.164, si se conoce. |
contact.user_idobligatorio | string o null | El BSUID del contacto, si se conoce. |
contact.nameobligatorio | string o null | El nombre de su perfil de WhatsApp. Solo con messages:read. |
directionobligatorio | uno de: "inbound", "outbound" | |
typeobligatorio | uno de: "text", "template", "image", "document", "audio", "video", "sticker", "location", "contacts", "interactive", "button", "reaction", "unsupported" | El tipo. Lo que llega puede ser de más tipos que lo que se envía. |
textobligatorio | string o null | El texto, el comentario del archivo o el texto de la plantilla ya compuesto. |
templateobligatorio | object o null | |
template.nameobligatorio | string | |
template.languageobligatorio | string o null | |
mediaobligatorio | object o null | |
media.idobligatorio | string o null | El archivo subido por la API con que se envió; null en los demás. |
media.kindobligatorio | string | |
media.content_typeobligatorio | string o null | |
media.filenameobligatorio | string o null | |
media.captionobligatorio | string o null | |
media.size_bytesobligatorio | integer o null | |
statusobligatorio | uno de: "queued", "sending", "accepted", "sent", "delivered", "read", "failed", "received" | queued y sending: en la cola. accepted, sent, delivered y read: lo que dice WhatsApp. failed: no salió (mira error). received: lo que llega. |
errorobligatorio | object o null | |
error.codeobligatorio | string | Por qué falló (catálogo de errores del mensaje). |
error.messageobligatorio | string | |
error.meta_codeobligatorio | integer o null | El código de error de Meta, si viene de Meta. |
client_referenceobligatorio | string o null | La referencia de tu sistema, tal como la enviaste. |
sent_byobligatorio | uno de varios o null | Quién pidió el envío: una clave, una persona de la consola, el sistema o la app WhatsApp Business del teléfono. null en lo que llega. |
whatsapp_idobligatorio | string o null | El id de WhatsApp (wamid), cuando WhatsApp lo acepta. |
created_atobligatorio | integer | Cuándo se creó el mensaje (o cuándo llegó). |
status_updated_atobligatorio | integer o null | Cuándo cambió su estado por última vez. |
expires_atobligatorio | integer o null | Mientras sigue en cola: hasta cuándo se intenta enviar (ttl). |
reply_toobligatorio | string o null | El whatsapp_id del mensaje al que responde, si responde a uno. |
interactiveobligatorio | object o null | El botón o la opción que eligió el contacto. |
interactive.typeobligatorio | uno de: "button_reply", "list_reply", "button" | Un botón o una opción de una lista, o el botón de una plantilla. |
interactive.idobligatorio | string o null | El id del botón o de la opción (el payload del botón de una plantilla). |
interactive.titleobligatorio | string o null | |
locationobligatorio | object o null | La ubicación que compartió el contacto. |
location.latitudeobligatorio | number o null | |
location.longitudeobligatorio | number o null | |
location.nameobligatorio | string o null | |
location.addressobligatorio | string o null | |
reactionobligatorio | object o null | Una reacción a otro mensaje. Sin emoji, quitó su reacción. |
reaction.emojiobligatorio | string o null | |
reaction.message_whatsapp_idobligatorio | string o null | El whatsapp_id del mensaje al que reaccionó. |
referralobligatorio | object o null | El anuncio que trajo al contacto (clic a WhatsApp), si vino por uno. |
referral.source_typeobligatorio | string o null | |
referral.source_idobligatorio | string o null | |
referral.source_urlobligatorio | string o null | |
referral.headlineobligatorio | string o null | |
referral.ctwa_clidobligatorio | string o null |
Ejemplo: Plantilla con datos
curl -X POST 'https://api.stack-netic.com/v1/messages' \
-H "Authorization: Bearer $STACKNETIC_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
--data '{
"number": "num_02y8w48sgGf2ztA7qbjqso",
"to": "+593991234567",
"type": "template",
"template": {
"name": "recordatorio_cita",
"language": "es",
"params": {
"body": {
"nombre": "Ana",
"fecha": "martes 12 de octubre",
"hora": "10:00"
}
}
},
"client_reference": "cita-8841",
"ttl": 3600
}'const res = await fetch("https://api.stack-netic.com/v1/messages", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.STACKNETIC_API_KEY}`,
"Idempotency-Key": crypto.randomUUID(),
"Content-Type": "application/json",
},
body: JSON.stringify({
"number": "num_02y8w48sgGf2ztA7qbjqso",
"to": "+593991234567",
"type": "template",
"template": {
"name": "recordatorio_cita",
"language": "es",
"params": {
"body": {
"nombre": "Ana",
"fecha": "martes 12 de octubre",
"hora": "10:00"
}
}
},
"client_reference": "cita-8841",
"ttl": 3600
}),
});
const data = await res.json();
if (!res.ok) throw new Error(`${data.code}: ${data.detail}`);
console.log(data);import os
import uuid
import requests
res = requests.post(
"https://api.stack-netic.com/v1/messages",
headers={
"Authorization": f"Bearer {os.environ['STACKNETIC_API_KEY']}",
"Idempotency-Key": str(uuid.uuid4()),
},
json={
"number": "num_02y8w48sgGf2ztA7qbjqso",
"to": "+593991234567",
"type": "template",
"template": {
"name": "recordatorio_cita",
"language": "es",
"params": {
"body": {
"nombre": "Ana",
"fecha": "martes 12 de octubre",
"hora": "10:00",
},
},
},
"client_reference": "cita-8841",
"ttl": 3600,
},
timeout=30,
)
data = res.json()
if not res.ok:
raise RuntimeError(f"{data['code']}: {data['detail']}")
print(data)<?php
$ch = curl_init('https://api.stack-netic.com/v1/messages');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => json_encode([
'number' => 'num_02y8w48sgGf2ztA7qbjqso',
'to' => '+593991234567',
'type' => 'template',
'template' => [
'name' => 'recordatorio_cita',
'language' => 'es',
'params' => [
'body' => [
'nombre' => 'Ana',
'fecha' => 'martes 12 de octubre',
'hora' => '10:00',
],
],
],
'client_reference' => 'cita-8841',
'ttl' => 3600,
]),
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . getenv('STACKNETIC_API_KEY'),
'Idempotency-Key: ' . bin2hex(random_bytes(16)),
'Content-Type: application/json',
],
CURLOPT_RETURNTRANSFER => true,
]);
$data = json_decode(curl_exec($ch), true);
if (curl_getinfo($ch, CURLINFO_RESPONSE_CODE) >= 400) {
throw new RuntimeException($data['code'] . ': ' . $data['detail']);
}
print_r($data);{
"object": "message",
"id": "msg_02y9HflgNTRjaQMubfP6vm",
"number": {
"id": "num_02y8w48sgGf2ztA7qbjqso",
"phone": "+593969847312"
},
"contact": {
"phone": "+593991234567",
"user_id": null,
"name": null
},
"direction": "outbound",
"type": "template",
"text": "Hola Ana, te esperamos el martes 12 de octubre a las 10:00.",
"template": {
"name": "recordatorio_cita",
"language": "es"
},
"media": null,
"status": "queued",
"error": null,
"client_reference": "cita-8841",
"sent_by": {
"type": "api_key",
"id": "key_02y9HfsYGgsLoqUuhdpNYk",
"name": "Facturador producción"
},
"whatsapp_id": null,
"created_at": 1790546400,
"status_updated_at": 1790546400,
"expires_at": 1790550000,
"reply_to": null,
"interactive": null,
"location": null,
"reaction": null,
"referral": null
}Errores
BAD_REQUEST· 400 · La petición está mal formadaAPI_KEY_EXPIRED· 401 · La clave caducóAPI_KEY_INVALID· 401 · La clave no es válidaAPI_KEY_REVOKED· 401 · La clave está revocadaAPI_KEY_SUSPENDED· 401 · La clave está suspendidaUNAUTHENTICATED· 401 · Falta la claveFEATURE_NOT_ENABLED· 403 · Esa función no está activa en este espacioFORBIDDEN· 403 · No se puede hacerINSUFFICIENT_SCOPE· 403 · La clave no tiene ese permisoREAD_ONLY· 403 · El espacio está en solo lecturaTEMPLATE_CATEGORY_NOT_ALLOWED· 403 · La clave no puede enviar esa categoríaNOT_FOUND· 404 · No existeCONFLICT· 409 · ConflictoUPLOAD_USED· 409 · El archivo ya se usóUPLOAD_EXPIRED· 410 · El archivo caducóPAYLOAD_TOO_LARGE· 413 · Demasiado grandeUNSUPPORTED_MEDIA_TYPE· 415 · Tipo no admitidoIDEMPOTENCY_KEY_REUSED· 422 · Esa clave de idempotencia ya se usó con otra peticiónTEMPLATE_NOT_FOUND· 422 · La plantilla no existeTEMPLATE_NOT_SENDABLE· 422 · La plantilla no se puede enviarVALIDATION_FAILED· 422 · Los datos no son válidosDAILY_LIMIT_REACHED· 429 · La clave llegó a su tope diarioQUEUE_FULL· 429 · Hay demasiados mensajes esperandoRATE_LIMITED· 429 · Demasiadas peticionesINTERNAL· 500 · Error internoMETA_ERROR· 502 · WhatsApp no respondió como se esperabaNOT_CONFIGURED· 503 · El número no puede enviar ahora