WhatsApp Cloud API setup in Costa Rica: complete step-by-step guide 2026

WhatsApp Cloud API is the official Meta endpoint for sending automated messages to WhatsApp users. It is not the WhatsApp Business mobile app — it is an HTTP API your server calls via code. In Costa Rica, setup from scratch takes 3–7 business days, costs USD 0.0085 per template message, and replaces the illegal scrapers (WhatsApp Web automation, baileys, whatsapp-web.js) that end up with your number banned. This guide is what we apply at every Sirius client integrating WhatsApp: clinics, restaurants, ecommerce, fintech.

💡 TL;DR: Create Business Manager, verify business with cedula juridica, add a dedicated number, get UTILITY templates approved, ship a webhook on Next.js + Vercel. Cost: USD 0.0085/message in CR. Time: 3–7 days. Do not use scrapers — Meta bans numbers and violates the TOS.

Why Cloud API and not scrapers or WhatsApp Web

Before Cloud API, there were two popular ways to "automate WhatsApp": WhatsApp Web scraping with libraries like whatsapp-web.js or baileys, and gray services like early ChatAPI or Wati. Both are a bad idea today:

Scrapers work until they stop working: Meta detects automated patterns and bans the number. We have seen clients lose the WhatsApp number used for the entire operation because the previous agency built a cheap scraper — recovering it is nearly impossible. Cloud API is free to configure, official, and backed by Meta's SLA. The only cost is USD 0.0085 per UTILITY template message in Costa Rica.

Prerequisites before you start

Before touching Business Manager, have ready: (1) your company's cedula juridica (in Costa Rica you download the digital certification from the Registro Nacional in 5 minutes), (2) a dedicated phone number NOT registered on regular WhatsApp or the WhatsApp Business app — a separate Kolbi prepaid SIM (~USD 2) works, or a Twilio/Vonage VoIP if you need an international number, (3) a corporate email (not a personal Gmail) to create Business Manager, (4) admin access to an HTTPS domain for the webhook (Next.js + Vercel gives you HTTPS automatically with a custom domain). Without these 4, do not start.

📊 If you are integrating WhatsApp as part of a larger project, use the interactive quote tool — 4 questions in 30 seconds, USD range for the full scope.

Cloud API direct vs Twilio vs 360dialog: when to use which

There are three official ways to use WhatsApp Cloud API:

Pragmatic recommendation: start with Cloud API direct. If after 6 months you need more control, human support, or advanced features (scheduled sends from a panel, A/B testing), migrating to Twilio or 360dialog takes 2–3 days. Starting with a BSP when you do not need one is paying overhead for nothing.

Message structure: session vs template (the 24-hour window)

This is the most critical concept of WhatsApp Cloud API and where 70% of developers get it wrong:

Session message (Service Conversation): when a user messages you first, a 24-hour window opens during which you can reply with any type of message (free text, images, audio, documents) without it being a template. This is free inside the window — perfect for conversational bots or customer support.

Template message: when YOU initiate the conversation, or reply after the 24-hour window, you must use a template pre-approved by Meta. This is what you pay for (USD 0.0085 UTILITY in CR). Templates have variables and are categorized:

• UTILITY: reminders, confirmations, OTPs, status updates. USD 0.0085.
• MARKETING: promotions, offers, launches. USD 0.0114.
• AUTHENTICATION: exclusively 2FA codes. USD 0.0085.

If your app is 100% reactive (only replies when the user writes), you never use templates and everything is free. If your app sends scheduled notifications (appointments, alerts, reminders), you live in the template world.

Pre-approved templates: 3 real examples

These are real templates we have approved for clients. Copy them as a starting point and adjust to your case.

Template 1 — Booking confirmed (UTILITY)

Category: UTILITY · Language: Spanish (Costa Rica) or English Variables: {{1}} customer name, {{2}} service, {{3}} date and time, {{4}} location

Hi {{1}}, your booking for {{2}} is confirmed ✅

Date: {{3}}
Location: {{4}}

If you need to cancel or reschedule, just reply to this chat.

Approves in minutes. Works for clinics, restaurants, beauty salons, repair shops. Learn more in our guide on the WhatsApp appointment system for clinics in Costa Rica.

Template 2 — Time reminder (UTILITY)

Category: UTILITY · Variables: {{1}} name, {{2}} service, {{3}} time remaining, {{4}} location

{{1}}, reminder for your {{2}} in {{3}}. 📍 {{4}}. If anything comes up, message us here.

Variant with buttons: add [Confirm] [Reschedule] [Cancel] and your webhook receives the callback with the button pressed.

Template 3 — Verification code (AUTHENTICATION)

Category: AUTHENTICATION · Variables: {{1}} code

{{1}} is your verification code. Do not share it with anyone. Expires in 10 minutes.

The AUTHENTICATION category was created by Meta to replace SMS-OTP. Similar cost (USD 0.0085) but with 98% open rate vs 90% for SMS. Moving from SMS to WhatsApp drops the signup-flow bounce rate by 25–40%.

Webhook server setup with Next.js + Vercel

The webhook is the piece that receives events from Meta: incoming messages, send status (sent → delivered → read), button clicks. Without a webhook, your app is blind.

Endpoint structure

In Next.js 14+ with App Router, create app/api/whatsapp/webhook/route.ts with two 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 expects 200 OK in < 5s
  return NextResponse.json({ status: 'ok' })
}

Inside processWebhookEvent you parse body.entry[0].changes[0].value to extract messages (messages[0].type === 'text' | 'button') or statuses (statuses[0].status === 'delivered' | 'read' | 'failed') and route them to your business logic.

Sender function

Create lib/whatsapp.ts to send templates. The base call is a POST to https://graph.facebook.com/v20.0/{PHONE_NUMBER_ID}/messages with Authorization: Bearer {TOKEN} and a body with messaging_product: 'whatsapp', the recipient, type: 'template', and the template object with name, language (es_CR or en_US) and components with parameters. It returns a message_id you use to correlate the webhook event.

Vercel deployment

1. Push the code to a Git repo.
2. Connect the repo in Vercel.
3. In Vercel → Project → Settings → Environment Variables add WHATSAPP_TOKEN, WHATSAPP_PHONE_NUMBER_ID, WHATSAPP_VERIFY_TOKEN.
4. Set up a custom domain (automatic HTTPS).
5. In Meta Business Manager → WhatsApp → Configuration → Webhook → URL: https://yourdomain.com/api/whatsapp/webhook. Verify Token: the same value as your env. Subscribe to messages and message_status.

Done. Your server now receives events in production. If you combine this with a transactional email system like Resend for fallbacks, you have full notification coverage.

Real costs in Costa Rica: the full math

Real volume for an average business using WhatsApp for operations:

Compare against SMS (USD 0.04–0.08 per message in Costa Rica): the same volume on SMS costs 5–10x more, with half the open rate and no interactive buttons.

Typical recurring infrastructure: Vercel Pro USD 20 + Resend USD 0–20 + Supabase USD 25 + WhatsApp messages USD 3–85 by volume = USD 50–150/month.

If you have a specific vertical (clinics, restaurants, hotels), check our packages at /servicios/clinics and /servicios/restaurants — they include the full WhatsApp Cloud API setup.

Common errors and how to avoid them

These are the mistakes we see in every project. Read them twice.

1. Number blocked due to accelerated warm-up

By week 2 your quality rating drops to "Low" and Meta permanently throttles you to 250 conversations/day because you started sending 1,000 messages/day from day 1 to users without clear opt-in (block ratio >1%). Solution: start with 50–100 conversations/day during the first week, only to active customers who messaged YOU first. Ramp gradually: 250 → 500 → 1,000 → 5,000 over 4–6 weeks, holding "High" for 24 straight hours with real traffic so Meta opens the next tier.

2. Templates rejected for promotional language

UTILITY template rejected with the reason "Promotional content in UTILITY category" because you used words like "offer", "discount", "do not miss". UTILITY must be strictly transactional. Solution: if you need to promote, use the MARKETING category (USD 0.0114, requires explicit opt-in) and save UTILITY for reminders and confirmations. "Your appointment is tomorrow" → UTILITY. "Take 20% off" → MARKETING.

3. Webhook returns 500 and Meta stops sending events

You stop receiving messages after a deploy because your handler runs synchronous operations (DB queries, API calls) before responding to Meta, which expects 200 OK in under 5 seconds. Solution: respond 200 OK immediately and process the event in the background — use Vercel waitUntil or a queue (Upstash, Inngest, BullMQ). The pattern processWebhookEvent(body).catch(console.error); return NextResponse.json({ ok: true }) (no await) fixes it.

4. Template variables rejected for lack of context

Template rejected for "Insufficient context in variables" because you registered it as {{1}} {{2}} {{3}} with no text between variables. Solution: each variable needs textual context: "Hi {{1}}, your appointment for {{2}} is on {{3}}". Fill in the sample data fields with realistic values — Meta uses them to validate.

5. Migrating from a scraper to Cloud API with the same number

You want to move your current number to Cloud API and Meta says "Number already registered" because the scraper left active sessions or the number is tied to the WhatsApp Business app. Solution: close all sessions (Settings → Linked devices → Log out all), uninstall the app, and from Business Manager → Add phone number select "Migrate". Meta asks for an SMS code — takes 5–10 minutes.

Summary

WhatsApp Cloud API is the only serious way to integrate WhatsApp in production in Costa Rica. It is official, scalable, cheap (USD 0.0085 per message), and replaces the gray scrapers that end with your number banned.

The technical keys: Cloud API direct > BSP for 80% of cases in Costa Rica; dedicated number (not your regular WhatsApp one); UTILITY templates for transactional, MARKETING for promotions; webhook responds 200 OK in under 5 seconds; gradual tier warm-up over 4–6 weeks; HTTPS mandatory (Vercel gives it for free).

If you are coming from a scraper, migrate now — do not wait until Meta bans your number. If you are starting from scratch, follow the 7 HowTo steps above in order and you will be in production in 5–7 days. For the conversational side, see WhatsApp with AI: bot vs human. For full project pricing with WhatsApp included, read how much software costs in Costa Rica. For the glossary entry, see WhatsApp Cloud API.

💡 For an exact range on your WhatsApp Cloud API project, use the interactive quote tool — 4 questions in 30 seconds, USD range + listed scope.

📞 To talk directly: WhatsApp +506 8433 7752 or admin@siriusx.net. Monday to Friday 8am–5pm, Saturday 8am–12pm, Costa Rica time.

Related posts

• WhatsApp appointment system for clinics in Costa Rica — related cluster, healthcare vertical use case.
• How much software costs in Costa Rica — pillar pricing guide by project type.
• WhatsApp with AI: bot vs human — when to automate conversations and when not to.
• Services for clinics and restaurants — packages with WhatsApp Cloud API included.
• Interactive quote tool — USD range + scope for your project in 30 seconds.