Chuleta de WhatsApp Cloud API

Configurar el webhook

• GET con hub.mode=subscribe, hub.verify_token, hub.challenge: devuelve el challenge si el token coincide
• Las entregas POST llevan X-Hub-Signature-256 = sha256=HMAC(app secret, cuerpo en bruto)
• Suscribe la app al campo messages de la cuenta de WhatsApp Business
• Devuelve 200 rápido; las entregas fallidas se reintentan

Tipos de mensaje

• text (cuerpo hasta 4096 caracteres)
• image, video, audio, document, sticker por enlace o id de medio
• interactive: button (máx. 3), list (10 filas), cta_url, flow
• template aprobada en WhatsApp Manager
• location, contacts, reaction

Constructor de mensajes

La ventana de 24 horas

• Un mensaje del usuario abre una ventana de atención de 24 horas para respuestas libres
• Fuera de ella solo puedes enviar plantillas aprobadas
• Categorías de plantilla: marketing, utility, authentication; el precio varía por categoría y país
• Consigue el consentimiento antes de escribir primero

Payload entrante

entry[].changes[].value
  .messages[]   from, id, timestamp, type,
                text.body | interactive.button_reply
                | interactive.list_reply
  .statuses[]   id, status: sent | delivered
                | read | failed, errors[]
  .contacts[]   profile.name, wa_id

Llamadas útiles

• Marcar como leído: POST /messages con "status": "read" y "message_id"
• Subir medios: POST /<PHONE_NUMBER_ID>/media y luego envía por id
• Descargar medios: GET /<MEDIA_ID> devuelve una URL temporal que también requiere el token

Errores comunes

• 131047 re-engagement: fuera de la ventana de 24 horas, usa una plantilla
• 131026 mensaje no entregable
• 132001 la plantilla no existe en ese idioma
• 190 token caducado o no válido
• 130429 límite de throughput alcanzado