Desarrolladores

API de StackNetic

Envía mensajes de WhatsApp desde tu sistema —plantillas con datos, fotos y documentos— y consulta su estado, con los números de tu espacio.

En esta página

Introducción#

La API usa JSON y HTTPS, con los ids, las fechas y los errores de siempre en los servicios modernos. Todo lo que hace una clave queda en el registro de la consola durante 14 días, sin el contenido de los mensajes.

La URL base

https://api.stack-netic.com/v1

Autenticación

Cada petición lleva una clave del espacio en la cabecera Authorization. Las claves se crean en la consola, en Desarrolladores, y se muestran una sola vez: guárdala como secreto en tu servidor (por ejemplo, en la variable de entorno STACKNETIC_API_KEY), nunca en el código ni en una página web. La API no admite llamadas desde un navegador.

Authorization: Bearer $STACKNETIC_API_KEY

Para comprobar una clave sin tocar nada, GET /v1/key: responde con cualquier permiso, con lo que la clave puede hacer y lo que lleva enviado hoy.

Claves y permisos

Cada clave tiene sus permisos y sus números: lo justo para su sistema. Una clave nunca puede más que la persona que la creó, y si esa persona sale del espacio o pierde acceso, la clave se suspende.

PermisoIdentificadorQué permite
Enviar mensajesmessages:sendEnvía mensajes y archivos, y consulta lo que envía esta clave.
Leer mensajesmessages:readLee todos los mensajes de sus números, también los que llegan.
Ver plantillastemplates:readLista las plantillas y los datos que pide cada una.
Crear y borrar plantillastemplates:writeCrea plantillas y borra las que se crearon en este espacio.
Ver númerosnumbers:readConsulta los números, su estado y si pueden enviar.
Gestionar webhookswebhooks:writeCrea, prueba, edita y elimina sus propios endpoints de webhooks. Los eventos de mensajes piden además «Leer mensajes».

Guía rápida#

  1. Crea una clave en Desarrolladores con el permiso «Enviar mensajes» y guárdala en STACKNETIC_API_KEY.
  2. Lista tus números: el id de cada uno (num_…) es desde dónde envías.
  3. Lista las plantillas del número: cada una dice qué datos pide y dónde van en el envío.
  4. Envía la plantilla con sus datos y una Idempotency-Key. La respuesta es el mensaje en cola.
  5. Consulta su estado hasta delivered o failed.

1. Tus números

curl 'https://api.stack-netic.com/v1/numbers' \
  -H "Authorization: Bearer $STACKNETIC_API_KEY"

2. Las plantillas del número

curl 'https://api.stack-netic.com/v1/templates?number=num_02y8w48sgGf2ztA7qbjqso' \
  -H "Authorization: Bearer $STACKNETIC_API_KEY"

3. Enviar la plantilla

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
}'

4. Consultar el estado

curl 'https://api.stack-netic.com/v1/messages/msg_02y9HflgNTRjaQMubfP6vm' \
  -H "Authorization: Bearer $STACKNETIC_API_KEY"

Consulta el estado cada 10 s los primeros 2 minutos y después cada minuto, o mejor: recibe cada cambio al momento con los webhooks (message.status).

Conceptos#

Identificadores#

Cada id lleva el tipo delante y 22 caracteres: no se confunde un mensaje con un número. Un id que no es de su tipo responde 404, como uno que no existe.

PrefijoQué es
msg_…Un mensaje
med_…Un archivo subido
num_…Un número
wa_…Una cuenta de WhatsApp Business
key_…Una clave
req_…Una petición (en la cabecera Request-Id)
evt_…Un evento de los webhooks (en la cabecera webhook-id)
we_…Un endpoint de webhooks
ws_…Un espacio (el de la clave, en GET /v1/key)
call_…Una llamada de WhatsApp (en el evento call.ended de los webhooks)

Fechas, teléfonos y textos#

Las fechas van en segundos desde 1970 (epoch, UTC). Los teléfonos, en formato internacional E.164 (+593991234567); un contacto que no muestra su teléfono se identifica por su BSUID. Los textos, en UTF-8.

Errores#

Los errores siguen RFC 9457 (application/problem+json): un code estable para tu código, un detail en español para las personas y, si son datos, errors[] con la ruta de cada campo. El type lleva al código en el catálogo de errores.

{
  "type": "https://messaging.stack-netic.com/docs/api/errores#VALIDATION_FAILED",
  "title": "Los datos no son válidos",
  "status": 422,
  "detail": "Revisa 1 dato antes de enviar.",
  "code": "VALIDATION_FAILED",
  "request_id": "req_2bN4pQ8rT1vX3zA5cE7gH9",
  "errors": [
    {
      "path": "template.params.body.nombre",
      "code": "missing",
      "message": "Completa “Nombre”."
    }
  ]
}

Paginación#

Las listas devuelven data, has_more y next_cursor. Para la página siguiente, repite la petición con cursor=next_cursor y los mismos filtros; un cursor manipulado o con otros filtros responde 400 INVALID_CURSOR.

Idempotencia#

Manda una Idempotency-Key única (un UUID) en cada POST. Si la conexión se corta y reintentas con la misma clave y el mismo contenido, la API devuelve la respuesta de la primera —con Idempotent-Replayed: true— sin enviar el mensaje otra vez. Vale 24 horas. La misma clave con otro contenido responde 422 IDEMPOTENCY_KEY_REUSED.

Límites#

Cada respuesta dice su cuota en RateLimit-Policy y lo que queda en RateLimit. Al pasarla, 429 con Retry-After. Además, cada clave tiene un tope de envíos al día (por omisión 1000, hasta 10.000) que se reinicia a medianoche, hora de Ecuador.

QuéCuotaVentana
Enviar mensajes y marcarlos como leídos6001 min
Subir archivos601 min
Descargar archivos1201 min
Crear o borrar plantillas1010 min
Lecturas12001 min
Gestionar endpoints de webhooks6010 min

Versiones y cambios#

La versión va en la ruta (/v1). Dentro de la v1 solo se añaden cosas: campos nuevos en las respuestas, operaciones y códigos de error nuevos. Tu código tiene que ignorar los campos que no conoce. Un cambio que rompa llegará como /v2, con aviso.

Mensajes#

Enviar mensajes y consultar su estado.

Enviar un mensaje#

POST/v1/messages
Permiso: messages:sendAdmite Idempotency-Key

Encola 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

CampoDóndeTipoDescripción
Idempotency-KeycabecerastringUna 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"

CampoTipoDescripción
number
obligatorio
stringDesde qué número se envía.
to
obligatorio
stringEl destino: un teléfono en formato internacional (+593991234567) o el BSUID del contacto.
client_referencestringTu referencia (una factura, una cita). Vuelve en el mensaje y sirve para filtrar. No es única.
ttlintegerSegundos que se intenta enviar antes de darlo por vencido (expired). Por omisión, 86.400 (24 horas).
type
obligatorio
"text"
text
obligatorio
object
text.body
obligatorio
stringEl texto: hasta 1.024 caracteres. Solo dentro de las 24 horas desde el último mensaje del contacto.

Con type: "template"

CampoTipoDescripción
number
obligatorio
stringDesde qué número se envía.
to
obligatorio
stringEl destino: un teléfono en formato internacional (+593991234567) o el BSUID del contacto.
client_referencestringTu referencia (una factura, una cita). Vuelve en el mensaje y sirve para filtrar. No es única.
ttlintegerSegundos que se intenta enviar antes de darlo por vencido (expired). Por omisión, 86.400 (24 horas).
type
obligatorio
"template"
template
obligatorio
object
template.name
obligatorio
string
template.languagestringEl idioma de la plantilla (es, es_MX…). Por omisión, es.
template.paramsobjectLos datos que pide la plantilla: GET /v1/templates dice cuáles, con su ruta.
template.params.headerobject (clave → string)Nombre de la variable (o su posición, o el índice del botón) → texto. Hasta 30 datos.
template.params.bodyobject (clave → string)Nombre de la variable (o su posición, o el índice del botón) → texto. Hasta 30 datos.
template.params.buttonsobject (clave → string)Nombre de la variable (o su posición, o el índice del botón) → texto. Hasta 30 datos.
template.params.header_mediaobjectEl archivo del encabezado, si la plantilla lleva imagen o documento.

Con type: "image"

CampoTipoDescripción
number
obligatorio
stringDesde qué número se envía.
to
obligatorio
stringEl destino: un teléfono en formato internacional (+593991234567) o el BSUID del contacto.
client_referencestringTu referencia (una factura, una cita). Vuelve en el mensaje y sirve para filtrar. No es única.
ttlintegerSegundos que se intenta enviar antes de darlo por vencido (expired). Por omisión, 86.400 (24 horas).
type
obligatorio
"image"
image
obligatorio
object
image.media_id
obligatorio
stringEl archivo subido con POST /v1/media.
image.captionstringHasta 1.024 caracteres.

Con type: "document"

CampoTipoDescripción
number
obligatorio
stringDesde qué número se envía.
to
obligatorio
stringEl destino: un teléfono en formato internacional (+593991234567) o el BSUID del contacto.
client_referencestringTu referencia (una factura, una cita). Vuelve en el mensaje y sirve para filtrar. No es única.
ttlintegerSegundos que se intenta enviar antes de darlo por vencido (expired). Por omisión, 86.400 (24 horas).
type
obligatorio
"document"
document
obligatorio
object
document.media_id
obligatorio
stringEl archivo subido con POST /v1/media.
document.captionstringHasta 1.024 caracteres.

Respuesta · 202

El mensaje, en cola. Location apunta a él.

CampoTipoDescripción
object
obligatorio
"message"
id
obligatorio
stringEl id del mensaje (msg_…).
number
obligatorio
object
number.id
obligatorio
stringEl id del número (num_…).
number.phone
obligatorio
string o nullEl teléfono del número, en E.164.
contact
obligatorio
objectEl contacto: por su teléfono o, si no lo muestra, por su BSUID.
contact.phone
obligatorio
string o nullEl teléfono del contacto, en E.164, si se conoce.
contact.user_id
obligatorio
string o nullEl BSUID del contacto, si se conoce.
contact.name
obligatorio
string o nullEl nombre de su perfil de WhatsApp. Solo con messages:read.
direction
obligatorio
uno de: "inbound", "outbound"
type
obligatorio
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.
text
obligatorio
string o nullEl texto, el comentario del archivo o el texto de la plantilla ya compuesto.
template
obligatorio
object o null
template.name
obligatorio
string
template.language
obligatorio
string o null
media
obligatorio
object o null
media.id
obligatorio
string o nullEl archivo subido por la API con que se envió; null en los demás.
media.kind
obligatorio
string
media.content_type
obligatorio
string o null
media.filename
obligatorio
string o null
media.caption
obligatorio
string o null
media.size_bytes
obligatorio
integer o null
status
obligatorio
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.
error
obligatorio
object o null
error.code
obligatorio
stringPor qué falló (catálogo de errores del mensaje).
error.message
obligatorio
string
error.meta_code
obligatorio
integer o nullEl código de error de Meta, si viene de Meta.
client_reference
obligatorio
string o nullLa referencia de tu sistema, tal como la enviaste.
sent_by
obligatorio
uno de varios o nullQuié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_id
obligatorio
string o nullEl id de WhatsApp (wamid), cuando WhatsApp lo acepta.
created_at
obligatorio
integerCuándo se creó el mensaje (o cuándo llegó).
status_updated_at
obligatorio
integer o nullCuándo cambió su estado por última vez.
expires_at
obligatorio
integer o nullMientras sigue en cola: hasta cuándo se intenta enviar (ttl).
reply_to
obligatorio
string o nullEl whatsapp_id del mensaje al que responde, si responde a uno.
interactive
obligatorio
object o nullEl botón o la opción que eligió el contacto.
interactive.type
obligatorio
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.id
obligatorio
string o nullEl id del botón o de la opción (el payload del botón de una plantilla).
interactive.title
obligatorio
string o null
location
obligatorio
object o nullLa ubicación que compartió el contacto.
location.latitude
obligatorio
number o null
location.longitude
obligatorio
number o null
location.name
obligatorio
string o null
location.address
obligatorio
string o null
reaction
obligatorio
object o nullUna reacción a otro mensaje. Sin emoji, quitó su reacción.
reaction.emoji
obligatorio
string o null
reaction.message_whatsapp_id
obligatorio
string o nullEl whatsapp_id del mensaje al que reaccionó.
referral
obligatorio
object o nullEl anuncio que trajo al contacto (clic a WhatsApp), si vino por uno.
referral.source_type
obligatorio
string o null
referral.source_id
obligatorio
string o null
referral.source_url
obligatorio
string o null
referral.headline
obligatorio
string o null
referral.ctwa_clid
obligatorio
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
}'
{
  "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

Leer un mensaje#

GET/v1/messages/{id}
Permiso: messages:readPermiso: messages:send

El mensaje y su estado actual. Con messages:send, solo los que envió esta clave; con messages:read, todos los de sus números, también los que llegan.

Parámetros

CampoDóndeTipoDescripción
id
obligatorio
rutastringEl id del mensaje (msg_…).

Respuesta · 200

El mensaje.

CampoTipoDescripción
object
obligatorio
"message"
id
obligatorio
stringEl id del mensaje (msg_…).
number
obligatorio
object
number.id
obligatorio
stringEl id del número (num_…).
number.phone
obligatorio
string o nullEl teléfono del número, en E.164.
contact
obligatorio
objectEl contacto: por su teléfono o, si no lo muestra, por su BSUID.
contact.phone
obligatorio
string o nullEl teléfono del contacto, en E.164, si se conoce.
contact.user_id
obligatorio
string o nullEl BSUID del contacto, si se conoce.
contact.name
obligatorio
string o nullEl nombre de su perfil de WhatsApp. Solo con messages:read.
direction
obligatorio
uno de: "inbound", "outbound"
type
obligatorio
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.
text
obligatorio
string o nullEl texto, el comentario del archivo o el texto de la plantilla ya compuesto.
template
obligatorio
object o null
template.name
obligatorio
string
template.language
obligatorio
string o null
media
obligatorio
object o null
media.id
obligatorio
string o nullEl archivo subido por la API con que se envió; null en los demás.
media.kind
obligatorio
string
media.content_type
obligatorio
string o null
media.filename
obligatorio
string o null
media.caption
obligatorio
string o null
media.size_bytes
obligatorio
integer o null
status
obligatorio
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.
error
obligatorio
object o null
error.code
obligatorio
stringPor qué falló (catálogo de errores del mensaje).
error.message
obligatorio
string
error.meta_code
obligatorio
integer o nullEl código de error de Meta, si viene de Meta.
client_reference
obligatorio
string o nullLa referencia de tu sistema, tal como la enviaste.
sent_by
obligatorio
uno de varios o nullQuié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_id
obligatorio
string o nullEl id de WhatsApp (wamid), cuando WhatsApp lo acepta.
created_at
obligatorio
integerCuándo se creó el mensaje (o cuándo llegó).
status_updated_at
obligatorio
integer o nullCuándo cambió su estado por última vez.
expires_at
obligatorio
integer o nullMientras sigue en cola: hasta cuándo se intenta enviar (ttl).
reply_to
obligatorio
string o nullEl whatsapp_id del mensaje al que responde, si responde a uno.
interactive
obligatorio
object o nullEl botón o la opción que eligió el contacto.
interactive.type
obligatorio
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.id
obligatorio
string o nullEl id del botón o de la opción (el payload del botón de una plantilla).
interactive.title
obligatorio
string o null
location
obligatorio
object o nullLa ubicación que compartió el contacto.
location.latitude
obligatorio
number o null
location.longitude
obligatorio
number o null
location.name
obligatorio
string o null
location.address
obligatorio
string o null
reaction
obligatorio
object o nullUna reacción a otro mensaje. Sin emoji, quitó su reacción.
reaction.emoji
obligatorio
string o null
reaction.message_whatsapp_id
obligatorio
string o nullEl whatsapp_id del mensaje al que reaccionó.
referral
obligatorio
object o nullEl anuncio que trajo al contacto (clic a WhatsApp), si vino por uno.
referral.source_type
obligatorio
string o null
referral.source_id
obligatorio
string o null
referral.source_url
obligatorio
string o null
referral.headline
obligatorio
string o null
referral.ctwa_clid
obligatorio
string o null

Ejemplo: Entregado

curl 'https://api.stack-netic.com/v1/messages/msg_02y9HflgNTRjaQMubfP6vm' \
  -H "Authorization: Bearer $STACKNETIC_API_KEY"
{
  "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, adjuntamos su comprobante 001-002-000123 por $ 45,20. Gracias por su compra.",
  "template": {
    "name": "comprobante",
    "language": "es"
  },
  "media": {
    "id": "med_02y9HHPWRS3wHysjF22iwI",
    "kind": "document",
    "content_type": "application/pdf",
    "filename": "RIDE-001-002-000123.pdf",
    "caption": null,
    "size_bytes": 48213
  },
  "status": "delivered",
  "error": null,
  "client_reference": "fac-001-002-000123",
  "sent_by": {
    "type": "api_key",
    "id": "key_02y9HfsYGgsLoqUuhdpNYk",
    "name": "Facturador producción"
  },
  "whatsapp_id": "wamid.HBgMNTkzOTkxMjM0NTY3FQIAERgSMUQ3RjBBMkI2QjZBQTlGNjNBAA==",
  "created_at": 1790546400,
  "status_updated_at": 1790546412,
  "expires_at": null,
  "reply_to": null,
  "interactive": null,
  "location": null,
  "reaction": null,
  "referral": null
}

Errores

Listar mensajes#

GET/v1/messages
Permiso: messages:readPermiso: messages:send

Del más reciente al más antiguo, con cursor. Con messages:send, solo los que envió esta clave. Sirve para consultar, no para sincronizar sin huecos: para no perder nada, consulta desde since = la última marca vista menos 5 minutos y descarta los ids ya vistos (los avisos automáticos llegarán con los webhooks).

Parámetros

CampoDóndeTipoDescripción
numberconsultastringSolo los de este número.
contactconsultastringSolo los de este contacto: su teléfono o su BSUID.
directionconsultauno de: "inbound", "outbound"
statusconsultauno de: "queued", "sending", "accepted", "sent", "delivered", "read", "failed", "received"
client_referenceconsultastringSolo los que llevan esta referencia (exacta).
api_keyconsultastringSolo los que envió esta clave. Con messages:read.
sinceconsultaintegerDesde este momento (epoch), incluido.
untilconsultaintegerHasta este momento (epoch), incluido.
limitconsultaintegerCuántos por página: de 1 a 100.
cursorconsultastringEl next_cursor de la página anterior.

Respuesta · 200

Una página de mensajes.

CampoTipoDescripción
object
obligatorio
"list"
data
obligatorio
array de object
data[].object
obligatorio
"message"
data[].id
obligatorio
stringEl id del mensaje (msg_…).
data[].number
obligatorio
object
data[].number.id
obligatorio
stringEl id del número (num_…).
data[].number.phone
obligatorio
string o nullEl teléfono del número, en E.164.
data[].contact
obligatorio
objectEl contacto: por su teléfono o, si no lo muestra, por su BSUID.
data[].contact.phone
obligatorio
string o nullEl teléfono del contacto, en E.164, si se conoce.
data[].contact.user_id
obligatorio
string o nullEl BSUID del contacto, si se conoce.
data[].contact.name
obligatorio
string o nullEl nombre de su perfil de WhatsApp. Solo con messages:read.
data[].direction
obligatorio
uno de: "inbound", "outbound"
data[].type
obligatorio
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.
data[].text
obligatorio
string o nullEl texto, el comentario del archivo o el texto de la plantilla ya compuesto.
data[].template
obligatorio
object o null
data[].template.name
obligatorio
string
data[].template.language
obligatorio
string o null
data[].media
obligatorio
object o null
data[].media.id
obligatorio
string o nullEl archivo subido por la API con que se envió; null en los demás.
data[].media.kind
obligatorio
string
data[].media.content_type
obligatorio
string o null
data[].media.filename
obligatorio
string o null
data[].media.caption
obligatorio
string o null
data[].media.size_bytes
obligatorio
integer o null
data[].status
obligatorio
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.
data[].error
obligatorio
object o null
data[].error.code
obligatorio
stringPor qué falló (catálogo de errores del mensaje).
data[].error.message
obligatorio
string
data[].error.meta_code
obligatorio
integer o nullEl código de error de Meta, si viene de Meta.
data[].client_reference
obligatorio
string o nullLa referencia de tu sistema, tal como la enviaste.
data[].sent_by
obligatorio
uno de varios o nullQuié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.
data[].whatsapp_id
obligatorio
string o nullEl id de WhatsApp (wamid), cuando WhatsApp lo acepta.
data[].created_at
obligatorio
integerCuándo se creó el mensaje (o cuándo llegó).
data[].status_updated_at
obligatorio
integer o nullCuándo cambió su estado por última vez.
data[].expires_at
obligatorio
integer o nullMientras sigue en cola: hasta cuándo se intenta enviar (ttl).
data[].reply_to
obligatorio
string o nullEl whatsapp_id del mensaje al que responde, si responde a uno.
data[].interactive
obligatorio
object o nullEl botón o la opción que eligió el contacto.
data[].interactive.type
obligatorio
uno de: "button_reply", "list_reply", "button"Un botón o una opción de una lista, o el botón de una plantilla.
data[].interactive.id
obligatorio
string o nullEl id del botón o de la opción (el payload del botón de una plantilla).
data[].interactive.title
obligatorio
string o null
data[].location
obligatorio
object o nullLa ubicación que compartió el contacto.
data[].location.latitude
obligatorio
number o null
data[].location.longitude
obligatorio
number o null
data[].location.name
obligatorio
string o null
data[].location.address
obligatorio
string o null
data[].reaction
obligatorio
object o nullUna reacción a otro mensaje. Sin emoji, quitó su reacción.
data[].reaction.emoji
obligatorio
string o null
data[].reaction.message_whatsapp_id
obligatorio
string o nullEl whatsapp_id del mensaje al que reaccionó.
data[].referral
obligatorio
object o nullEl anuncio que trajo al contacto (clic a WhatsApp), si vino por uno.
data[].referral.source_type
obligatorio
string o null
data[].referral.source_id
obligatorio
string o null
data[].referral.source_url
obligatorio
string o null
data[].referral.headline
obligatorio
string o null
data[].referral.ctwa_clid
obligatorio
string o null
has_more
obligatorio
boolean
next_cursor
obligatorio
string o nullPara la página siguiente, con los mismos filtros; null al final.

Ejemplo: Por referencia

curl 'https://api.stack-netic.com/v1/messages?client_reference=lote-7&limit=20' \
  -H "Authorization: Bearer $STACKNETIC_API_KEY"
{
  "object": "list",
  "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, adjuntamos su comprobante 001-002-000123 por $ 45,20. Gracias por su compra.",
      "template": {
        "name": "comprobante",
        "language": "es"
      },
      "media": {
        "id": "med_02y9HHPWRS3wHysjF22iwI",
        "kind": "document",
        "content_type": "application/pdf",
        "filename": "RIDE-001-002-000123.pdf",
        "caption": null,
        "size_bytes": 48213
      },
      "status": "queued",
      "error": null,
      "client_reference": "lote-7",
      "sent_by": {
        "type": "api_key",
        "id": "key_02y9HfsYGgsLoqUuhdpNYk",
        "name": "Facturador producción"
      },
      "whatsapp_id": null,
      "created_at": 1790546400,
      "status_updated_at": 1790546400,
      "expires_at": 1790632800,
      "reply_to": null,
      "interactive": null,
      "location": null,
      "reaction": null,
      "referral": null
    }
  ],
  "has_more": true,
  "next_cursor": "v1.QmFzZTY0VXJsQ2lmcmFkbw"
}

Errores

Descargar el archivo de un mensaje#

GET/v1/messages/{id}/media
Permiso: messages:readPermiso: messages:send

La foto, el audio, el vídeo, el documento o el sticker de un mensaje, con sus bytes tal cual (Content-Type dice su formato y Content-Disposition, su nombre). Lo que llega se guarda al momento, y WhatsApp lo conserva solo 7 días: mientras se guarda responde 409 MEDIA_NOT_READY con Retry-After, y si ya no estaba, 410 MEDIA_UNAVAILABLE. Admite Range para bajarlo por partes (206). Ve los mismos mensajes que «Leer un mensaje».

Parámetros

CampoDóndeTipoDescripción
id
obligatorio
rutastringEl id del mensaje (msg_…).

Respuesta · 200 · el archivo

El archivo entero.

CampoDóndeTipoDescripción
Content-Type
obligatorio
cabecerastringEl formato del archivo (image/jpeg, application/pdf…).
Content-Length
obligatorio
cabeceraintegerLos bytes de esta respuesta.
Content-Disposition
obligatorio
cabecerastringattachment, con el nombre del archivo (el original, si lo trae).
Accept-Ranges
obligatorio
cabecerastringbytes: se puede pedir por partes con Range.
ETag
obligatorio
cabecerastringLa huella SHA-256 del archivo entero.

Ejemplo: La foto que mandó un contacto

curl 'https://api.stack-netic.com/v1/messages/msg_02y9HflgNTRjaQMubfP6vm/media' \
  -H "Authorization: Bearer $STACKNETIC_API_KEY" \
  --fail-with-body -o 'foto.jpg'
HTTP/1.1 200 OK
Content-Type: image/jpeg
Content-Length: 48213
Content-Disposition: attachment; filename="whatsapp-foto-2026-09-28.jpg"
ETag: "3f0a…"

(los bytes de la foto)

Errores

Marcar como leído#

POST/v1/messages/{id}/read
Permisos: messages:read y messages:sendRepetirla no cambia nada

Le dice a WhatsApp que el negocio leyó un mensaje que llegó: el contacto ve los dos ticks azules. Responde 202 en cuanto queda en cola y sale en segundos, en el turno de su número. Repetirlo no manda otro aviso. Pide los dos permisos, leer y enviar mensajes; uno enviado responde 422 MESSAGE_NOT_INBOUND.

Parámetros

CampoDóndeTipoDescripción
id
obligatorio
rutastringEl id del mensaje (msg_…).
Idempotency-KeycabecerastringUna 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.

Respuesta · 202

El aviso de leído, en cola.

CampoTipoDescripción
object
obligatorio
"read_receipt"
message
obligatorio
stringEl id del mensaje (msg_…).
status
obligatorio
"queued"En cola: sale en segundos, en el turno de su número.

Ejemplo: Marcar la respuesta de un contacto

curl -X POST 'https://api.stack-netic.com/v1/messages/msg_02y9HflgNTRjaQMubfP6vm/read' \
  -H "Authorization: Bearer $STACKNETIC_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"
{
  "object": "read_receipt",
  "message": "msg_02y9HflgNTRjaQMubfP6vm",
  "status": "queued"
}

Errores

Archivos#

Subir fotos y documentos para enviarlos.

Subir un archivo#

POST/v1/media
Permiso: messages:sendAdmite Idempotency-Key

Sube una foto (JPG o PNG, hasta 5 MB) o un documento (PDF, Word, Excel, PowerPoint o texto, hasta 16 MB) para enviarlo en un mensaje: suelto (purpose=message) o en el encabezado de una plantilla (purpose=header con kind). Se usa una sola vez y dura 24 horas. Solo lo puede usar la clave que lo subió.

Parámetros

CampoDóndeTipoDescripción
Idempotency-KeycabecerastringUna 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 · multipart/form-data

multipart/form-data con los campos y el archivo en la parte file.

CampoTipoDescripción
number
obligatorio
stringEl número desde el que se enviará.
purposeuno de: "message", "header"message: una foto o un documento suelto. header: el encabezado de una plantilla.
kinduno de: "image", "document"Con purpose=header: el tipo del encabezado.
file
obligatorio
stringEl archivo.

Respuesta · 201

El archivo, listo para enviarlo.

CampoTipoDescripción
object
obligatorio
"media"
id
obligatorio
stringEl id del archivo (med_…).
kind
obligatorio
uno de: "image", "document"
content_type
obligatorio
string
filename
obligatorio
stringEl nombre con que se enviará: saneado y con la extensión de su formato.
size_bytes
obligatorio
integer
renamed
obligatorio
booleanSi el nombre cambió al sanearlo.
expires_at
obligatorio
integerHasta cuándo se puede usar: 24 horas, y una sola vez.

Ejemplo: El PDF del encabezado de un comprobante

curl -X POST 'https://api.stack-netic.com/v1/media' \
  -H "Authorization: Bearer $STACKNETIC_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -F 'number=num_02y8w48sgGf2ztA7qbjqso' \
  -F 'purpose=header' \
  -F 'kind=document' \
  -F 'file=@RIDE-001-002-000123.pdf'
{
  "object": "media",
  "id": "med_02y9HHPWRS3wHysjF22iwI",
  "kind": "document",
  "content_type": "application/pdf",
  "filename": "RIDE-001-002-000123.pdf",
  "size_bytes": 48213,
  "renamed": false,
  "expires_at": 1790632800
}

Errores

Números#

Los números del espacio y si pueden enviar.

Listar los números#

GET/v1/numbers
Permiso: numbers:read

Los números que alcanza la clave, con su estado, su calidad, si pueden enviar y por qué no.

Respuesta · 200

Los números.

CampoTipoDescripción
object
obligatorio
"list"
data
obligatorio
array de object
data[].object
obligatorio
"number"
data[].id
obligatorio
stringEl id del número (num_…).
data[].phone
obligatorio
string o nullEl teléfono, en E.164.
data[].display_name
obligatorio
string o nullEl nombre verificado en WhatsApp.
data[].label
obligatorio
string o nullLa etiqueta que le puso el espacio.
data[].mode
obligatorio
uno de: "coexistence", "cloud_api"Cómo está conectado: junto a la app de WhatsApp Business o solo por la API.
data[].status
obligatorio
uno de: "active", "disconnected"
data[].quality
obligatorio
uno de: "green", "yellow", "red", "unknown"La calidad según Meta.
data[].messaging_limit
obligatorio
string o nullEl límite de mensajería de Meta (TIER_1K…). Meta lo está retirando: puede ser null.
data[].can_send
obligatorio
uno de: "available", "limited", "blocked", "unknown"Si WhatsApp deja enviar desde aquí.
data[].issues
obligatorio
array de objectLos problemas que informa Meta del número, con su solución en español.
data[].issues[].code
obligatorio
integer o null
data[].issues[].title
obligatorio
string
data[].issues[].solution
obligatorio
string
data[].whatsapp_account
obligatorio
object o nullSu cuenta de WhatsApp Business.
data[].whatsapp_account.id
obligatorio
stringEl id de la cuenta de WhatsApp Business (wa_…).
data[].whatsapp_account.name
obligatorio
string o null
data[].whatsapp_account.can_send
obligatorio
uno de: "available", "limited", "blocked", "unknown"Si WhatsApp deja enviar desde aquí.
data[].connected_at
obligatorio
integerCuándo se conectó.
has_more
obligatorio
boolean
next_cursor
obligatorio
string o nullPara la página siguiente, con los mismos filtros; null al final.

Ejemplo: Un número de una cuenta sin método de pago

curl 'https://api.stack-netic.com/v1/numbers' \
  -H "Authorization: Bearer $STACKNETIC_API_KEY"
{
  "object": "list",
  "data": [
    {
      "object": "number",
      "id": "num_02y8w48sgGf2ztA7qbjqso",
      "phone": "+593969847312",
      "display_name": "StackNetic",
      "label": "Ventas",
      "mode": "coexistence",
      "status": "active",
      "quality": "green",
      "messaging_limit": "TIER_1K",
      "can_send": "blocked",
      "issues": [
        {
          "code": 141006,
          "title": "Falta un método de pago en la cuenta de WhatsApp Business",
          "solution": "Meta no deja iniciar conversaciones hasta que se añada un método de pago válido en WhatsApp Manager → Configuración de pagos."
        }
      ],
      "whatsapp_account": {
        "id": "wa_02y8w2MyKl4wS3UC9VNwwo",
        "name": "StackNetic operations",
        "can_send": "blocked"
      },
      "connected_at": 1790200000
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Errores

Leer un número#

GET/v1/numbers/{id}
Permiso: numbers:read

Un número: su estado, si puede enviar y su cuenta de WhatsApp Business.

Parámetros

CampoDóndeTipoDescripción
id
obligatorio
rutastringEl id del número (num_…).

Respuesta · 200

El número.

CampoTipoDescripción
object
obligatorio
"number"
id
obligatorio
stringEl id del número (num_…).
phone
obligatorio
string o nullEl teléfono, en E.164.
display_name
obligatorio
string o nullEl nombre verificado en WhatsApp.
label
obligatorio
string o nullLa etiqueta que le puso el espacio.
mode
obligatorio
uno de: "coexistence", "cloud_api"Cómo está conectado: junto a la app de WhatsApp Business o solo por la API.
status
obligatorio
uno de: "active", "disconnected"
quality
obligatorio
uno de: "green", "yellow", "red", "unknown"La calidad según Meta.
messaging_limit
obligatorio
string o nullEl límite de mensajería de Meta (TIER_1K…). Meta lo está retirando: puede ser null.
can_send
obligatorio
uno de: "available", "limited", "blocked", "unknown"Si WhatsApp deja enviar desde aquí.
issues
obligatorio
array de objectLos problemas que informa Meta del número, con su solución en español.
issues[].code
obligatorio
integer o null
issues[].title
obligatorio
string
issues[].solution
obligatorio
string
whatsapp_account
obligatorio
object o nullSu cuenta de WhatsApp Business.
whatsapp_account.id
obligatorio
stringEl id de la cuenta de WhatsApp Business (wa_…).
whatsapp_account.name
obligatorio
string o null
whatsapp_account.can_send
obligatorio
uno de: "available", "limited", "blocked", "unknown"Si WhatsApp deja enviar desde aquí.
connected_at
obligatorio
integerCuándo se conectó.

Ejemplo: Bloqueado por el pago de la cuenta

curl 'https://api.stack-netic.com/v1/numbers/num_02y8w48sgGf2ztA7qbjqso' \
  -H "Authorization: Bearer $STACKNETIC_API_KEY"
{
  "object": "number",
  "id": "num_02y8w48sgGf2ztA7qbjqso",
  "phone": "+593969847312",
  "display_name": "StackNetic",
  "label": "Ventas",
  "mode": "coexistence",
  "status": "active",
  "quality": "green",
  "messaging_limit": "TIER_1K",
  "can_send": "blocked",
  "issues": [
    {
      "code": 141006,
      "title": "Falta un método de pago en la cuenta de WhatsApp Business",
      "solution": "Meta no deja iniciar conversaciones hasta que se añada un método de pago válido en WhatsApp Manager → Configuración de pagos."
    }
  ],
  "whatsapp_account": {
    "id": "wa_02y8w2MyKl4wS3UC9VNwwo",
    "name": "StackNetic operations",
    "can_send": "blocked"
  },
  "connected_at": 1790200000
}

Errores

Plantillas#

Las plantillas de la cuenta de WhatsApp Business y los datos que piden.

Listar las plantillas#

GET/v1/templates
Permiso: templates:read

Las plantillas de la cuenta de WhatsApp Business del número, con los datos que pide cada una (y su ruta en la petición) y si se puede enviar por la API.

Parámetros

CampoDóndeTipoDescripción
number
obligatorio
consultastringEl número: sus plantillas son las de su cuenta de WhatsApp Business.

Respuesta · 200

Las plantillas.

CampoTipoDescripción
object
obligatorio
"list"
data
obligatorio
array de object
data[].object
obligatorio
"template"
data[].name
obligatorio
string
data[].language
obligatorio
string
data[].category
obligatorio
stringUTILITY, MARKETING o AUTHENTICATION, como en Meta.
data[].status
obligatorio
stringAPPROVED, PENDING, REJECTED, PAUSED…, como en Meta.
data[].whatsapp_account
obligatorio
string o nullEl id de la cuenta de WhatsApp Business (wa_…).
data[].sendable
obligatorio
booleanSi se puede enviar por la API ahora.
data[].not_sendable_reason
obligatorio
object o null
data[].not_sendable_reason.code
obligatorio
string
data[].not_sendable_reason.message
obligatorio
string
data[].fields
obligatorio
array de objectLos datos que pide al enviarla, en orden.
data[].fields[].path
obligatorio
stringDónde va el dato en POST /v1/messages (template.params.body.nombre).
data[].fields[].type
obligatorio
uno de: "text", "url_suffix", "coupon", "payload", "media"
data[].fields[].media_kind
obligatorio
uno de: "image", "document" o null
data[].fields[].label
obligatorio
string
data[].fields[].required
obligatorio
boolean
data[].fields[].example
obligatorio
string o null
data[].fields[].max_length
obligatorio
integer o null
data[].preview
obligatorio
object
data[].preview.header
obligatorio
string o null
data[].preview.body
obligatorio
string o null
data[].preview.footer
obligatorio
string o null
data[].preview.buttons
obligatorio
array de string
has_more
obligatorio
boolean
next_cursor
obligatorio
string o nullPara la página siguiente, con los mismos filtros; null al final.

Ejemplo: Una plantilla con un PDF en el encabezado

curl 'https://api.stack-netic.com/v1/templates?number=num_02y8w48sgGf2ztA7qbjqso' \
  -H "Authorization: Bearer $STACKNETIC_API_KEY"
{
  "object": "list",
  "data": [
    {
      "object": "template",
      "name": "comprobante",
      "language": "es",
      "category": "UTILITY",
      "status": "APPROVED",
      "whatsapp_account": "wa_02y8w2MyKl4wS3UC9VNwwo",
      "sendable": true,
      "not_sendable_reason": null,
      "fields": [
        {
          "path": "template.params.header_media.media_id",
          "type": "media",
          "media_kind": "document",
          "label": "Documento del encabezado",
          "required": true,
          "example": null,
          "max_length": null
        },
        {
          "path": "template.params.body.numero",
          "type": "text",
          "media_kind": null,
          "label": "Numero",
          "required": true,
          "example": "001-002-000123",
          "max_length": 1024
        },
        {
          "path": "template.params.body.total",
          "type": "text",
          "media_kind": null,
          "label": "Total",
          "required": true,
          "example": "$ 45,20",
          "max_length": 1024
        }
      ],
      "preview": {
        "header": "[Documento]",
        "body": "Hola, adjuntamos su comprobante {{numero}} por {{total}}. Gracias por su compra.",
        "footer": null,
        "buttons": []
      }
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Errores

Crear una plantilla#

POST/v1/templates
Permiso: templates:writeCon plantillas en el planAdmite Idempotency-Key

Crea una plantilla en la cuenta de WhatsApp Business del número y la envía a revisión: queda PENDING hasta que WhatsApp la apruebe. En JSON, o en multipart/form-data con el borrador en la parte draft y la muestra del encabezado (imagen o documento) en sample.

Parámetros

CampoDóndeTipoDescripción
number
obligatorio
consultastringEl número: sus plantillas son las de su cuenta de WhatsApp Business.
Idempotency-KeycabecerastringUna 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

El borrador de una plantilla, como en la consola.

CampoTipoDescripción
name
obligatorio
stringMinúsculas, números y guiones bajos.
language
obligatorio
string
category
obligatorio
uno de: "UTILITY", "MARKETING"
headeruno de variosCon imagen o documento, la muestra va en la parte sample del multipart.
body
obligatorio
stringEl texto, con variables con nombre: {{nombre}}.
footerstring
examplesobject (clave → string)Un ejemplo por variable: Meta los pide para revisarla.
buttonsarray de uno de varios

Cuerpo · multipart/form-data

La parte draft lleva el borrador en JSON y sample, la muestra.

CampoTipoDescripción
draft
obligatorio
stringEl borrador, en JSON (como el cuerpo JSON del alta).
samplestringLa muestra del encabezado: una foto o un PDF.

Respuesta · 201

La plantilla, en revisión.

CampoTipoDescripción
object
obligatorio
"template"
name
obligatorio
string
language
obligatorio
string
category
obligatorio
stringUTILITY, MARKETING o AUTHENTICATION, como en Meta.
status
obligatorio
stringAPPROVED, PENDING, REJECTED, PAUSED…, como en Meta.
whatsapp_account
obligatorio
string o nullEl id de la cuenta de WhatsApp Business (wa_…).
sendable
obligatorio
booleanSi se puede enviar por la API ahora.
not_sendable_reason
obligatorio
object o null
not_sendable_reason.code
obligatorio
string
not_sendable_reason.message
obligatorio
string
fields
obligatorio
array de objectLos datos que pide al enviarla, en orden.
fields[].path
obligatorio
stringDónde va el dato en POST /v1/messages (template.params.body.nombre).
fields[].type
obligatorio
uno de: "text", "url_suffix", "coupon", "payload", "media"
fields[].media_kind
obligatorio
uno de: "image", "document" o null
fields[].label
obligatorio
string
fields[].required
obligatorio
boolean
fields[].example
obligatorio
string o null
fields[].max_length
obligatorio
integer o null
preview
obligatorio
object
preview.header
obligatorio
string o null
preview.body
obligatorio
string o null
preview.footer
obligatorio
string o null
preview.buttons
obligatorio
array de string

Ejemplo: Un recordatorio con variables

curl -X POST 'https://api.stack-netic.com/v1/templates?number=num_02y8w48sgGf2ztA7qbjqso' \
  -H "Authorization: Bearer $STACKNETIC_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  --data '{
  "name": "recordatorio_cita",
  "language": "es",
  "category": "UTILITY",
  "body": "Hola {{nombre}}, te esperamos el {{fecha}}.",
  "examples": {
    "nombre": "Ana",
    "fecha": "martes 12 de octubre"
  }
}'
{
  "object": "template",
  "name": "recordatorio_cita",
  "language": "es",
  "category": "UTILITY",
  "status": "PENDING",
  "whatsapp_account": "wa_02y8w2MyKl4wS3UC9VNwwo",
  "sendable": false,
  "not_sendable_reason": {
    "code": "not_approved",
    "message": "En revisión: WhatsApp todavía no la aprobó."
  },
  "fields": [
    {
      "path": "template.params.body.nombre",
      "type": "text",
      "media_kind": null,
      "label": "Nombre",
      "required": true,
      "example": "Ana",
      "max_length": 1024
    },
    {
      "path": "template.params.body.fecha",
      "type": "text",
      "media_kind": null,
      "label": "Fecha",
      "required": true,
      "example": "martes 12 de octubre",
      "max_length": 1024
    }
  ],
  "preview": {
    "header": null,
    "body": "Hola {{nombre}}, te esperamos el {{fecha}}.",
    "footer": null,
    "buttons": []
  }
}

Errores

Borrar una plantilla#

DELETE/v1/templates/{name}
Permiso: templates:writeCon plantillas en el planRepetirla no cambia nada

Borra de la cuenta de WhatsApp Business, en todos sus idiomas, una plantilla creada desde este espacio. Las demás se gestionan en WhatsApp Manager.

Parámetros

CampoDóndeTipoDescripción
name
obligatorio
rutastringEl nombre de la plantilla.
number
obligatorio
consultastringEl número: sus plantillas son las de su cuenta de WhatsApp Business.

Respuesta · 200

Borrada.

CampoTipoDescripción
object
obligatorio
"template"
name
obligatorio
string
deleted
obligatorio
true

Ejemplo: Borrar

curl -X DELETE 'https://api.stack-netic.com/v1/templates/recordatorio_cita?number=num_02y8w48sgGf2ztA7qbjqso' \
  -H "Authorization: Bearer $STACKNETIC_API_KEY"
{
  "object": "template",
  "name": "recordatorio_cita",
  "deleted": true
}

Errores

Webhooks#

Los endpoints que reciben, firmados y al momento, los avisos de lo que pasa en el espacio. Qué trae cada aviso está en la guía de webhooks.

Listar los endpoints#

GET/v1/webhook-endpoints
Permiso: webhooks:writeCon webhooks en el plan

Los endpoints que creó esta clave —o las que reemplazó al rotarla—, del más reciente al más antiguo, con su estado y su salud. Los creados en la consola no aparecen aquí.

Respuesta · 200

Los endpoints.

CampoTipoDescripción
object
obligatorio
"list"
data
obligatorio
array de object
data[].object
obligatorio
"webhook_endpoint"
data[].id
obligatorio
stringEl id del endpoint de webhooks (we_…).
data[].url
obligatorio
stringLa URL que recibe los avisos, normalizada (el dominio en minúsculas, sin el fragmento).
data[].description
obligatorio
string o null
data[].events
obligatorio
array de stringLos tipos que recibe, en el orden del catálogo: message.received, message.status, message.echo, call.ended, template.status, number.connected, number.disconnected, number.quality, number.status. Abierto: pueden aparecer tipos nuevos.
data[].numbers
obligatorio
"all" o array de string"all": todos los números del espacio, también los que se conecten después. Si no, los ids de los números.
data[].api_version
obligatorio
stringLa versión de los cuerpos que recibe (v1).
data[].status
obligatorio
uno de: "active", "paused", "disabled", "suspended"paused: lo pausó alguien (lo pendiente espera). disabled: 72 horas fallando o respondió 410 Gone. suspended: quien creó la clave ya no lo justifica. Los tres se reactivan en la consola.
data[].status_reason
obligatorio
string o nullPor qué no está activo: manual, failing, gone, author_removed, author_role_changed, author_scope_changed, author_disabled o platform.
data[].secret
obligatorio
string o nullEl secreto con que se firman los avisos (whsec_…), solo en la respuesta del alta: guárdalo entonces. Después, y al repetir el alta con la misma Idempotency-Key, null.
data[].secret_hint
obligatorio
stringLos últimos 4 caracteres del secreto, para reconocerlo.
data[].health
obligatorio
objectCómo le está yendo. El registro de cada entrega está en la consola.
data[].health.failing
obligatorio
booleanSi sus últimas entregas fallaron.
data[].health.consecutive_failures
obligatorio
integer
data[].health.failing_since
obligatorio
integer o nullDesde cuándo falla.
data[].health.last_attempt_at
obligatorio
integer o nullEl último intento de entrega.
data[].health.last_success_at
obligatorio
integer o nullLa última entrega con un 2xx.
data[].health.last_failure_at
obligatorio
integer o nullEl último fallo.
data[].health.last_failure_code
obligatorio
string o nullEl resultado del último fallo: http_503, timeout, tls_certificate…
data[].created_at
obligatorio
integerCuándo se creó.
data[].updated_at
obligatorio
integerSu último cambio.
has_more
obligatorio
boolean
next_cursor
obligatorio
string o nullPara la página siguiente, con los mismos filtros; null al final.

Ejemplo: Un endpoint

curl 'https://api.stack-netic.com/v1/webhook-endpoints' \
  -H "Authorization: Bearer $STACKNETIC_API_KEY"
{
  "object": "list",
  "data": [
    {
      "object": "webhook_endpoint",
      "id": "we_02y8w4hE8Lo89zo8KTrC1e",
      "url": "https://api.tuempresa.com/webhooks/stacknetic",
      "description": "Facturador: el estado de los comprobantes",
      "events": [
        "message.status",
        "number.status"
      ],
      "numbers": [
        "num_02y8w48sgGf2ztA7qbjqso"
      ],
      "api_version": "v1",
      "status": "active",
      "status_reason": null,
      "secret": null,
      "secret_hint": "LaSw",
      "health": {
        "failing": false,
        "consecutive_failures": 0,
        "failing_since": null,
        "last_attempt_at": 1790546412,
        "last_success_at": 1790546412,
        "last_failure_at": null,
        "last_failure_code": null
      },
      "created_at": 1790460000,
      "updated_at": 1790460000
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Errores

Crear un endpoint#

POST/v1/webhook-endpoints
Permiso: webhooks:writeCon webhooks en el planAdmite Idempotency-Key

Da de alta una URL de tu sistema para recibir, firmados y al momento, los eventos que elijas de los números que elijas. Se comprueban la URL y su DNS. La respuesta trae el secreto con que se firman (secret, whsec_…) solo esta vez: guárdalo para verificar la firma, como explica la guía de webhooks. Usa Idempotency-Key: un reintento no crea otro endpoint, y su respuesta trae secret: null.

Parámetros

CampoDóndeTipoDescripción
Idempotency-KeycabecerastringUna 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 endpoint nuevo: la URL, qué eventos y de qué números.

CampoTipoDescripción
url
obligatorio
stringLa URL de tu sistema: https://, un dominio público (no una IP) y el puerto 443 u 8443. Se comprueba su DNS.
descriptionstring o nullPara reconocerlo, hasta 200 caracteres.
events
obligatorio
array de stringLo que quieres recibir, al menos un tipo: message.received, message.status, message.echo, call.ended, template.status, number.connected, number.disconnected, number.quality, number.status. No hay comodín. Los que llevan datos de las conversaciones (message.* y call.ended) piden además el permiso messages:read.
numbers
obligatorio
"all" o array de stringDe qué números: "all" (todos, también los que se conecten después; pide una clave con todos los números) o una lista de ids.

Respuesta · 201

El endpoint, activo, con su secreto.

CampoTipoDescripción
object
obligatorio
"webhook_endpoint"
id
obligatorio
stringEl id del endpoint de webhooks (we_…).
url
obligatorio
stringLa URL que recibe los avisos, normalizada (el dominio en minúsculas, sin el fragmento).
description
obligatorio
string o null
events
obligatorio
array de stringLos tipos que recibe, en el orden del catálogo: message.received, message.status, message.echo, call.ended, template.status, number.connected, number.disconnected, number.quality, number.status. Abierto: pueden aparecer tipos nuevos.
numbers
obligatorio
"all" o array de string"all": todos los números del espacio, también los que se conecten después. Si no, los ids de los números.
api_version
obligatorio
stringLa versión de los cuerpos que recibe (v1).
status
obligatorio
uno de: "active", "paused", "disabled", "suspended"paused: lo pausó alguien (lo pendiente espera). disabled: 72 horas fallando o respondió 410 Gone. suspended: quien creó la clave ya no lo justifica. Los tres se reactivan en la consola.
status_reason
obligatorio
string o nullPor qué no está activo: manual, failing, gone, author_removed, author_role_changed, author_scope_changed, author_disabled o platform.
secret
obligatorio
string o nullEl secreto con que se firman los avisos (whsec_…), solo en la respuesta del alta: guárdalo entonces. Después, y al repetir el alta con la misma Idempotency-Key, null.
secret_hint
obligatorio
stringLos últimos 4 caracteres del secreto, para reconocerlo.
health
obligatorio
objectCómo le está yendo. El registro de cada entrega está en la consola.
health.failing
obligatorio
booleanSi sus últimas entregas fallaron.
health.consecutive_failures
obligatorio
integer
health.failing_since
obligatorio
integer o nullDesde cuándo falla.
health.last_attempt_at
obligatorio
integer o nullEl último intento de entrega.
health.last_success_at
obligatorio
integer o nullLa última entrega con un 2xx.
health.last_failure_at
obligatorio
integer o nullEl último fallo.
health.last_failure_code
obligatorio
string o nullEl resultado del último fallo: http_503, timeout, tls_certificate…
created_at
obligatorio
integerCuándo se creó.
updated_at
obligatorio
integerSu último cambio.

Ejemplo: Los estados de los mensajes y de un número

curl -X POST 'https://api.stack-netic.com/v1/webhook-endpoints' \
  -H "Authorization: Bearer $STACKNETIC_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  --data '{
  "url": "https://api.tuempresa.com/webhooks/stacknetic",
  "description": "Facturador: el estado de los comprobantes",
  "events": [
    "message.status",
    "number.status"
  ],
  "numbers": [
    "num_02y8w48sgGf2ztA7qbjqso"
  ]
}'
{
  "object": "webhook_endpoint",
  "id": "we_02y8w4hE8Lo89zo8KTrC1e",
  "url": "https://api.tuempresa.com/webhooks/stacknetic",
  "description": "Facturador: el estado de los comprobantes",
  "events": [
    "message.status",
    "number.status"
  ],
  "numbers": [
    "num_02y8w48sgGf2ztA7qbjqso"
  ],
  "api_version": "v1",
  "status": "active",
  "status_reason": null,
  "secret": "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw",
  "secret_hint": "LaSw",
  "health": {
    "failing": false,
    "consecutive_failures": 0,
    "failing_since": null,
    "last_attempt_at": null,
    "last_success_at": null,
    "last_failure_at": null,
    "last_failure_code": null
  },
  "created_at": 1790546400,
  "updated_at": 1790546400
}

Errores

Leer un endpoint#

GET/v1/webhook-endpoints/{id}
Permiso: webhooks:writeCon webhooks en el plan

Un endpoint que creó esta clave, con su estado y su salud. Uno de la consola o de otra clave no existe para ella (404).

Parámetros

CampoDóndeTipoDescripción
id
obligatorio
rutastringEl id del endpoint de webhooks (we_…).

Respuesta · 200

El endpoint.

CampoTipoDescripción
object
obligatorio
"webhook_endpoint"
id
obligatorio
stringEl id del endpoint de webhooks (we_…).
url
obligatorio
stringLa URL que recibe los avisos, normalizada (el dominio en minúsculas, sin el fragmento).
description
obligatorio
string o null
events
obligatorio
array de stringLos tipos que recibe, en el orden del catálogo: message.received, message.status, message.echo, call.ended, template.status, number.connected, number.disconnected, number.quality, number.status. Abierto: pueden aparecer tipos nuevos.
numbers
obligatorio
"all" o array de string"all": todos los números del espacio, también los que se conecten después. Si no, los ids de los números.
api_version
obligatorio
stringLa versión de los cuerpos que recibe (v1).
status
obligatorio
uno de: "active", "paused", "disabled", "suspended"paused: lo pausó alguien (lo pendiente espera). disabled: 72 horas fallando o respondió 410 Gone. suspended: quien creó la clave ya no lo justifica. Los tres se reactivan en la consola.
status_reason
obligatorio
string o nullPor qué no está activo: manual, failing, gone, author_removed, author_role_changed, author_scope_changed, author_disabled o platform.
secret
obligatorio
string o nullEl secreto con que se firman los avisos (whsec_…), solo en la respuesta del alta: guárdalo entonces. Después, y al repetir el alta con la misma Idempotency-Key, null.
secret_hint
obligatorio
stringLos últimos 4 caracteres del secreto, para reconocerlo.
health
obligatorio
objectCómo le está yendo. El registro de cada entrega está en la consola.
health.failing
obligatorio
booleanSi sus últimas entregas fallaron.
health.consecutive_failures
obligatorio
integer
health.failing_since
obligatorio
integer o nullDesde cuándo falla.
health.last_attempt_at
obligatorio
integer o nullEl último intento de entrega.
health.last_success_at
obligatorio
integer o nullLa última entrega con un 2xx.
health.last_failure_at
obligatorio
integer o nullEl último fallo.
health.last_failure_code
obligatorio
string o nullEl resultado del último fallo: http_503, timeout, tls_certificate…
created_at
obligatorio
integerCuándo se creó.
updated_at
obligatorio
integerSu último cambio.

Ejemplo: Activo y sano

curl 'https://api.stack-netic.com/v1/webhook-endpoints/we_02y8w4hE8Lo89zo8KTrC1e' \
  -H "Authorization: Bearer $STACKNETIC_API_KEY"
{
  "object": "webhook_endpoint",
  "id": "we_02y8w4hE8Lo89zo8KTrC1e",
  "url": "https://api.tuempresa.com/webhooks/stacknetic",
  "description": "Facturador: el estado de los comprobantes",
  "events": [
    "message.status",
    "number.status"
  ],
  "numbers": [
    "num_02y8w48sgGf2ztA7qbjqso"
  ],
  "api_version": "v1",
  "status": "active",
  "status_reason": null,
  "secret": null,
  "secret_hint": "LaSw",
  "health": {
    "failing": false,
    "consecutive_failures": 0,
    "failing_since": null,
    "last_attempt_at": 1790546412,
    "last_success_at": 1790546412,
    "last_failure_at": null,
    "last_failure_code": null
  },
  "created_at": 1790460000,
  "updated_at": 1790460000
}

Errores

Editar un endpoint#

PATCH/v1/webhook-endpoints/{id}
Permiso: webhooks:writeCon webhooks en el planRepetirla no cambia nada

Cambia la URL, la descripción, los eventos o los números; lo que no va se queda como estaba, y repetirla no cambia nada. Uno suspendido no se edita: hay que reactivarlo en la consola.

Parámetros

CampoDóndeTipoDescripción
id
obligatorio
rutastringEl id del endpoint de webhooks (we_…).

Cuerpo · application/json

Lo que cambia; lo que no va se queda como estaba. Una URL nueva se vuelve a comprobar.

CampoTipoDescripción
urlstringLa URL de tu sistema: https://, un dominio público (no una IP) y el puerto 443 u 8443. Se comprueba su DNS.
descriptionstring o nullPara reconocerlo, hasta 200 caracteres.
eventsarray de stringLo que quieres recibir, al menos un tipo: message.received, message.status, message.echo, call.ended, template.status, number.connected, number.disconnected, number.quality, number.status. No hay comodín. Los que llevan datos de las conversaciones (message.* y call.ended) piden además el permiso messages:read.
numbers"all" o array de stringDe qué números: "all" (todos, también los que se conecten después; pide una clave con todos los números) o una lista de ids.

Respuesta · 200

El endpoint, con el cambio.

CampoTipoDescripción
object
obligatorio
"webhook_endpoint"
id
obligatorio
stringEl id del endpoint de webhooks (we_…).
url
obligatorio
stringLa URL que recibe los avisos, normalizada (el dominio en minúsculas, sin el fragmento).
description
obligatorio
string o null
events
obligatorio
array de stringLos tipos que recibe, en el orden del catálogo: message.received, message.status, message.echo, call.ended, template.status, number.connected, number.disconnected, number.quality, number.status. Abierto: pueden aparecer tipos nuevos.
numbers
obligatorio
"all" o array de string"all": todos los números del espacio, también los que se conecten después. Si no, los ids de los números.
api_version
obligatorio
stringLa versión de los cuerpos que recibe (v1).
status
obligatorio
uno de: "active", "paused", "disabled", "suspended"paused: lo pausó alguien (lo pendiente espera). disabled: 72 horas fallando o respondió 410 Gone. suspended: quien creó la clave ya no lo justifica. Los tres se reactivan en la consola.
status_reason
obligatorio
string o nullPor qué no está activo: manual, failing, gone, author_removed, author_role_changed, author_scope_changed, author_disabled o platform.
secret
obligatorio
string o nullEl secreto con que se firman los avisos (whsec_…), solo en la respuesta del alta: guárdalo entonces. Después, y al repetir el alta con la misma Idempotency-Key, null.
secret_hint
obligatorio
stringLos últimos 4 caracteres del secreto, para reconocerlo.
health
obligatorio
objectCómo le está yendo. El registro de cada entrega está en la consola.
health.failing
obligatorio
booleanSi sus últimas entregas fallaron.
health.consecutive_failures
obligatorio
integer
health.failing_since
obligatorio
integer o nullDesde cuándo falla.
health.last_attempt_at
obligatorio
integer o nullEl último intento de entrega.
health.last_success_at
obligatorio
integer o nullLa última entrega con un 2xx.
health.last_failure_at
obligatorio
integer o nullEl último fallo.
health.last_failure_code
obligatorio
string o nullEl resultado del último fallo: http_503, timeout, tls_certificate…
created_at
obligatorio
integerCuándo se creó.
updated_at
obligatorio
integerSu último cambio.

Ejemplo: Recibir también los mensajes que llegan

curl -X PATCH 'https://api.stack-netic.com/v1/webhook-endpoints/we_02y8w4hE8Lo89zo8KTrC1e' \
  -H "Authorization: Bearer $STACKNETIC_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "events": [
    "message.received",
    "message.status",
    "number.status"
  ]
}'
{
  "object": "webhook_endpoint",
  "id": "we_02y8w4hE8Lo89zo8KTrC1e",
  "url": "https://api.tuempresa.com/webhooks/stacknetic",
  "description": "Facturador: el estado de los comprobantes",
  "events": [
    "message.received",
    "message.status",
    "number.status"
  ],
  "numbers": [
    "num_02y8w48sgGf2ztA7qbjqso"
  ],
  "api_version": "v1",
  "status": "active",
  "status_reason": null,
  "secret": null,
  "secret_hint": "LaSw",
  "health": {
    "failing": false,
    "consecutive_failures": 0,
    "failing_since": null,
    "last_attempt_at": 1790546412,
    "last_success_at": 1790546412,
    "last_failure_at": null,
    "last_failure_code": null
  },
  "created_at": 1790460000,
  "updated_at": 1790547000
}

Errores

Eliminar un endpoint#

DELETE/v1/webhook-endpoints/{id}
Permiso: webhooks:writeCon webhooks en el planRepetirla no cambia nada

Lo elimina y cancela lo que tenía pendiente: deja de recibir avisos al momento. No se puede deshacer.

Parámetros

CampoDóndeTipoDescripción
id
obligatorio
rutastringEl id del endpoint de webhooks (we_…).

Respuesta · 200

Eliminado.

CampoTipoDescripción
object
obligatorio
"webhook_endpoint"
id
obligatorio
stringEl id del endpoint de webhooks (we_…).
deleted
obligatorio
true

Ejemplo: Eliminar

curl -X DELETE 'https://api.stack-netic.com/v1/webhook-endpoints/we_02y8w4hE8Lo89zo8KTrC1e' \
  -H "Authorization: Bearer $STACKNETIC_API_KEY"
{
  "object": "webhook_endpoint",
  "id": "we_02y8w4hE8Lo89zo8KTrC1e",
  "deleted": true
}

Errores

Enviar una prueba#

POST/v1/webhook-endpoints/{id}/test
Permiso: webhooks:writeCon webhooks en el planAdmite Idempotency-Key

Manda al endpoint un aviso webhook.test, firmado como los demás y con un solo intento: sirve para probar tu receptor después de cada cambio. Responde 202 con el id del aviso, el webhook-id que recibirás; lo que respondió tu servidor se ve en la consola. Uno pausado o desactivado también se prueba; uno suspendido, no.

Parámetros

CampoDóndeTipoDescripción
id
obligatorio
rutastringEl id del endpoint de webhooks (we_…).
Idempotency-KeycabecerastringUna 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.

Respuesta · 202

La prueba, en cola.

CampoTipoDescripción
object
obligatorio
"webhook_test"
id
obligatorio
stringEl id del aviso de prueba: llega en su cabecera webhook-id.
endpoint
obligatorio
stringEl id del endpoint de webhooks (we_…).
type
obligatorio
"webhook.test"
created_at
obligatorio
integerCuándo se pidió.

Ejemplo: Probar el receptor

curl -X POST 'https://api.stack-netic.com/v1/webhook-endpoints/we_02y8w4hE8Lo89zo8KTrC1e/test' \
  -H "Authorization: Bearer $STACKNETIC_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"
{
  "object": "webhook_test",
  "id": "evt_02y9Hg6I37jaHgkutafuog",
  "endpoint": "we_02y8w4hE8Lo89zo8KTrC1e",
  "type": "webhook.test",
  "created_at": 1790550000
}

Errores

Clave#

La clave con que llamas: para comprobarla y ver lo que lleva enviado hoy.

Ver la clave#

GET/v1/key
Cualquier permiso

La clave con que llamas: su nombre, sus permisos, sus números, sus envíos de hoy frente a su tope y su espacio. Vale con cualquier permiso, así que sirve para comprobar que una clave funciona. Nunca devuelve el secreto.

Respuesta · 200

La clave.

CampoTipoDescripción
object
obligatorio
"api_key"
id
obligatorio
stringEl id de la clave (key_…).
name
obligatorio
string
scopes
obligatorio
array de uno de: "messages:send", "messages:read", "templates:read", "templates:write", "numbers:read", "webhooks:write"Sus permisos.
numbers
obligatorio
"all" o array de stringLos números que alcanza: "all" (todos, también los que se conecten después) o sus ids.
daily_sends
obligatorio
objectEl tope de envíos del día, por linaje: rotar la clave no da otro.
daily_sends.limit
obligatorio
integerSu tope de envíos del día.
daily_sends.used
obligatorio
integerLos de hoy: suyos y de las claves que reemplazó al rotarla.
daily_sends.remaining
obligatorio
integer
daily_sends.resets_at
obligatorio
integerLa próxima medianoche, hora de Ecuador, cuando vuelve a cero.
expires_at
obligatorio
integer o nullCuándo caduca; null: no caduca.
workspace
obligatorio
objectEl espacio de la clave.
workspace.id
obligatorio
stringEl id del espacio (ws_…).
workspace.name
obligatorio
string

Ejemplo: Una clave de envío

curl 'https://api.stack-netic.com/v1/key' \
  -H "Authorization: Bearer $STACKNETIC_API_KEY"
{
  "object": "api_key",
  "id": "key_02y9HfsYGgsLoqUuhdpNYk",
  "name": "Facturador producción",
  "scopes": [
    "messages:send",
    "templates:read",
    "numbers:read"
  ],
  "numbers": [
    "num_02y8w48sgGf2ztA7qbjqso"
  ],
  "daily_sends": {
    "limit": 1000,
    "used": 312,
    "remaining": 688,
    "resets_at": 1790571600
  },
  "expires_at": null,
  "workspace": {
    "id": "ws_02y8w1U16yvllaqHECQC2Y",
    "name": "Clínica Ejemplo"
  }
}

Errores

Errores#

Cada código de error, con su estado HTTP, cuándo sale y si conviene reintentar, está en el catálogo de errores. Allí también están los motivos por los que un mensaje ya aceptado puede fallar (error.code del mensaje).

Cambios#

  • 7 de octubre de 2026 · v1. Los endpoints de webhooks por la API (/v1/webhook-endpoints, con el permiso webhooks:write), GET /v1/key y, en el OpenAPI, la sección webhooks con el cuerpo de cada aviso. FEATURE_NOT_ENABLED dice qué falta en required_capability; crear y borrar plantillas piden, como en la consola, que el espacio incluya «Plantillas» (templates). Descargar el archivo de un mensaje (GET /v1/messages/{id}/media) y marcar como leído uno que llegó (POST /v1/messages/{id}/read), con sus códigos MEDIA_NOT_READY, MEDIA_UNAVAILABLE, RANGE_NOT_SATISFIABLE y MESSAGE_NOT_INBOUND.
  • 27 de septiembre de 2026 · v1. Primera versión: mensajes (texto, plantillas con datos, fotos y documentos), archivos, números y plantillas (listar, crear y borrar).