Enviar mensajes

1.La petición básica

Enviar un mensaje con la Cloud API es una sola petición HTTPS. Tu bot ya sabe qué responder (el motor devuelve una lista de respuestas); esta lección es la última pieza: cómo se convierten esas respuestas en peticiones a Meta.

Según la documentación oficial de envío de mensajes:

• El método y la ruta son POST /<PHONE_NUMBER_ID>/messages sobre graph.facebook.com, con la versión de la API en la ruta (por ejemplo v26.0).
• La cabecera Authorization: Bearer <token> lleva tu token.
• La cabecera Content-Type: application/json indica el formato.
• El cuerpo siempre incluye messaging_product: "whatsapp", el destinatario en to y el type del mensaje.

Lo que el código del curso aplica en src/whatsapp.js:

export const GRAPH_VERSION = 'v26.0';

export async function enviarMensaje(env, cuerpo, llamar = fetch) {
  const url = `https://graph.facebook.com/${GRAPH_VERSION}/${env.WA_PHONE_ID}/messages`;
  const respuesta = await llamar(url, {
    method: 'POST',
    headers: { Authorization: `Bearer ${env.WA_TOKEN}`, 'Content-Type': 'application/json' },
    body: JSON.stringify(cuerpo),
  });
  const datos = await respuesta.json().catch(() => ({}));
  if (!respuesta.ok) {
    // Nunca incluimos el token en el error.
    throw new Error(`WhatsApp respondió ${respuesta.status}: ${datos?.error?.message ?? 'sin detalle'}`);
  }
  return datos;
}

Tres decisiones merecen atención:

1. llamar = fetch: la función recibe como parámetro el fetch que usará. En producción es el real; en las pruebas es uno falso, así pruebas el envío sin tocar internet ni gastar mensajes (lo verás en la lección 23).
2. El mensaje de error nunca contiene el token. Un error registrado en la consola o en un panel de logs no debe filtrar una credencial.
3. Se lee el error.message de la respuesta de Meta, que suele explicar el problema.

2.Texto simple

El tipo más simple. El motor devuelve { tipo: 'texto', texto: '...' } y construirEnvio lo transforma:

import { construirEnvio } from './src/whatsapp.js';

const cuerpo = construirEnvio('51999000111', {
  tipo: 'texto',
  texto: 'Hola, bienvenido a Minimarket La Esquina.',
});
console.log(JSON.stringify(cuerpo));

{"messaging_product":"whatsapp","recipient_type":"individual","to":"51999000111","type":"text","text":{"preview_url":false,"body":"Hola, bienvenido a Minimarket La Esquina."}}

preview_url: false evita que WhatsApp genere una vista previa de enlaces. Si quieres que un enlace muestre su vista previa, tendrías que ponerlo en true (la documentación oficial usa true en su ejemplo cuando el texto incluye un enlace). Respecto al límite, el código impone 4096 caracteres de texto.

Una respuesta exitosa contiene el id del mensaje (wamid...) y el contacto:

{
  "messaging_product": "whatsapp",
  "contacts": [{ "input": "51999000111", "wa_id": "51999000111" }],
  "messages": [{ "id": "wamid.EJEMPLO123" }]
}

Guarda ese id si más adelante quieres relacionarlo con los estados sent, delivered o read que llegarán a tu webhook (lección 13).

3.Botones de respuesta

Los botones de respuesta (reply buttons) muestran hasta tres opciones tocables bajo el mensaje. Son ideales para decisiones cortas: «Recojo» o «Delivery», «Confirmar» o «Cancelar». Cuando el cliente toca uno, tu webhook recibe un mensaje interactive con el id del botón, no con su texto. Por eso el motor usa ids como entrega:recojo y pedido_confirmar: son identificadores estables, mientras el título es solo lo que se ve.

Reglas que valida construirEnvio antes de enviar (si se rompe una, lanza un error claro antes de llamar a Meta):

Estas validaciones producen mensajes como los siguientes (reales, ejecutados con el código del curso):

Respuesta inválida para WhatsApp: título de botón de más de 20 caracteres: "Un titulo demasiado largo para boton"
Respuesta inválida para WhatsApp: entre 1 y 3 botones

Y un envío válido de dos botones produce este cuerpo:

{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "51999000111",
  "type": "interactive",
  "interactive": {
    "type": "button",
    "body": { "text": "¿Cómo quieres recibir tu pedido?" },
    "action": {
      "buttons": [
        { "type": "reply", "reply": { "id": "entrega:recojo", "title": "Recojo en tienda" } },
        { "type": "reply", "reply": { "id": "entrega:delivery", "title": "Delivery" } }
      ]
    }
  }
}

4.Listas

Cuando tienes más de tres opciones, usa una lista: un mensaje con un botón que abre un menú con filas. Es lo que usa el bot para mostrar las categorías del catálogo. Límites del código:

Un ejemplo mínimo con el estilo del minimarket:

const cuerpo = construirEnvio('51999000111', {
  tipo: 'lista',
  texto: 'Elige una categoria',
  boton: 'Ver categorias',
  secciones: [{
    titulo: 'Categorias',
    filas: [{ id: 'cat:abarrotes', titulo: 'Abarrotes', descripcion: 'Arroz, azucar, aceite' }],
  }],
});

{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "51999000111",
  "type": "interactive",
  "interactive": {
    "type": "list",
    "body": { "text": "Elige una categoria" },
    "action": {
      "button": "Ver categorias",
      "sections": [{
        "title": "Categorias",
        "rows": [{ "id": "cat:abarrotes", "title": "Abarrotes", "description": "Arroz, azucar, aceite" }]
      }]
    }
  }
}

(El bloque de salida está reformateado en menos líneas para ahorrar espacio; el contenido es el mismo.)

Nota la diferencia de nombres entre el motor y la API: el motor usa botones, titulo, secciones y filas; la API usa buttons, title, sections y rows. construirEnvio es precisamente el traductor, y ese es el motivo por el que el motor no sabe nada de Meta: si Meta cambia un campo, solo tocas whatsapp.js.

5.Enviar varias respuestas en orden

Un turno del motor puede producir varias respuestas (por ejemplo, un texto y luego un menú). El Worker las envía una por una, esperando cada una, para que lleguen en el orden correcto:

await enviarMensaje(env, construirLeido(evento.id), llamar).catch((e) => console.error(e.message));
for (const respuesta of respuestas) {
  await enviarMensaje(env, construirEnvio(evento.de, respuesta), llamar);
}

Antes marca el mensaje del cliente como leído (los dos checks azules) con construirLeido; si eso falla, solo se registra y no se interrumpe la respuesta, porque es un detalle cosmético. Si lanzaras todas las peticiones a la vez con Promise.all, podrían llegar desordenadas.

6.Cuando algo falla: errores comunes

Cuando la API rechaza una petición, responde con un código HTTP y un JSON con un objeto error que incluye message y un code. La página oficial de códigos de error de WhatsApp lista cientos; estos son los que más verás al empezar:

El error de token lo viste en la lección 13. Esto fue lo que el código del curso registró con un token falso (real, ejecutado con el Worker):

WhatsApp respondió 401: Invalid OAuth access token - Cannot parse access token

Nota que muestra el estado HTTP y el mensaje, pero ni rastro del token.

Una regla práctica para decidir qué hacer con un error:

• No reintentes los errores de petición (100, 131051, 132000): el cuerpo está mal y fallará siempre.
• No reintentes 190 hasta renovar el token.
• Reintenta con espera los de límite de velocidad (130429, 131056).
• Cambia de estrategia con 131047: pasa de texto libre a plantilla.

7.Una respuesta 200 no significa «entregado»

Cuando enviarMensaje devuelve datos sin lanzar error, solo sabes que Meta aceptó tu petición. La documentación oficial lo dice así: la respuesta únicamente confirma que la API aceptó el pedido, y la entrega real se informa por webhook. Un mensaje aceptado puede fallar después (por ejemplo, el cliente cambió de número o no tiene conexión mucho tiempo). Por eso el Worker registra los eventos de estado failed con su lista de errores:

else if (evento.tipo === 'estado' && evento.estado === 'failed') console.error('Mensaje fallido', evento.id, evento.errores);

Más adelante, las lecciones de memoria y pruebas y errores usarán estos estados para reintentar o avisar al dueño.

8.Errores frecuentes

• Mandar más de tres botones. Pasa a una lista: el límite es de 3 botones de respuesta.
• Títulos demasiado largos. 20 caracteres en botones y 24 en filas de lista; acorta o mueve el detalle a la descripción.
• Usar el título del botón como identificador. El título cambia con el idioma o el diseño; decide siempre por el id.
• Enviar en paralelo varias respuestas. Pueden llegar desordenadas; envíalas en secuencia.
• Reintentar a ciegas. Un error de formato o de token se repetirá infinitamente; clasifica antes de reintentar.
• Dar por entregado un 200. Revisa los estados del webhook.
• Registrar el token en logs. Al construir mensajes de error, nunca incluyas cabeceras ni credenciales.

9.Apuntes para llevar

• Enviar es un POST a graph.facebook.com/<versión>/<PHONE_NUMBER_ID>/messages con Authorization: Bearer.
• construirEnvio traduce las respuestas del motor (texto, botones, lista) al cuerpo de la API y valida los límites antes de enviar.
• Máximo 3 botones de respuesta; para más opciones, una lista (hasta 10 filas).
• Decide por el id de botones y filas, no por su título.
• Envía las respuestas en orden, una por una.
• Clasifica los errores: algunos se corrigen, otros se reintentan y otros piden una plantilla.
• Un 200 solo significa que Meta aceptó el mensaje; la entrega la dicen los estados del webhook.

10.Glosario