Migration: pywa to WATS

active · reviewed 2026-06-10

WATS is a Bun-first TypeScript implementation: async-only APIs, camelCase public names, package-scoped primitives, strict runtime validation, MockTransport-first tests. This page maps pywa names to their WATS equivalents. For per-capability status, the capability status matrix is authoritative; the live campaign log is the evidence.

Status tags below use the honesty taxonomy: live-validated (exercised against live Meta), shape-only (implemented and tested locally), and planned (no WATS equivalent yet).

Package and construction map

Client construction and auth

pywa commonly puts token, phone id, WABA id, server, webhook, and app secret into one WhatsApp(...) constructor. WATS separates those responsibilities:

import { GraphClient, createFetchTransport } from "@wats/graph";
import { WhatsApp } from "@wats/core";

const graphClient = new GraphClient({
  accessToken: process.env.WATS_ACCESS_TOKEN!,
  apiVersion: "v25.0",
  transport: createFetchTransport()
});

const wa = new WhatsApp({
  graphClient,
  phoneNumberId: process.env.WATS_PHONE_NUMBER_ID,
  wabaId: process.env.WATS_WABA_ID
});

Migration notes:

• Public WATS options are camelCase: phoneNumberId, wabaId, accessToken, apiVersion.
• Graph wire names remain snake_case only at the HTTP boundary.
• WATS constructors reject unsafe ids before transport.
• WATS does not resolve env-secret refs in the SDK; config/service/CLI boundaries own env indirection.

Message sending map

Media map

Templates map

Flows map

Calling map

Business and admin map

Groups map

Groups are a WATS addition with no pywa equivalent. Use them only when you intentionally target the official WhatsApp Business Platform Groups API.

Webhook, handler, filter, and listener migration

pywa decorators such as @wa.on_message, @wa.on_callback_button, @wa.on_flow_completion, and @wa.on_call_status map to WATS router/listener primitives:

import { WhatsApp, filtersTyped } from "@wats/core";

wa.on(filtersTyped.message.text("hello"), async (update) => {
  await wa.startChat({ to: update.message.from, text: "hi" });
});

Migration differences:

• WATS TypedRouter.on(...) returns a registration handle with unregister() instead of pywa decorator registration.
• WATS handlers receive TypedUpdate variants rather than pywa Python classes.
• WATS wa.listen(...) is the lower-level one-shot listener primitive. For text starts, WhatsApp.startChat(...) returns a waitable result with waitForReply, waitForClick, waitForSelection, waitForFlowCompletion, waitUntilDelivered, waitUntilRead, and waitUntilFailed, all backed by observed webhook updates through the listener registry. Broader send helpers remain planned.
• WATS filters use function composition (and, or, not, custom) rather than Python &, |, and ~ operators.
• WATS deep-normalizes common inbound message body families and adds typed filters for media, location, reaction, interactive button/list/nfm Flow-completion replies, and quick-reply buttons. This covers the most common @wa.on_callback_button, @wa.on_callback_selection, and @wa.on_flow_completion migration paths while keeping the update kind as "message".
• user_preferences maps to TypedUserPreferencesUpdate plus filtersTyped.userPreferences; system maps phone/identity changes to TypedSystemUpdate plus filtersTyped.system; chat_opened maps REQUEST_WELCOME to TypedChatOpenedUpdate plus filtersTyped.chatOpened.
• WATS still has fewer first-class typed update families than pywa for call permission updates and several status/account details. Calling webhook fields (connect/terminate/status/call_permission_reply) are fully normalized to camelCase, but call_permission_reply remains an interactive message rather than a dedicated TypedUpdate kind.

Error handling migration

pywa raises WhatsAppError subclasses keyed from Graph error codes. WATS exposes GraphApiError subclasses and a seeded registry mirroring pywa error codes where possible:

import { ExpiredAccessTokenError, GraphApiError } from "@wats/graph";

try {
  await phone.sendText({ to: "+155****4567", text: "hello" });
} catch (error) {
  if (error instanceof ExpiredAccessTokenError) {
    // refresh / rotate the token
  } else if (error instanceof GraphApiError) {
    // inspect error.code, error.subcode, error.classification
  }
}

Migration notes:

• Do not match Python class names in TypeScript code; import WATS subclasses from @wats/graph.
• WATS validation failures reject before transport with WATS-specific validation errors.
• Rate-limit retry/backoff is the opt-in createReliableTransport decorator, not automatic. The default GraphClient transport does not retry; opt in explicitly and avoid non-idempotent POST retries unless you also provide idempotency.

Import and subpath cheat sheet

Known gaps to plan around

Do not migrate code assuming WATS already has pywa parity for:

• pywa's full decorator and handler taxonomy for callback selections/buttons, Flow request sub-actions, user marketing preferences, phone-number changes, and identity changes.
• pywa sent-update waiters beyond the currently shipped process-local sent-result/click/selection/Flow-completion waiters.
• pywa's broad filter catalog: commands, MIME/extension filters, location radius, per-error-code status filters, user marketing filters, and call permission filters.
• Flow hosting and live Flow data-channel validation.
• real WebRTC/SIP call orchestration beyond WATS request/webhook shapes and call-button/deep-link helpers.
• catalog/product inventory CRUD and phone-level callback override. WATS already has profile/commerce updates, phone registration/deregistration, QR code CRUD, token exchange, and WABA callback override as shape-only helpers.
• full Meta Graph OpenAPI generation and production operator modes beyond the current credential-free wats init, wats doctor, dry-run wats serve, and credential-gated local live wats serve tooling.

Migration checklist

1. Inventory pywa imports and method names.
2. Replace constructor setup with GraphClient, PhoneNumberClient, WABAClient, and WhatsApp facade composition.
3. Convert snake_case names to camelCase.
4. Move raw secrets to env vars or @wats/config env-secret refs.
5. Replace pywa send methods with WATS scoped-client methods and root builders.
6. Replace decorators with TypedRouter.on(...) / WhatsApp.on(...) and filtersTyped.
7. Replace conversational waits with wa.listen(...) or startChat(...).waitForReply() / status waiters where applicable.
8. Add MockTransport tests before using real credentials.
9. Keep live operations behind the campaign gates: read-only before side-effecting before destructive, redact everything.