Runtime API: claves y envío

Crear, rotar y revocar

Abrí Mis conexiones → Claves y acceso. Creá una clave con messages:write para enviar o webhooks:verify para verificar. Se muestra completa una sola vez; guardala en el servidor. La base conserva sólo su hash.

Máximo cinco claves activas por conexión. Rotar revoca todas las anteriores inmediatamente y emite una nueva con los permisos elegidos. Las solicitudes ya autorizadas pueden terminar. La baja revoca las claves; una nueva autorización no las recupera.

Para archivos existen media:read (consultar y descargar) y media:write (subir y borrar). El panel ofrece esas opciones y claves combinadas con messages:write. Las claves existentes conservan sus permisos; creá una nueva si necesitás ampliar el acceso.

Dirección y cuerpo

POST https://whatsaut.com/api/runtime/v1/PHONE_NUMBER_ID/messages. Authorization: Bearer con una clave de esa conexión. Content-Type: application/json. No se admiten parámetros de URL, compresión, credenciales Meta ni campos ajenos al contrato.

El servidor selecciona la credencial y versión Graph configuradas. El cliente no puede cambiar app, WABA o destino. El cuerpo máximo es de 64 KiB.

curl --request POST "https://whatsaut.com/api/runtime/v1/$PHONE_NUMBER_ID/messages" \
  --header "Authorization: Bearer $WHATSAUT_KEY" \
  --header 'Content-Type: application/json' \
  --data @mensaje.json

Texto

El destinatario se expresa en dígitos con código de país, sin +. El cuerpo de texto admite hasta 4096 caracteres y preview_url booleano opcional. El ejemplo usa datos ficticios; reemplazalos sólo para un envío autorizado.

{
  "messaging_product": "whatsapp",
  "to": "5491100000000",
  "type": "text",
  "text": {
    "body": "Mensaje de ejemplo",
    "preview_url": false
  }
}

Plantilla

Indicá nombre e idioma de una plantilla aprobada. Las plantillas admiten sólo parámetros text del componente body: hasta 20. No admiten encabezados multimedia ni botones de plantilla. Los botones de respuesta se envían como type=interactive, según el ejemplo siguiente.

{
  "messaging_product": "whatsapp",
  "to": "5491100000000",
  "type": "template",
  "template": {
    "name": "confirmacion_turno",
    "language": {
      "code": "es"
    },
    "components": [
      {
        "type": "body",
        "parameters": [
          {
            "type": "text",
            "text": "Mart\u00edn"
          },
          {
            "type": "text",
            "text": "martes"
          }
        ]
      }
    ]
  }
}

Botones de respuesta

Enviá type=interactive e interactive.type=button, cuerpo de hasta 1024 caracteres y de uno a tres botones reply. Cada botón necesita ID único de hasta 256 caracteres y título único de hasta 20, sin Markdown. El ID no admite espacios en sus extremos.

Encabezado opcional sólo de texto y pie opcional: hasta 60 caracteres cada uno. Las respuestas del usuario llegan al webhook como interactive.button_reply. La API también admite listas, según el ejemplo siguiente. Todavía no admite catálogos, carruseles ni botones de URL. Para archivos consultá la guía Multimedia.

Usá estas respuestas dentro de una conversación habilitada por Meta. WhatsAut no calcula localmente la ventana de atención ni guarda el historial; Meta aplica sus restricciones y puede rechazar el envío.

{
  "messaging_product": "whatsapp",
  "to": "5491100000000",
  "type": "interactive",
  "interactive": {
    "type": "button",
    "body": {
      "text": "¿Cómo querés recibir tu pedido?"
    },
    "action": {
      "buttons": [
        {
          "type": "reply",
          "reply": {
            "id": "retiro",
            "title": "Retirar"
          }
        },
        {
          "type": "reply",
          "reply": {
            "id": "envio",
            "title": "Envío"
          }
        }
      ]
    }
  }
}

Listas de opciones

Usá type=interactive e interactive.type=list. El contrato de WhatsAut admite entre una y diez secciones, con un máximo de diez filas entre todas ellas. Cada sección necesita al menos una fila; los IDs deben ser únicos en toda la lista.

El botón que abre la lista admite hasta 20 caracteres. Cada fila admite ID de hasta 200, título de hasta 24 y descripción opcional de hasta 72. El título de sección admite hasta 24 y es obligatorio cuando hay más de una sección. No uses campos adicionales ni opciones vacías.

El cuerpo admite hasta 1024 caracteres en esta versión de WhatsAut. Encabezado sólo de texto y pie opcionales: hasta 60 cada uno. La lista utiliza el mismo permiso messages:write y comparte el límite de 60 intentos por minuto con las demás operaciones de mensajes.

La selección llega a tu webhook como interactive.list_reply, con el ID elegido. Verificá primero la firma del evento y deduplicá su ID de mensaje antes de ejecutar acciones. Un ID de fila identifica una opción, no prueba autorización para una compra ni reemplaza tu validación de negocio. Meta aplica las restricciones de la conversación; el envío no se reintenta automáticamente.

{
  "messaging_product": "whatsapp",
  "to": "5491100000000",
  "type": "interactive",
  "interactive": {
    "type": "list",
    "body": {
      "text": "Elegí una opción para continuar"
    },
    "action": {
      "button": "Ver opciones",
      "sections": [
        {
          "title": "Entrega",
          "rows": [
            {
              "id": "retiro",
              "title": "Retirar en el local",
              "description": "Te avisamos cuando esté listo"
            },
            {
              "id": "envio",
              "title": "Envío a domicilio"
            }
          ]
        }
      ]
    }
  }
}

Marcar un mensaje entrante como leído

Usá el mismo endpoint y una clave messages:write. Enviá messaging_product, status=read y message_id obtenido del webhook autenticado de esa conexión. No incluyas to ni type. La respuesta confirmada es {"success":true}.

Este contrato admite IDs que comiencen con wamid., seguidos de letras, dígitos o los caracteres _ + / = -, hasta 512 caracteres totales. Meta comprueba que el mensaje pueda marcarse como leído; WhatsAut no conserva un índice local de mensajes recibidos.

Marcar leído un mensaje entrante es distinto de comprobar si un cliente leyó uno enviado. Para esto último usá los estados del webhook. No se admiten otros estados ni indicadores de escritura.

{
  "messaging_product": "whatsapp",
  "status": "read",
  "message_id": "wamid.EJEMPLO_REEMPLAZAR"
}

Enviar archivos por ID

Se admiten image, audio, video y document con un ID de Meta. Primero subí el archivo según la guía Multimedia. Antes de cada envío comprobamos con Meta que el ID pertenece al número de la clave y que el formato/tamaño corresponde. No se aceptan enlaces ni credenciales externas.

Imagen/video admiten caption opcional de hasta 1024 caracteres. Documentos PDF admiten además filename opcional de hasta 240, sin barras ni saltos de línea. Audio sólo admite id. El envío requiere messages:write; subir requiere media:write y consultar/descargar requiere media:read.

Estas solicitudes comparten el presupuesto de mensajes de 60 intentos/minuto. Cada envío multimedia consulta primero metadata de Meta; un archivo eliminado, vencido, ajeno o no admitido impide el envío.

{
  "messaging_product": "whatsapp",
  "to": "5491100000000",
  "type": "image",
  "image": {
    "id": "900000000000001",
    "caption": "Imagen de ejemplo"
  }
}

Resultado, límites y errores

Para envíos, un 200 devuelve messaging_product y messages con el ID asignado; no confirma entrega. Para marcar leído devuelve success=true sólo si Meta lo confirmó. No se guardan destinatarios, contenido ni IDs de mensajes recibidos; los estados de entrega llegan al webhook.

Límite compartido por conexión: 60 intentos por minuto entre texto, plantillas, botones, listas y confirmaciones de lectura, aunque uses varias claves. Los intentos inválidos autenticados también consumen presupuesto. Un 429 incluye Retry-After: 60. Existe además un límite de admisión por proceso de 600 solicitudes/minuto por dirección de cliente.

Errores estables: invalid_key (401), scope_denied o asset_mismatch (403), invalid_request o invalid_payload (400), payload_too_large (413), connection_not_ready o credentials_unavailable (409), rate_limited (429), meta_rejected o upstream_response_invalid (502), send_outcome_unknown (502/504), configuration_error (503).

No hay reintentos automáticos. Ante timeout o resultado incierto, no repitas a ciegas: el primer envío podría haber sido aceptado. X-WhatsAut-Request-Id identifica la respuesta y su registro operativo. Desde los detalles de la conexión, abrí Operación, métricas y auditoría. El registro es acotado y no permite reenvíos ni garantiza entrega.

Pausas y errores operativos

Tres fallas transitorias de Meta desde la última operación exitosa pausan mensajes y archivos nuevos de esa conexión durante 30 segundos. Luego se admite una sola solicitud nueva para comprobar recuperación, con reserva de hasta 90 segundos si el proceso se interrumpe. No se reintentan las anteriores.

circuit_open (503, Retry-After: 30) significa que esta operación no contactó a Meta. operations_unavailable (503) significa que no se pudo registrar el inicio y tampoco se contactó al proveedor. operation_outcome_unknown (500) indica resultado incierto; no repitas automáticamente. Los rechazos de datos o permisos no abren el circuito ni prueban su recuperación.

La protección cubre mensajes y operaciones Graph de archivos, no plantillas del panel, onboarding ni verificación de firmas. Los errores de descarga del CDN no abren el circuito. Autenticación, límites y validaciones de transporte anteriores a la operación quedan fuera de esta auditoría. Consultá Supervisar una conexión para interpretar sus métricas.