Migrate from Meta Cloud API

Choose the migration boundary

Yanola becomes the provider boundary between your application and Meta. Your application calls Yanola with a Yanola API key; Yanola owns the connected Meta credential, provider call, delivery reconciliation, and operational record.

WhatsApp product rules still apply. The migration removes provider credentials and Graph-version maintenance from application code, but it does not bypass number registration, template approval, the 24-hour Customer Service Window, or WhatsApp policy.

Map direct Meta concepts to Yanola

Verify the connected Sender and templates

Connect the WhatsApp number to the intended Agent Project before changing application traffic. A key can use only Senders in that project and, when configured, only the key's explicit Sender allowlist.

Compare the Yanola template catalog with the names, languages, and components your direct integration uses. Catalog entries remain Sender-specific because approval still belongs to the underlying WhatsApp business account.

import { WhatsAppClient } from "@yanola/whatsapp"

const apiKey = process.env.YANOLA_API_KEY

if (!apiKey) {
  throw new Error("Missing YANOLA_API_KEY")
}

const yanola = new WhatsAppClient({ apiKey })

const senderPage = await yanola.senders.list({ limit: 100 })
const sender = senderPage.data.find(
  (candidate) => candidate.phoneNumber === "+15557654321"
)

if (!sender?.apiEligible) {
  throw new Error("Sender is not API-eligible")
}

const templatePage = await yanola.templates.list({
  from: sender.phoneNumber,
  refresh: true,
  limit: 100,
})

console.log(
  templatePage.data.map(({ name, languageCode, status }) => ({
    name,
    languageCode,
    status,
  }))
)

Replace the Graph send call

A direct Cloud API text send posts to graph.facebook.com/<GRAPH_VERSION>/<PHONE_NUMBER_ID>/messages with messaging_product, type, and a nested text object. With Yanola, the key supplies account, project, and environment context while from selects the Sender.

The SDK adds Bearer authentication and generates an idempotency key when you do not supply one. Keep an application-owned key when a queue or business operation can retry the same logical send.

import { WhatsAppClient } from "@yanola/whatsapp"

const apiKey = process.env.YANOLA_API_KEY

if (!apiKey) {
  throw new Error("Missing YANOLA_API_KEY")
}

const yanola = new WhatsAppClient({ apiKey })

const accepted = await yanola.messages.sendText(
  {
    from: "+15557654321",
    to: "+15551234567",
    body: "Your order is ready",
    previewUrl: false,
  },
  {
    idempotencyKey: "order-A-1042-ready-v1",
  }
)

console.log(accepted.id, accepted.status, accepted.requestId)

Translate message operations

Non-template Live Mode sends still require an inbound message to the same Sender within the previous 24 hours. A 422 service_window_required response should route the business flow to an appropriate approved template, not to an automatic retry.

Adopt Yanola IDs and state

Persist the accepted msg_ or msg_test_ ID as the primary messaging reference. Retain requestId for support and transport debugging, evt_ IDs for event deduplication, del_ IDs for delivery attempts, conv_ IDs for conversation correlation, and med_ IDs for inbound media.

A provider message ID can appear inside retained Meta-compatible detail, but it is not the Yanola public control-plane ID and might not exist on synthetic or non-Meta-originated events.

Move the webhook trust boundary

Create the Test Mode and Live Mode endpoints in the Agent Project dashboard. Yanola does not call your route with Meta's GET hub.challenge verification flow, and your handler must not require hub.mode or hub.verify_token before accepting Yanola deliveries.

Replace X-Hub-Signature-256 verification with the endpoint's copy-once YANOLA_WEBHOOK_SECRET and yanola-signature. Yanola signs <timestamp>.<exact raw body>, includes a five-minute default tolerance in the SDK helper, and can emit multiple v1 digests during secret rotation.

Adapt an existing Meta-shaped handler

Select meta payload mode to keep the unwrapped object, entry, changes, value, messages, contacts, and statuses shape while you replace the transport boundary. Verify Yanola's signature over the raw body before handing parsed JSON to the existing parser.

1. Read yanola-signature, yanola-event-id, yanola-delivery-id, and yanola-payload-format case-insensitively from the request headers.
2. Verify the exact raw body before JSON.parse or any side effect.
3. Validate the runtime JSON before treating it as MetaWebhookPayload.
4. Deduplicate with yanola-event-id, durably persist the event, and then return 2xx.
5. Process the familiar messages or statuses arrays asynchronously.

import {
  verifyYanolaWebhookSignature,
  type MetaWebhookPayload,
} from "@yanola/whatsapp"

async function acceptYanolaDelivery(input: {
  rawBody: string
  signature: string | undefined
  eventId: string | undefined
}) {
  if (
    !verifyYanolaWebhookSignature({
      secret: process.env.YANOLA_WEBHOOK_SECRET!,
      signature: input.signature,
      rawBody: input.rawBody,
    })
  ) {
    throw new Error("Invalid Yanola webhook signature")
  }

  if (!input.eventId) {
    throw new Error("Missing yanola-event-id")
  }

  const payload = JSON.parse(input.rawBody) as MetaWebhookPayload

  await webhookInbox.insertOnce({
    id: input.eventId,
    payload,
  })
}

Know the Meta-compatible caveats

Meta-compatible means compatible JSON structure. It is not a byte-for-byte replay of Meta's original HTTP request, and it does not preserve Meta's authentication, batching, identifiers, timing, or every provider-only field.

Migrate inbound media and read receipts

An existing Meta parser can recognize an inbound media-shaped message, but application code should move from Meta media downloads to the Yanola event and media resources. Retrieve the normalized event identified by yanola-event-id to obtain its public message and med_ references.

client.media.retrieve returns a short-lived signed Yanola proxy URL. Download it before expiresAt and never add a Meta Authorization header. To mark the inbound message read, pass its public msg_ ID to client.messages.markAsRead; a retained wamid is not accepted by that route.

import { WhatsAppClient } from "@yanola/whatsapp"

const apiKey = process.env.YANOLA_API_KEY

if (!apiKey) {
  throw new Error("Missing YANOLA_API_KEY")
}

const yanola = new WhatsAppClient({ apiKey })

const event = await yanola.events.retrieve("evt_...")
const publicMessageId = event.data.data.message?.id
const publicMediaId = "med_..." // From the normalized inbound payload

const media = await yanola.media.retrieve(publicMediaId)
const response = await fetch(media.downloadUrl)
const bytes = await response.arrayBuffer()
console.log(bytes.byteLength, media.expiresAt)

if (typeof publicMessageId === "string") {
  await yanola.messages.markAsRead(publicMessageId)
}

Test the cutover without double sends

1. Create a narrowly scoped Test Mode key and a separate Test Mode webhook endpoint in meta payload mode.
2. Run representative text, template, media, location, contact-card, and mark-read requests through @yanola/whatsapp and assert msg_test_ IDs, logs, synthetic events, and signatures.
3. Exercise duplicate delivery and replay handling with yanola-event-id before enabling a Live endpoint.
4. Create the Live Mode key and endpoint separately; never reuse Test Mode secrets or assume test records cross environments.
5. Choose one send path per business operation during rollout. Do not call Meta directly and Yanola for the same recipient action.
6. Canary a low-volume Live Sender, monitor message state, webhook deliveries, rate-limit headers, and usage records, then expand traffic deliberately.

Complete the production cutover

1. Confirm every production number appears as an active, API-eligible Sender under the intended Agent Project.
2. Confirm every required template name, language, and component layout through client.templates.list.
3. Remove Graph URL construction and Meta access-token reads from application services, workers, and deployment secrets that no longer need them.
4. Persist Yanola public IDs and update support, analytics, and reconciliation queries that previously keyed only on wamid.
5. Switch webhook verification, deduplication, health checks, and alerts to the Yanola delivery contract.
6. Fund Yanola Balance, verify subscription entitlements, and set throughput around documented rate-limit headers.
7. Keep a rollback window that prevents duplicate sends, then disable the old direct callback/send path after Yanola logs and live statuses are healthy.
8. Plan a follow-up move from meta payload mode to yanola mode so new code receives explicit event types, environment, and stable public resource projections.