WhatsApp is the operating system for commerce in Brazil. Not a channel. The platform.

In the United States, the commerce stack is straightforward: Shopify storefront, Stripe checkout, email confirmation, FedEx tracking. The customer journey lives on the web. Discovery happens on Google or Instagram. Transactions happen on websites. Notifications go to email inboxes where they sit, unread, among hundreds of promotional messages.

In Brazil, this model does not work. It has never worked. And it will never work.

The commerce journey in Brazil starts and ends on WhatsApp. A customer sees a product on Instagram, taps the WhatsApp link in the bio, asks about availability, negotiates price (yes, price negotiation is standard practice), receives a Pix QR code, pays instantly, gets a confirmation message, receives a tracking code, and gets a delivery notification — all within the same WhatsApp conversation thread. No website visit required. No email address required. No app download required.

This is not an emerging trend. This is the established reality for over 6 million small and medium businesses in Brazil. According to a 2024 survey by Sebrae (the Brazilian small business agency), 72% of SMBs in Brazil use WhatsApp as their primary sales channel. Not a supplementary channel. Their primary channel.

The technology industry, particularly in Silicon Valley, has a persistent blind spot here. When American founders think about "conversational commerce," they think about chatbots on websites — little pop-up widgets in the bottom right corner that ask "How can I help you today?" and route to a FAQ. When Brazilian entrepreneurs think about conversational commerce, they think about the 400 WhatsApp messages they exchanged with customers yesterday. These are fundamentally different mental models, and the American one is wrong for this market.

The numbers behind WhatsApp dominance in LatAm

The scale of WhatsApp adoption in Latin America is difficult to overstate from a North American perspective. These are not vanity metrics. They are infrastructure-level adoption numbers that dictate where commerce happens.

Brazil: 120M daily active users

Brazil has approximately 215 million people. Of those, roughly 170 million are internet users. And of those internet users, 120 million use WhatsApp every single day. That is a 70% daily penetration rate across the entire population — and nearly 95% among smartphone users. No other app, platform, or service comes close. Instagram reaches about 113 million monthly users. TikTok reaches about 82 million. Email? The average Brazilian checks email 1.4 times per day. They check WhatsApp 23 times per day.

But the commerce-specific data is what matters for agent infrastructure. 80% of Brazilian consumers have communicated with a business via WhatsApp (Meta Business Messaging Survey, 2024). 66% have made a purchase that originated from a WhatsApp conversation (Opinion Box, 2024). 76% prefer to receive order updates via WhatsApp over email, SMS, or app notifications (Sebrae, 2024). The average response time to a business WhatsApp message is 90 seconds. The average response time to a business email is 6.4 hours. That is a 256x speed difference in customer engagement.

Mexico: 95M users, 78M daily

Mexico mirrors Brazil's pattern with its own cultural dynamics. With 95 million WhatsApp users and approximately 78 million daily actives, WhatsApp is the default communication layer for Mexican commerce. The AMVO (Mexican Association of Online Sales) reported in 2024 that 63% of Mexican e-commerce transactions involve at least one WhatsApp touchpoint — typically pre-sale questions, payment coordination, or post-sale support. The "tiendita" economy (small neighborhood stores, which account for approximately 23% of Mexico's GDP according to INEGI) runs almost entirely on WhatsApp: orders placed via message, confirmations sent via message, delivery coordinated via voice note.

Argentina, Colombia, and the rest

Argentina (38M users), Colombia (35M users), Peru (24M users), Chile (16M users). The pattern is uniform across the continent. WhatsApp is not merely popular. It is infrastructural. Government services in Argentina send vaccine appointment confirmations via WhatsApp. Colombian banks send transaction alerts via WhatsApp. Chilean airlines send boarding passes via WhatsApp. When the infrastructure for daily life runs on a platform, commerce follows inevitably.

Compare these engagement numbers to alternatives:

Channel          Open Rate    Response Rate    Avg Response Time
─────────────────────────────────────────────────────────────────
WhatsApp         90-95%       45-60%           < 3 minutes
SMS              85-90%       12-18%           < 15 minutes
Email            18-22%       2-5%             4-8 hours
Push Notif.      5-15%        1-3%             varies widely
In-App           3-8%         <1%              varies widely

The gap between WhatsApp and email is not incremental. It is categorical. An agent that sends order confirmations via email in Brazil is an agent whose messages will be read by fewer than one in five customers. The same message on WhatsApp will be read by nine out of ten — usually within three minutes. This is not a preference to accommodate. It is a market reality to build for.

WhatsApp Business API economics: what it actually costs

One of the most misunderstood aspects of WhatsApp commerce is the pricing model. Unlike SMS (per-message) or email (essentially free at scale), WhatsApp Business API uses conversation-based pricing with four distinct tiers. Understanding these tiers is essential for any commerce agent because they directly impact unit economics and determine whether WhatsApp-based agent commerce is viable at scale.

The four conversation categories

Meta introduced conversation-based pricing in 2022 and has refined it several times since. As of early 2026, the categories are:

Category        Who Initiates    Use Case
─────────────────────────────────────────────────────────────
Marketing       Business         Promotions, offers, re-engagement
Utility         Business         Order updates, shipping, receipts
Authentication  Business         OTP, login verification
Service         Customer         Customer-initiated support

* Service conversations are free for the first 1,000/month per WABA.
  Each conversation = 24-hour window from the first message.

Key insight: a single conversation is a 24-hour window, not a single message. Once a conversation is opened (either by the business sending a template or the customer messaging first), all messages within that 24-hour window are included. This means an agent that handles an entire order flow — product question, Pix link, payment confirmation, shipping update — within 24 hours pays for one conversation, not four separate messages. For fast-fulfillment commerce (which Pix enables, since payment settles in under 10 seconds), the entire transaction lifecycle fits inside a single conversation window.

Template messages vs. session messages

This distinction is critical and trips up every developer building on WhatsApp for the first time. Getting it wrong means either failed message delivery or unnecessary costs.

Template messages are pre-approved message formats submitted to Meta for review. They are the only way a business can initiate a conversation with a customer outside an active session window. Templates support variables (customer name, order number, tracking code) but the structure and wording must be approved first. Approval typically takes 24-48 hours but can take up to a week for new WhatsApp Business Accounts. Template messages open a new conversation window and incur the category-based charge.

Session messages are free-form messages sent within an open 24-hour conversation window. Once a customer messages first (opening a Service conversation) or a template opens a Business-initiated conversation, the agent can send any content — text, images, documents, buttons, lists — without needing pre-approved templates. This is where agents shine: within an active session, the agent has full expressive freedom.

// Template message - initiates conversation, must be pre-approved
// Opens a 24h window.
await whatsapp.sendTemplate({
  to: "+5511999999999",
  template: "order_shipped",      // pre-approved by Meta
  language: "pt_BR",
  components: [{
    type: "body",
    parameters: [
      { type: "text", text: "João" },
      { type: "text", text: "BR123456789" },
      { type: "text", text: "Correios PAC" },
    ],
  }],
});

// Session message - free-form within 24h window, no approval needed
// No additional cost if within the same conversation window.
await whatsapp.sendText({
  to: "+5511999999999",
  text: "Seu pedido acabou de sair para entrega!",
});

Cost comparison with SMS and email

WhatsApp costs more per message than email. But the 90% read rate versus 20% read rate means the effective cost per customer actually reached can be lower, especially when the message contains a payment link or delivery confirmation that requires customer action. The metric that matters is not cost per message sent. It is cost per customer action taken.

import { CodeSpar } from "@codespar/sdk";const session = await new CodeSpar().create("user_0000", { preset: "brazilian" });const run = await session.send("create a Pix charge of R$ 289.90 for order 2207 and send it to the customer on WhatsApp");const charge = run.tool_calls.find((c) => c.tool_name === "codespar_charge");const { payment_status } = await session.paymentStatus(charge!.id); // pending until the customer pays

Z-API vs. Evolution API vs. WhatsApp Cloud API: honest tradeoffs

There are three realistic options for connecting an agent to WhatsApp in production. Each has genuine strengths and genuine problems. Most comparisons you will find online are written by vendors selling one of these solutions. This one is not.

WhatsApp Cloud API (Official, Meta-hosted)

The official API, hosted by Meta. Free to use beyond conversation costs. This is what Meta wants you to use, and for good reasons — and some less good ones.

STRENGTHS
  - Official. Zero risk of Meta enforcement or account bans.
  - Free tier: 1,000 service conversations/month.
  - Template message support with full approval workflow.
  - Webhook delivery is reliable.
  - Scales to millions of messages without infra concerns.
  - Interactive messages: buttons, lists, flows, product catalogs.
  - Green checkmark verification available for brand trust.
  - Rate limit tiers scale with spending (up to 1,000 msgs/sec).

WEAKNESSES
  - Rate limits: 80 messages/second for standard tier.
    Tier upgrades require cumulative spending thresholds.
    New accounts start at Tier 1 (1K business-initiated/day).
  - Phone number is locked to Cloud API exclusively.
    Cannot use WhatsApp on the same number simultaneously.
    This surprises small business owners who use their
    personal WhatsApp for sales.
  - Template approval is manual, opaque, and inconsistent.
    Rejections cite generic reasons ("INVALID_FORMAT")
    with no guidance on what specifically to change.
  - Meta Business Verification can take 1-4 weeks.
    Requires legal documents, website verification, etc.
    Blocks launch timeline for new businesses.
  - No group message support via API.
  - Media upload requires pre-registration or URL hosting.
    URLs must be publicly accessible (no auth headers).
  - Brazil-specific: phone number porting takes 2-7 days.
  - Webhook payload format changes without versioned migration.

Z-API (Cloud-hosted, Brazilian provider)

Z-API is a Brazilian company that provides a cloud-hosted WhatsApp API wrapper. They handle the infrastructure and provide a REST API that abstracts WhatsApp Web complexity. Popular with Brazilian startups for its fast setup.

STRENGTHS
  - Cloud-hosted. Zero infrastructure to manage.
  - Brazilian company, BRL billing, Portuguese support docs.
  - QR code pairing: connect any WhatsApp number in minutes.
    No Meta Business Verification. No waiting period.
  - Works with personal AND business WhatsApp numbers.
  - Group operations: create, add/remove members, send messages.
  - Webhook relay with built-in retry logic.
  - 20+ API endpoints covering most WhatsApp operations.
  - Monthly plans; current prices on z-api.io.

WEAKNESSES
  - Send rate is limited per instance; Z-API's docs publish
    no number. Under high load (flash sales, broadcast
    campaigns), this becomes a blocking bottleneck.
  - Uses WhatsApp Web protocol under the hood (Baileys-based).
    Subject to Meta's detection heuristics.
    Account bans are rare (~0.5% of accounts per year based on
    community reports) but when they happen, recovery is
    difficult and sometimes impossible.
  - No official template message support.
    You can send any message, but it's not going through
    Meta's template system. For businesses that need
    template compliance, this is a non-starter.
  - Vendor dependency: if Z-API infrastructure goes down,
    your agent goes silent. No fallback path.
  - Session persistence: QR code re-pairing required after
    certain WhatsApp updates or prolonged disconnection.
    Requires manual intervention (scanning QR from the
    phone).
  - Pricing scales linearly: need higher throughput? Buy
    another instance.

Evolution API (Self-hosted, open source)

Evolution API is an open-source project built on the Baileys library (a TypeScript reverse-engineering of the WhatsApp Web client). You host it yourself — typically on a VPS, bare metal server, or container orchestrator.

STRENGTHS
  - Open source (Apache 2.0). Full code access. No vendor lock.
  - Self-hosted: complete control over data, uptime, scaling.
  - No per-message or per-conversation fees beyond hosting costs.
  - Active community: 14K+ GitHub stars, regular releases.
  - Integrates natively with Chatwoot, Typebot, N8N, Dify.
  - WebSocket + webhook support for real-time events.
  - Multi-instance: run dozens of WhatsApp numbers on one server.
  - Docker-ready with docker-compose for quick deployment.

WEAKNESSES
  - Self-hosting means self-ops. YOU own the uptime.
    Expect 4-8 hours/month on maintenance, updates,
    monitoring, and incident response.
  - Uses Baileys (WhatsApp Web reverse-engineering).
    Same TOS risk as Z-API. Not sanctioned by Meta.
    Detection risk increases with message volume.
  - Memory consumption: each instance uses 200-400MB RAM.
    10 instances = 2-4GB RAM minimum. On a $10/month
    DigitalOcean droplet, you get 3-4 instances max.
  - Baileys breakage: when Meta updates the WhatsApp Web
    protocol (every 2-4 weeks), Baileys can break.
    Community fixes typically land in 24-72 hours.
    YOUR AGENT IS OFFLINE DURING THIS WINDOW.
  - No official template message support. Same limitation as Z-API.
  - Rate limits are self-imposed but Meta's server-side
    detection flags unusual patterns. Keep volume low
    to avoid detection.
    There is no official documentation of these thresholds
    because the behavior is undocumented and changes.
  - Requires Redis + PostgreSQL/MongoDB for production.
    Minimum viable infra: ~$20-40/month (cloud VPS).
  - No SLA, no support contract. Community GitHub issues only.
    Critical bugs may or may not get fixed quickly depending
    on maintainer availability.

Our recommendation by use case

Use Case                            Recommendation
─────────────────────────────────────────────────────────────────
Production SaaS, high volume        WhatsApp Cloud API
  Compliance matters. Template approval matters.
  Scale to millions. Accept the setup friction.

Brazilian SMB, <5K msgs/month       Z-API
  Fast setup. No infra. Monthly plans.
  Accept the per-instance send limit and occasional re-pairing.

Developer/startup, full control     Evolution API
  Cost-efficient at scale. Fully customizable.
  Accept the ops burden and Baileys breakage risk.

Agent commerce (CodeSpar)           Cloud API + Z-API fallback
  Cloud API as primary (compliance, templates, scale).
  Z-API for features Cloud API lacks (groups, QR pairing).
  Evolution API for self-hosted enterprise deployments.

The conversation-to-payment flow: how it actually works

The most powerful pattern in Brazilian commerce is the conversation-to-payment flow. A customer messages a business on WhatsApp, an agent responds with product information and a Pix QR code, the customer pays in their banking app, and, in the flow the integrator composes below, the agent sends the NF-e and the tracking code back in the same thread. No redirect to a website. No app switch. No friction.

Here is how this works end-to-end with the @codespar/sdk 0.16.11 (Node.js 20+, a test key csk_test_… while you build):

import { CodeSpar } from "@codespar/sdk";

const cs = new CodeSpar({ apiKey: process.env.CODESPAR_API_KEY });
const session = await cs.create("store_0001", { preset: "brazilian" });

// 1. Customer messages: "Quero comprar o tênis preto tamanho 42"
//    Your WhatsApp provider's webhook delivers it to this handler.
export async function onWhatsAppMessage(from: string, text: string) {
  // 2-4. The agent checks the product, creates the Pix charge and sends the
  //      Pix copia e cola back on WhatsApp as text
  //      (codespar_charge, then codespar_notify).
  const run = await session.send(
    `Customer ${from} wrote on WhatsApp: "${text}". If the product is in stock, ` +
      `create a Pix charge for it and send ${from} the Pix copia e cola ` +
      `on WhatsApp. If it is out of stock, tell them so on WhatsApp.`,
  );
  return run.tool_calls.find((c) => c.tool_name === "codespar_charge");
}

// 5. Payment confirmation: CodeSpar posts commerce.payment.succeeded to your endpoint
await cs.api.post("/v1/triggers", {
  body: {
    name: "pix-paid",
    event: "commerce.payment.succeeded",
    webhook_url: "https://yourapp.com/hooks/pix-paid",
  },
});

// 6-8. On that webhook: issue the NF-e, create the shipping label,
//      and send both to the customer on WhatsApp
//      (codespar_invoice, codespar_ship, codespar_notify).
export async function onPixPaid(customerPhone: string, order: string) {
  await session.send(
    `Order ${order} was paid by Pix. Issue the NF-e, generate the shipping label, ` +
      `and send ${customerPhone} the NF-e and the tracking code on WhatsApp.`,
  );
}

As the integrator composes it here, the flow keeps product discovery, the Pix payment, the NF-e and the shipping label inside one WhatsApp conversation. The return messages come from your code: the onPixPaid handler asks the agent to send the NF-e and the tracking code. The customer never leaves the app.

Why Pix is the critical enabler

Pix, Brazil's instant payment system launched by the Banco Central do Brasil in November 2020, is what makes this loop possible. Before Pix, WhatsApp commerce required boleto bancário (a bank slip that takes 1-3 business days to clear, with a 30-40% abandonment rate) or credit card links that redirect to external checkout pages (breaking the WhatsApp-native experience). Pix changed everything by enabling instant settlement, 24/7/365, with zero fees for individuals and minimal fees for businesses (typically 0.5-1.0% for merchant Pix).

As of early 2026, Pix processes over 4.5 billion transactions per month in Brazil. 75% of Brazilian adults have used Pix. The combination of WhatsApp (instant messaging) + Pix (instant payment) + NF-e (instant invoicing) makes a commerce loop possible, from "I want to buy this" to the NF-e, in one conversation, when the integrator composes it.

Failure modes: what breaks and when

Most content about WhatsApp commerce reads like a sales brochure. Here is what actually goes wrong in production.

Rate limiting under high load

This is the most common production failure and the one least discussed in vendor documentation. During a flash sale, a broadcast campaign, or even a viral Instagram post that drives WhatsApp inquiries, message volume spikes by 10-50x normal levels. Each API has different breaking points and different failure behaviors:

WhatsApp Cloud API
  Standard tier: 80 msgs/sec (4,800/min)
  When exceeded: HTTP 429, messages queued server-side
  Recovery: automatic after 1-2 seconds cooldown
  Risk: message ordering is NOT guaranteed under load.
        A customer may receive "payment confirmed" before
        "here is your Pix QR code." This causes confusion.
  Tier scaling: requires cumulative spending thresholds.
        Tier 1: 1K business-initiated conversations/24h
        Tier 2: 10K/24h   Tier 3: 100K/24h   Tier 4: unlimited
        You cannot buy your way to Tier 4 on day one.

Z-API
  Limit: per instance; Z-API's docs publish no number.
  When exceeded: HTTP 429, no server-side queue.
  Recovery: must implement client-side retry with backoff.
  Risk: messages are DROPPED, not queued. Data loss is real.
        If your code doesn't handle 429s, customers don't
        get their payment confirmations.
  Workaround: multiple instances, each paired with its
        own phone number.

Evolution API (Baileys)
  Soft limit: not documented
  When exceeded: WhatsApp server may throttle or flag session.
  Recovery: may require QR re-pairing (manual intervention).
  Risk: sustained high volume triggers Meta's detection
        heuristics. The session gets terminated, and your
        agent goes offline until someone physically scans
        a QR code from the connected phone. At 3 AM.

How we would handle this: a priority queue with exponential backoff. The @codespar/sdk does not ship one; the sketch below shows its shape. Payment confirmations and NF-e deliveries get highest priority. Marketing messages get lowest. Under rate limit pressure, low-priority messages are shed first, so transactional ones go out. Dropped messages are logged to a dead letter queue for retry via batch processing during off-peak hours.

// Design sketch: a priority-based message queue
const queue = cs.whatsapp.createQueue({
  maxConcurrent: 50,            // msgs/sec for Cloud API
  backoff: {
    type: "exponential",
    initialDelay: 1000,         // 1 second
    maxDelay: 30000,            // 30 seconds cap
    jitter: true,               // prevent thundering herd
  },
  maxRetries: 5,
  priorities: {
    "payment_confirmation": 100, // highest priority
    "nfe_delivery": 90,          // legal requirement
    "shipping_update": 70,
    "order_confirmation": 60,
    "support_response": 50,
    "marketing": 10,             // lowest - shed under pressure
  },
  onDrop: (msg) => {
    // Dead letter queue for batch retry
    cs.deadLetter.enqueue({
      ...msg,
      droppedAt: Date.now(),
      reason: "rate_limit_exceeded",
      retryAfter: "next_off_peak",
    });
  },
});

Message delivery failures

WhatsApp messages can fail to deliver for reasons that are not immediately obvious, and the failure modes differ across APIs:

Number not on WhatsApp: The customer provided a phone number that is not registered on WhatsApp. The Cloud API returns error code 131026 with a clear message. Z-API returns a generic 400 error with inconsistent error descriptions depending on the endpoint. Evolution API may silently succeed (returning a "sent" status) while the message never actually delivers.

Template rejected at send time: A template that was approved can later be paused or disabled by Meta if it accumulates poor quality signals (low read rates, frequent blocks by recipients, or spam reports). When this happens, every message using that template fails with error 132015. There is no advance warning. No email from Meta. No webhook notification. The agent discovers this when sends start failing in production. The solution is to monitor template quality ratings programmatically and maintain backup templates for every production template.

24-hour window expired: If an agent tries to send a session message (free-form) after the 24-hour conversation window has closed, the message is rejected. The agent must send a new template message (incurring a new conversation charge) to reopen the window. This is a common source of customer support tickets: "Why did my agent stop responding?" Because the conversation window expired and the agent tried to send a free-form message instead of a template.

Media upload failures: Sending images (Pix QR codes, product photos) and documents (NF-e DANFE PDFs) requires either pre-uploading media to WhatsApp's CDN or providing a publicly accessible URL. If the URL is behind authentication, returns a non-200 status, takes more than 5 seconds to respond, or the content exceeds 16MB, the media upload silently fails and the message is sent without the attachment. The customer receives a text message with a caption that references an image or document that is not there.

Webhook reliability

Webhooks are how your agent learns about incoming messages, delivery statuses, and payment callbacks. They are also the most fragile part of the entire system, and the failure modes are insidious because they are often silent.

Failure Mode                  Impact              Mitigation
──────────────────────────────────────────────────────────────────
Your server is down           Messages lost       Redundant endpoints,
                                                  dead letter queue,
                                                  health monitoring

Webhook handler > 5s          Meta retries 3x     Keep handler < 500ms.
                              then gives up        Enqueue + ack immediately.
                                                  Process async.

Duplicate webhooks            Double-processing   Idempotency keys on
                              (double charges,    every payment callback.
                              double NF-e!)       Dedupe in handler.

Out-of-order delivery         "Delivered" before  Sequence numbers +
                              "sent" status       event reordering buffer

Signature validation          Legit webhooks      Rotate keys correctly.
failure                       rejected = lost     Cache Meta's public keys.
                              messages            Handle key rotation events.

Z-API relay failure           No retry on their   Poll Z-API status endpoint
                              side = silent drop  every 60s as fallback.
                                                  Log gaps in message IDs.

Meta webhook IP changes       Firewall blocks     Don't IP-allowlist.
                              new IPs = outage    Validate via HMAC signature
                                                  only. Meta documents this.

The double-processing problem deserves special attention. If a payment confirmation webhook is delivered twice (which happens under network instability, server restarts, or Meta's retry logic), your agent must not generate two Pix charges, emit two NF-e invoices, or send two confirmation messages. Idempotency is not optional in WhatsApp commerce — it is a legal and financial requirement. A duplicate NF-e is a fiscal violation. A duplicate Pix charge is a consumer protection violation.

Template approval delays

Every business-initiated WhatsApp message requires a pre-approved template. Meta reviews these templates for compliance with their commerce and messaging policies. The documented SLA is 24-48 hours. Here is what actually happens:

New accounts face stricter review. First-time template submissions from newly verified WhatsApp Business Accounts often take 3-5 business days. Meta does not provide an escalation path for standard-tier accounts.

Rejections are cryptic and non-specific. Meta provides a rejection reason from a fixed list (e.g., "INVALID_FORMAT", "PROMOTIONAL_CONTENT", "SCAM") but no specific guidance on which part of the template triggered the rejection. This means iterative submission-rejection cycles where you change one word at a time trying to figure out what Meta's automated reviewer flagged. The appeal process exists but is slow (5-10 business days).

Templates can be paused retroactively. If an approved template accumulates poor quality signals (customers blocking the business after receiving it, low read rates, spam reports), Meta will pause it without advance notice. The agent discovers this when sends start failing. There is no "warning" state — it goes directly from approved to paused. The only mitigation is proactive quality monitoring and maintaining backup templates with alternative wording for every production template.

Privacy and compliance: LGPD, opt-in, and message retention

Brazil's Lei Geral de Proteção de Dados (LGPD) — the country's data protection law modeled after the EU's GDPR — imposes specific requirements on WhatsApp commerce that many implementations treat as an afterthought. This is a legal liability that scales linearly with message volume. The ANPD (Brazil's data protection authority) has been increasingly active in enforcement since 2024, with fines reaching R$50 million for serious violations.

Opt-in requirements

Under both LGPD and Meta's WhatsApp Business Policy, businesses must obtain explicit opt-in before sending template messages (business-initiated conversations). This is not a suggestion and it is not a best practice. Meta enforces it algorithmically and will restrict your WhatsApp Business Account if violation reports accumulate past threshold.

What qualifies as valid opt-in: The customer messages your business first on WhatsApp (implicit opt-in for that conversation). The customer checks a box during an online purchase explicitly consenting to WhatsApp communications, with clear language specifying message types and frequency. The customer provides their phone number on a form with unambiguous language stating it will be used for WhatsApp messages.

What does NOT qualify: Purchasing a phone number list. Scraping numbers from public profiles or business directories. Adding numbers from business cards to broadcast lists without documented consent. Assuming that a customer who provided their number for delivery purposes consented to marketing messages. A verbal agreement during an in-person interaction (not documented, not verifiable). Pre-checked consent boxes on web forms (LGPD requires affirmative action, not passive acceptance).

Message retention and data minimization

LGPD's data minimization principle (Article 6, III) requires that personal data — which includes WhatsApp messages containing names, phone numbers, CPF numbers, addresses, and purchase history — must be retained only for as long as necessary for the stated purpose and must be deletable upon customer request.

This creates a genuine tension with compliance requirements in other domains. Brazilian tax law requires NF-e records to be retained for 5 years. The Consumer Defense Code (Código de Defesa do Consumidor) requires proof of transaction for dispute resolution for up to 5 years. WhatsApp conversation logs that contain payment confirmations and delivery receipts may need to be retained for years for fiscal and consumer protection purposes — but the personal data within them falls under LGPD's minimization principle.

The resolution is not simple deletion but rather data anonymization with selective retention:

// Design sketch: LGPD-compliant message retention
const retentionPolicy = cs.compliance.defineRetention({
  // Transactional: retain 5 years (tax/fiscal requirement)
  transactional: {
    retain: "5y",
    includes: ["payment_confirmation", "nfe_delivery", "refund"],
    anonymizeAfter: "5y",     // replace PII with hashes
    legalBasis: "legal_obligation",  // LGPD Art. 7, II
  },
  // Service: retain 2 years (consumer dispute window)
  service: {
    retain: "2y",
    includes: ["support_ticket", "complaint", "return_request"],
    anonymizeAfter: "2y",
    legalBasis: "legitimate_interest",  // LGPD Art. 7, IX
  },
  // Marketing: retain 90 days only
  marketing: {
    retain: "90d",
    includes: ["promotion", "broadcast", "reengagement"],
    deleteAfter: "90d",       // full deletion, not anonymization
    legalBasis: "consent",    // LGPD Art. 7, I (revocable)
  },
  // On customer deletion request (LGPD Art. 18, VI)
  onDeletionRequest: {
    deleteMarketing: "immediate",
    anonymizeService: "immediate",
    anonymizeTransactional: "immediate",  // can't delete fiscal data
    retainFiscalRecords: true,            // legal obligation overrides
    responseDeadline: "15d",              // LGPD requires response in 15 days
    notifyCustomer: true,                 // confirm what was deleted/anonymized
  },
});

Data residency considerations

WhatsApp messages in transit are end-to-end encrypted. But once your webhook receives a message and your system stores it, you are the data controller under LGPD. The choice of WhatsApp API affects where data is processed:

WhatsApp Cloud API: Meta processes messages through their global infrastructure (which includes US and EU servers) before delivering webhooks to your endpoint. For businesses subject to strict data residency requirements (financial services, healthcare), this is a compliance consideration. The ANPD has not issued specific guidance on WhatsApp Cloud API data flows, but the international data transfer provisions of LGPD (Chapter V) apply.

Z-API: Cloud-hosted in Brazil (AWS São Paulo region based on their documentation). Message data stays in Brazilian infrastructure during processing. Good for data residency, but you are dependent on Z-API's own data handling practices and need a DPA (Data Processing Agreement) with them.

Evolution API: Self-hosted wherever you deploy it. If you run it on a Brazilian VPS or cloud region, data residency is fully under your control. This is the strongest option for organizations with strict data sovereignty requirements. The tradeoff is operational responsibility.

WhatsApp + Pix + NF-e: the killer stack for LatAm agent commerce

Individually, WhatsApp is a messaging channel. Pix is a payment rail. NF-e is an invoicing system. Together, they form something that exists nowhere else in the world: a complete, instant, zero-friction commerce loop that can be fully automated by an AI agent without any web infrastructure.

Why this stack is unique to Brazil

No other country has this exact combination of ingredients at this level of adoption. India has UPI (instant payments comparable to Pix in volume) and WhatsApp (500M+ users), but lacks a standardized electronic invoicing system that integrates as cleanly as NF-e — India's GST e-invoicing is still evolving. Indonesia has GoPay and WhatsApp but no central-bank-mandated instant payment rail with universal bank interoperability. Mexico has SPEI (instant bank transfers) and WhatsApp, but its mobile payment adoption (CoDi/DiMo) is below 5% — a fraction of Pix's 75% penetration.

Brazil's unique position comes from three regulatory and cultural forces that converged in the span of five years:

Central Bank innovation (Pix, 2020): The Banco Central do Brasil did not merely create Pix. They mandated that every bank and fintech in Brazil support it. This is not optional. Nubank, Itaú, Bradesco, Banco do Brasil, PicPay, Mercado Pago — every institution with a banking license must offer Pix. The result is universal interoperability. A Pix payment from Nubank to Itaú settles in the same 10 seconds as Nubank to Nubank. No intermediary. No clearing delay. No settlement risk.

Tax modernization (NF-e, 2006-present): Brazil was one of the first countries in the world to implement fully electronic invoicing at national scale. Every formal commercial transaction requires an NF-e issued in real-time to the state tax authority (SEFAZ). The NF-e XML is a standardized document with a well-documented schema that any system can parse, verify, and store. This means an agent can issue legally valid invoices through an API — a capability that does not exist in most other countries.

Cultural adoption (WhatsApp, 2012-present): WhatsApp was not imposed by regulation. It won through network effects in a market where SMS was prohibitively expensive (R$0.25-0.50 per message in the 2010s) and mobile data plans were cheap (thanks to competitive pricing from carriers like TIM and Claro). By the time Meta acquired WhatsApp in 2014 for $19 billion, it was already the dominant communication tool in Brazil. Today, saying "manda um zap" (send a WhatsApp) is as natural as saying "send a text" in the US.

The complete loop in production

// The Complete Loop in production: WhatsApp + Pix + NF-e
// Example data: the customer, the items and the amounts are made up.
import { CodeSpar, type ChargeResult } from "@codespar/sdk";

const cs = new CodeSpar({ apiKey: process.env.CODESPAR_API_KEY });
const session = await cs.create("store_0001", { preset: "brazilian" });
const customer = { name: "Maria Silva", phone: "5511999887766", cpf: "12345678900" }; // phone: country code + number, digits only

// Step 1: Customer messages on WhatsApp
// "Oi, quero 2 camisetas azuis tamanho M"

// Step 2: Agent creates the Pix charge (R$158.00, in reais) and sends it
const charge = await session.execute("codespar_charge", {
  method: "pix",
  amount: 158,
  currency: "BRL",
  description: "2x Camiseta Azul M",
  buyer: { name: customer.name, phone: customer.phone, document: customer.cpf },
});
const pix = charge.data as ChargeResult;

await session.execute("codespar_notify", {
  channel: "whatsapp",
  to: customer.phone,
  message: `Pix de R$ 158,00. Copia e cola: ${pix.pix_copy_paste}`,
});

// Step 3: Customer pays via Pix in the bank app
// Opens Nubank/Itaú/etc → scans QR or pastes code → confirms

// Step 4: Once the charge is paid, issue the NF-e
const { payment_status } = await session.paymentStatus(charge.tool_call_id!);
if (payment_status === "succeeded") {
  await session.execute("codespar_invoice", {
    action: "issue",
    type: "nfe",
    recipient: { name: customer.name, document: customer.cpf },
    items: [{ description: "Camiseta Azul M", quantity: 2, unit_price: 79 }],
  });

  // Step 5: Create the shipping label
  const ship = await session.ship({
    action: "label",
    origin: { postal_code: "01310100", city: "São Paulo", state: "SP" },
    destination: { postal_code: "22041080", city: "Rio de Janeiro", state: "RJ" },
    items: [{ description: "2x Camiseta Azul M", weight_g: 400 }],
    service_level: "cheapest",
  });

  // Step 6: Send the tracking code on WhatsApp
  await session.execute("codespar_notify", {
    channel: "whatsapp",
    to: customer.phone,
    message: [
      "Pagamento confirmado! A nota fiscal foi emitida.",
      `Rastreio: ${ship.tracking_code}`,
      `Transportadora: ${ship.carrier}`,
      `Previsão: ${ship.estimated_delivery}`,
    ].join("\n"),
  });
}

// Customer never left WhatsApp.

Why agents belong on WhatsApp, not on websites

The argument for AI agents operating natively on WhatsApp is not about notification delivery rates, although those matter. It is about meeting customers where they already conduct commerce — and eliminating every point of friction between intent and purchase.

The web is a detour in LatAm

When a Brazilian customer clicks a link in a WhatsApp message that opens a web browser, conversion drops by 40-60% (based on data published by VTEX and Nuvemshop, two major Brazilian e-commerce platforms). The browser is foreign territory. The customer has to wait for the page to load (often on 3G), potentially log in, find the product again, enter payment details, and complete a checkout flow that was designed for desktop users in North America. Every extra step is a drop-off point.

An agent that keeps the entire transaction inside WhatsApp eliminates this drop-off entirely. The conversation is the checkout flow. The Pix QR code is the payment page. The Pix confirmation in the customer's bank app is the proof of payment; the NF-e is the fiscal document, and on the path this article describes the agent tells the customer about it in a text message, not an attachment. No context switching. No page loads. No form fills.

Conversational commerce outperforms browse-and-buy

Data from the Brazilian e-commerce sector shows that conversational commerce (initiated via WhatsApp or chat) has a conversion rate of 8-15%, compared to 1.5-3% for traditional web-based e-commerce (E-Commerce Brasil, 2024). The reason is structural: in a conversation, the customer states their intent directly ("I want a Bluetooth headphone under R$200"), the agent provides a specific recommendation, and the customer pays. There is no browsing, no comparison shopping, no cart abandonment. The funnel is compressed from 5-7 steps to 2-3 interactions.

For AI agents, our thesis is that this effect gets amplified. The agent knows the customer's purchase history, understands natural language requests ("manda aquele mesmo tênis que comprei mês passado mas no 43"), and can generate a personalized Pix charge in the same message as the product recommendation. If conversational commerce already converts at a multiple of web checkout, an agent that removes the remaining friction (search, cart, redirect) should land materially above it. CodeSpar has not published funnel numbers.

Automation for what was always conversational

Here is the thing that most Silicon Valley observers miss: conversational commerce is not new in Latin America. Brazilian shopkeepers have been running their businesses via WhatsApp for a decade — manually. They copy-paste product photos from a folder, calculate totals on a calculator app, generate Pix QR codes from their bank app, screenshot the receipt, and send it to the customer. They do this for every single order. This works for 10 orders a day. It does not work for 100 or 1,000.

AI agents are the automation layer that WhatsApp commerce has been waiting for. Not chatbots with rigid decision trees that break when the customer says something unexpected. Not rule-based auto-responders that can only handle exact keyword matches. Agents that can understand "manda aquele mesmo tênis que comprei mês passado mas no 43" ("send me the same sneaker I bought last month but in size 43"), look up the customer's order history, check real-time stock for size 43, and generate a new Pix charge — within the permissions and approvals configured, all within the same WhatsApp thread.

Lessons for implementers

Vendor blog posts that only share wins are useless. Here is what tends to go wrong in a WhatsApp commerce implementation, and what to do about it.

Plan for template approval friction

Template approval takes longer than the documented turnaround, templates can be rejected for ambiguous wording, and an approved template can be paused later. Submit templates in small batches, keep A/B variants, and pre-submit backup templates before you need them.

Do not assume webhook delivery is reliable

It is reliable — until it is not. When the provider has an incident, incoming messages can be missed: the customer sees the message as delivered and gets no answer. Run a polling fallback that checks for missed messages when webhook delivery volume drops below the expected baseline, and keep a secondary webhook endpoint on a different cloud provider.

Handle Pix expiration

Pix charges expire on the schedule of the provider that issues them; codespar_charge sets no expiration window. When a customer opens the QR code after expiration, the payment fails on the bank side — the bank app shows "charge not found" or "expired." If the customer then messages "paguei" ("I paid") and no payment webhook arrives, an agent with no record of the failed attempt treats it as a fresh message. As the integrator, send a reminder before the charge expires ("Your payment link expires soon — want me to generate a new one?"), and create a fresh charge if the customer answers after expiration.

Plan for Evolution API session instability

Evolution API (Baileys) maintains a WebSocket session with WhatsApp Web servers. This session drops under three conditions: Meta pushes a WhatsApp Web update (every 2-4 weeks), the server running Evolution API restarts or runs out of memory, or the session has been idle for 14+ days. Each time, the agent goes offline until someone manually scans a QR code from the physical phone. At 3 AM on a Saturday, that means the agent is offline until Monday morning. Run a frequent health check, alert on session disconnection, and keep a runbook for QR re-pairing that any on-call engineer can follow.

Our WhatsApp MCP servers

We publish two WhatsApp MCP servers on npm, under the MIT license. Each wraps a different WhatsApp API and has its own tools; the lists below are the tools in version 0.2.2 of each package.

send_text                  → Send a text message
send_image                 → Send an image message
send_document              → Send a document
send_audio                 → Send an audio message
get_contacts               → Get all WhatsApp contacts
check_number               → Check if a phone number has WhatsApp
get_profile_picture        → Get profile picture URL for a phone number
get_messages               → Get messages for a phone number
send_button_list           → Send a button list message
get_status                 → Get WhatsApp instance connection status
create_group               → Create a WhatsApp group
get_group_metadata         → Get group metadata and participants
add_group_participant      → Add a participant to a WhatsApp group
remove_group_participant   → Remove a participant from a WhatsApp group
send_location              → Send a location message
send_contact               → Send a contact card
add_label                  → Assign a label/tag to a chat
get_labels                 → List all available labels/tags
read_message               → Mark messages as read
delete_message             → Delete a message
get_contact_metadata       → Get a contact's name, profile picture and status
add_contacts               → Add one or more contacts to the WhatsApp address book
list_chats                 → List all WhatsApp chats with pagination
mark_chat_as_read          → Mark an entire chat as read or unread
list_groups                → List all WhatsApp groups with pagination
send_option_list           → Send an interactive option list
send_button_actions        → Send interactive action buttons

send_text                  → Send a text message
send_image                 → Send an image message
send_document              → Send a document
get_instances              → List all WhatsApp instances
create_instance            → Create a new WhatsApp instance
get_qrcode                 → Get QR code for instance pairing
get_contacts               → Get contacts from an instance
send_poll                  → Send a poll message
get_messages               → Get messages from a chat
check_number               → Check if a phone number is registered on WhatsApp
create_group               → Create a WhatsApp group
get_group_info             → Get group metadata, participants, and settings
update_profile             → Update instance profile
set_presence               → Set online/offline presence for an instance
get_chat_history           → Get full chat history with pagination support
logout_instance            → Logout an instance
restart_instance           → Restart an instance
delete_instance            → Delete an instance permanently
connection_state           → Get the connection state of an instance
leave_group                → Leave a WhatsApp group
update_group_participants  → Add, remove, promote, or demote participants
fetch_group_invite_code    → Fetch the invite code/link for a WhatsApp group
mark_message_as_read       → Mark one or more messages in a chat as read
archive_chat               → Archive or unarchive a chat
delete_message             → Delete a message for me or for everyone in a chat

Through CodeSpar, the agent calls codespar_notify with channel: "whatsapp", and CodeSpar routes it by country: in Brazil to Z-API's send_text, outside Brazil to Twilio. codespar_notify does not route to Evolution API; that server is used directly from an MCP client. CodeSpar does not rate-limit, queue or retry the message. When Z-API accepts the send-text request, codespar_notify returns the message id Z-API sent back, the channel, the recipient and the status QUEUED. QUEUED means only that Z-API accepted the request: it does not say the message was delivered or read.

The strong opinion

Most takes on WhatsApp commerce are equivocal. "WhatsApp is one of many channels." "Consider WhatsApp as part of an omnichannel strategy." "WhatsApp can complement your existing email marketing."

These takes are wrong — at least for Latin America. They reflect an American mental model where email is the default and everything else is supplementary. In Brazil, the hierarchy is inverted. WhatsApp is the default. Everything else is the supplement.

The 500 million WhatsApp users in Latin America are not waiting for a better website. They are not waiting for a better app. They are not waiting for a chatbot that routes them to a FAQ. They are having commerce conversations on WhatsApp right now — 6 million businesses, millions of transactions per day — and they need agents that can participate in those conversations natively, intelligently, and reliably.

The infrastructure exists. Pix handles payments instantly and universally. NF-e handles invoicing programmatically and legally. WhatsApp handles the conversation with 90%+ engagement. What has been missing is the intelligence layer — agents that can understand intent, manage inventory, process payments, issue invoices, handle exceptions, and recover from failures, all within a WhatsApp thread, within the permissions and approvals configured.

That is what we are building at CodeSpar. Not a chatbot. Not a notification service. Not another "omnichannel platform" that treats WhatsApp as one of twelve equally weighted integrations. A commerce agent runtime that treats WhatsApp as the primary interface because that is what the market demands.

The businesses that understand this — that WhatsApp is not a channel but the platform — will win in LatAm commerce. The ones that treat WhatsApp as an afterthought will wonder why their engagement rates, conversion rates, and customer satisfaction scores lag behind every local competitor.

Atualizado em 07/10/2026: os exemplos de conversa até pagamento e do loop completo agora compilam com o @codespar/sdk 0.16.11 (cobrança Pix por codespar_charge, nota por codespar_invoice, frete por codespar_ship, mensagens por codespar_notify, confirmação por um trigger em commerce.payment.succeeded). Estavam marcados como 0.2.0, mas usavam APIs que nenhuma versão publicada teve. A fila por prioridade e a retenção LGPD aparecem como esboços de design: o SDK não as oferece. Saíram o custo por mensagem e os tempos do ciclo que não foram medidos, os valores do pedido aparecem como dados de exemplo, as listas de ferramentas dos dois servidores MCP são as publicadas no npm (0.2.2), e saiu o aviso de retrato: nenhuma versão publicada do SDK tinha as APIs que o artigo mostrava. As mensagens de volta no fluxo são compostas pelo integrador, e o histórico sem fonte saiu.