Setup WhatsApp Cloud API en Costa Rica: guía completa paso a paso 2026

WhatsApp Cloud API es el endpoint oficial de Meta para enviar mensajes automáticos a usuarios de WhatsApp. No es la app móvil de WhatsApp Business — es una API HTTP que tu servidor llama por código. En Costa Rica, el setup desde cero toma 3–7 días hábiles, cuesta USD 0.0085 por mensaje plantilla y reemplaza a los scrapers ilegales (WhatsApp Web automation, baileys, whatsapp-web.js) que terminan con tu número bloqueado. Esta guía es lo que aplicamos en cada cliente que pasa por Sirius para integrar WhatsApp: clínicas, restaurantes, ecommerce, fintech.

💡 TL;DR: Crea Business Manager, verifica empresa con cédula jurídica, agrega número dedicado, aprueba plantillas UTILITY, monta webhook en Next.js + Vercel. Costo: USD 0.0085/mensaje en CR. Tiempo: 3–7 días. No uses scrapers — Meta bloquea números y viola los TOS.

Por qué Cloud API y no scrapers ni WhatsApp Web

Antes de Cloud API, había dos opciones populares para "automatizar WhatsApp": WhatsApp Web scraping con librerías como whatsapp-web.js o baileys, y servicios grises tipo ChatAPI o Wati en sus inicios. Ambas son hoy una mala idea:

Los scrapers funcionan hasta que dejan de funcionar: Meta detecta patrones automatizados y bloquea el número. Hemos visto clientes perder el número de toda la operación porque la agencia anterior montó un scraper barato — recuperarlo es casi imposible. Cloud API es gratis de configurar, oficial y con SLA de Meta. El único costo es USD 0.0085 por mensaje plantilla UTILITY en Costa Rica.

Prerequisitos antes de empezar

Antes de tocar el Business Manager, ten listos: (1) cédula jurídica de tu empresa vigente (descargas la certificación digital del Registro Nacional en 5 minutos), (2) un número de teléfono dedicado que NO esté en WhatsApp regular ni en la app de WhatsApp Business — sirve un Kolbi prepago aparte (~USD 2) o VoIP de Twilio/Vonage, (3) email corporativo (no Gmail personal) para crear Business Manager, (4) acceso a un dominio HTTPS para el webhook (Next.js + Vercel te da HTTPS automático con dominio custom). Sin estos 4, no arranques.

📊 Si vas a integrar WhatsApp como parte de un proyecto más grande, usa el cotizador interactivo — 4 preguntas, 30 segundos, rango USD para el alcance completo.

Cloud API directo vs Twilio vs 360dialog: cuándo cada uno

Hay tres formas oficiales de usar WhatsApp Cloud API:

Recomendación pragmática: arranca con Cloud API directo. Si en 6 meses necesitas más control, soporte humano o features avanzadas (envíos programados desde panel, A/B testing), migrar a Twilio o 360dialog toma 2–3 días. Empezar con BSP cuando no lo necesitas es pagar overhead por nada.

Estructura de mensajes: sesión vs plantilla (la ventana de 24 h)

Este es el concepto más crítico de WhatsApp Cloud API y donde el 70% de los desarrolladores se equivocan:

Mensaje de sesión (Service Conversation): cuando un usuario te escribe primero, se abre una ventana de 24 horas en la que puedes responderle con cualquier tipo de mensaje (texto libre, imágenes, audio, documentos) sin que sea plantilla. Esto es gratis dentro de la ventana — perfecto para bots conversacionales o atención al cliente.

Mensaje de plantilla (Template Message): cuando TÚ inicias la conversación o respondes después de las 24 horas, debes usar una plantilla pre-aprobada por Meta. Aquí es donde paga (USD 0.0085 UTILITY en CR). Las plantillas tienen variables y se categorizan:

• UTILITY: recordatorios, confirmaciones, OTPs, actualizaciones de estado. USD 0.0085.
• MARKETING: promociones, ofertas, lanzamientos. USD 0.0114.
• AUTHENTICATION: códigos 2FA exclusivamente. USD 0.0085.

Si tu app es 100% reactiva (solo responde cuando el usuario escribe), nunca usas plantillas y todo es gratis. Si tu app envía notificaciones programadas (citas, alertas, recordatorios), vives en mundo de plantillas.

Plantillas pre-aprobadas: 3 ejemplos reales

Estas son plantillas reales que aprobamos para clientes. Cópialas como punto de partida y ajusta a tu caso.

Plantilla 1 — Cita confirmada (UTILITY)

Categoría: UTILITY · Idioma: Spanish (Costa Rica) Variables: {{1}} nombre cliente, {{2}} servicio, {{3}} fecha y hora, {{4}} ubicación

Hola {{1}}, tu reserva para {{2}} está confirmada ✅

Fecha: {{3}}
Lugar: {{4}}

Si necesitas cancelar o reprogramar, escríbenos a este mismo chat.

Se aprueba en minutos. Funciona para clínicas, restaurantes, salones de belleza, talleres. Aprende más en nuestra guía de sistema de citas WhatsApp para clínicas en Costa Rica.

Plantilla 2 — Recordatorio temporal (UTILITY)

Categoría: UTILITY · Variables: {{1}} nombre, {{2}} servicio, {{3}} tiempo restante, {{4}} ubicación

{{1}}, te recordamos tu {{2}} en {{3}}. 📍 {{4}}. Cualquier imprevisto, escríbenos aquí.

Variante con botones: agrega [Confirmar] [Reprogramar] [Cancelar] y tu webhook recibe el callback con el botón presionado.

Plantilla 3 — Código de verificación (AUTHENTICATION)

Categoría: AUTHENTICATION · Variables: {{1}} código

{{1}} es tu código de verificación. No lo compartas con nadie. Expira en 10 minutos.

La categoría AUTHENTICATION fue creada por Meta para reemplazar SMS-OTP. Costo similar (USD 0.0085) pero con open rate 98% vs SMS 90%. Mudar de SMS a WhatsApp baja el bounce rate del flujo de signup en 25–40%.

Setup del webhook server con Next.js + Vercel

El webhook es la pieza que recibe eventos de Meta: mensajes entrantes, status de envío (sent → delivered → read), clicks de botones. Sin webhook, tu app es ciega.

Estructura del endpoint

En Next.js 14+ con App Router, crea app/api/whatsapp/webhook/route.ts con dos handlers:

import { NextRequest, NextResponse } from 'next/server'

const VERIFY_TOKEN = process.env.WHATSAPP_VERIFY_TOKEN!

export async function GET(req: NextRequest) {
  const params = req.nextUrl.searchParams
  if (params.get('hub.mode') === 'subscribe' && params.get('hub.verify_token') === VERIFY_TOKEN) {
    return new NextResponse(params.get('hub.challenge'), { status: 200 })
  }
  return new NextResponse('Forbidden', { status: 403 })
}

export async function POST(req: NextRequest) {
  const body = await req.json()
  processWebhookEvent(body).catch(console.error) // async — Meta espera 200 OK en < 5 s
  return NextResponse.json({ status: 'ok' })
}

Dentro de processWebhookEvent parseas body.entry[0].changes[0].value para extraer mensajes (messages[0].type === 'text' | 'button') o statuses (statuses[0].status === 'delivered' | 'read' | 'failed') y los enrutas a tu lógica de negocio.

Función sender

Crea lib/whatsapp.ts para enviar plantillas. La llamada base es un POST a https://graph.facebook.com/v20.0/{PHONE_NUMBER_ID}/messages con Authorization: Bearer {TOKEN} y un body con messaging_product: 'whatsapp', el destinatario, type: 'template', y el objeto template con nombre, idioma (es_CR) y componentes con parámetros. Devuelve un message_id que usas para correlacionar el evento del webhook.

Despliegue en Vercel

1. Push del código a un repo Git.
2. Conecta el repo en Vercel.
3. En Vercel → Project → Settings → Environment Variables agrega WHATSAPP_TOKEN, WHATSAPP_PHONE_NUMBER_ID, WHATSAPP_VERIFY_TOKEN.
4. Configura un dominio custom (HTTPS automático).
5. En Meta Business Manager → WhatsApp → Configuration → Webhook → URL: https://tudominio.com/api/whatsapp/webhook. Verify Token: el mismo valor que tu env. Suscríbete a messages y message_status.

Listo. Tu servidor ya recibe eventos en producción. Si combinas esto con un sistema de email transaccional como Resend para fallbacks, tienes cobertura completa de notificaciones.

Costos reales en Costa Rica: la matemática completa

Volumen real de un negocio promedio que usa WhatsApp para operación:

Compárelo contra SMS (USD 0.04–0.08 por mensaje en CR): la misma operación en SMS cuesta 5–10× más, con la mitad del open rate y sin botones interactivos.

Infraestructura recurrente típica: Vercel Pro USD 20 + Resend USD 0–20 + Supabase USD 25 + mensajes WhatsApp USD 3–85 según volumen = USD 50–150/mes.

Si tienes una vertical específica (clínicas, restaurantes, hoteles), revisa nuestros paquetes en /servicios/clinics y /servicios/restaurants — incluyen el setup completo de WhatsApp Cloud API.

Errores comunes y cómo evitarlos

Estos son los errores que vemos en cada proyecto. Léelos dos veces.

1. Número bloqueado por warm-up acelerado

A la semana 2 tu quality rating cae a "Low" y Meta limita a 250 conversaciones/día permanentemente porque empezaste enviando 1 000 mensajes/día desde el día 1 a usuarios sin opt-in claro (ratio de bloqueos >1%). Solución: arranca con 50–100 conversaciones/día la primera semana, solo a clientes activos que TE escribieron antes. Sube gradualmente: 250 → 500 → 1 000 → 5 000 en 4–6 semanas, manteniendo "High" 24 h seguidas con tráfico real para que Meta abra el siguiente tier.

2. Plantillas rechazadas por lenguaje promocional

Plantilla UTILITY rechazada con motivo "Promotional content in UTILITY category" porque usaste palabras como "oferta", "descuento", "no te lo pierdas". UTILITY debe ser estrictamente transaccional. Solución: si necesitas promocionar, usa categoría MARKETING (USD 0.0114, requiere opt-in explícito) y guarda UTILITY para recordatorios y confirmaciones. "Tu cita es mañana" → UTILITY. "Aprovecha 20% off" → MARKETING.

3. Webhook devuelve 500 y Meta deja de enviar eventos

Dejas de recibir mensajes después de un deploy porque tu handler hace operaciones síncronas (queries DB, API calls) antes de responder a Meta, que espera 200 OK en < 5 s. Solución: responde 200 OK inmediatamente y procesa el evento en background — usa waitUntil de Vercel o un queue (Upstash, Inngest, BullMQ). El patrón processWebhookEvent(body).catch(console.error); return NextResponse.json({ ok: true }) (sin await) lo arregla.

4. Variables de plantilla rechazadas por contexto

Plantilla rechazada por "Insufficient context in variables" porque la registraste como {{1}} {{2}} {{3}} sin texto entre variables. Solución: cada variable necesita contexto textual: "Hola {{1}}, tu cita para {{2}} es el {{3}}". Llena los ejemplos de sample data con valores realistas — Meta los usa para validar.

5. Migrar de scraper a Cloud API con el mismo número

Quieres pasar tu número actual a Cloud API y Meta dice "Number already registered" porque el scraper dejó sesiones activas o el número está atado a WhatsApp Business app. Solución: cierra todas las sesiones (Settings → Linked devices → Log out all), desinstala la app, y desde Business Manager → Add phone number selecciona "Migrate". Meta pide código SMS — toma 5–10 minutos.

En resumen

WhatsApp Cloud API es la única forma seria de integrar WhatsApp en producción en Costa Rica. Es oficial, escalable, barato (USD 0.0085 por mensaje), y reemplaza a los scrapers grises que terminan con tu número bloqueado.

Las claves técnicas: Cloud API directo > BSP para 80% de los casos en CR; número dedicado (no el de WhatsApp regular); plantillas UTILITY para transaccional, MARKETING para promociones; webhook responde 200 OK en < 5 segundos; warm-up gradual del tier en 4–6 semanas; HTTPS obligatorio (Vercel lo da gratis).

Si vienes de un scraper, migra ahora — no esperes a que Meta bloquee tu número. Si arrancas desde cero, sigue los 7 pasos del HowTo en orden y vas a producción en 5–7 días. Para más sobre el lado conversacional, revisa WhatsApp con IA: bot vs humano. Para pricing completo de proyecto con WhatsApp incluido, lee cuánto cuesta desarrollar software en Costa Rica. Y si necesitas el glossary, mira WhatsApp Cloud API.

💡 Para un rango exacto de tu proyecto con WhatsApp Cloud API, usa el cotizador interactivo — 4 preguntas en 30 segundos, rango USD + scope listado.

📞 Para hablar directo: WhatsApp +506 8433 7752 o admin@siriusx.net. Lunes a viernes 8 am–5 pm, sábados 8 am–12 md, hora CR.

Posts relacionados

• Sistema de citas con WhatsApp para clínicas en Costa Rica — cluster relacionado, caso de uso vertical salud.
• Cuánto cuesta desarrollar software en Costa Rica — guía pillar de pricing por tipo de proyecto.
• WhatsApp con IA: bot vs humano — cuándo automatizar conversaciones y cuándo no.
• Servicios para clínicas y restaurantes — paquetes con WhatsApp Cloud API incluido.
• Cotizador interactivo — rango USD + scope para tu proyecto en 30 segundos.