Build a platform

Put WhatsApp in your product for many customers. Onboard each customer's number, route their messages, send on their behalf, monitor and offboard.

This guide is for SaaS products, agencies and integrators that connect their customers' WhatsApp Business numbers. It walks through the whole lifecycle of a customer and links to the reference pages for details. Terms like ak_ and poolNumberId are defined in the Glossary.

The model

  • Your product is one App. The App has one API key (ak_) and one webhook URL. See Creating an App.
  • Each customer connects one or more numbers. Every connected number gets an ID (an opaque string; examples here use pn_abc123), called numberId in onboarding events and poolNumberId everywhere else. Same value.
  • You keep the mapping. You pass your own customer ID as metadata when you start a signup, PipesBot hands it back when the number is connected, and you store numberId → customerId.

What PipesBot handles for you

PipesBot is a registered Meta Tech Provider, so you don't become one. You skip Meta's App Review, you never store Meta access tokens, and you don't subscribe webhooks for each customer's WhatsApp Business Account (WABA): PipesBot does it when the number connects.

Your customer sees your App's name on the consent screen, then completes Meta's official Embedded Signup with their own Meta account. That step is Meta's and can't be branded.

Onboard a customer

Before onboarding anyone, set your App's webhook URL (see Know when they're done).

From your backend, create a one-time signup token. Put your customer ID in metadata:

curl -X POST https://api.pipes.bot/v1/apps/token \
  -H "Authorization: Bearer ak_your_app_key" \
  -H "Content-Type: application/json" \
  -d '{
    "redirectUrl": "https://yourapp.com/whatsapp/connected",
    "metadata": { "customerId": "cus_123" }
  }'
{ "token": "<JWT>", "expiresAt": "2025-01-15T10:45:00.000Z" }

Then send your customer to the signup page, for example from a "Connect WhatsApp" button in your product:

https://app.pipes.bot/apps/{your-app-slug}?token={token}

The token is valid for 15 minutes and is single-use: it onboards exactly one number. Create a new one each time a customer clicks the button.

The signup page follows your customer's browser language (English, Spanish or Brazilian Portuguese). To force one, pass locale when you create the token. See Signup page language.

If the number is on the WhatsApp Business app, the customer picks the option to connect their existing app number, and it connects with Coexistence: they keep using the app on their phone. Full details: Embedded Signup.

Know when they're done

You learn that a customer finished in two ways. Use both: the webhook is the source of truth, the redirect is for your UI.

  • number.onboarded webhook. PipesBot POSTs it to your App's webhook URL, with the metadata you passed echoed back. It is sent only if your App has a webhook URL when the number connects.
  • Redirect. Once the number is ready, the customer's browser returns to your redirectUrl with ?numberId=&phone= appended. While a step is pending, such as the two-step verification PIN, they stay on the signup page.
  • Listing. If you missed the webhook, GET /v1/numbers returns every number connected to your App, with the same metadata. See Listing numbers.
{
  "event": "number.onboarded",
  "timestamp": "2025-01-15T10:30:00.000Z",
  "data": {
    "numberId": "pn_abc123",
    "phoneNumber": "+1 555-123-4567",
    "displayName": "Acme Support",
    "appId": "app_abc123",
    "metadata": { "customerId": "cus_123" },
    "importHistory": false,
    "importContacts": false
  }
}

Store data.numberId → data.metadata.customerId. Make the handler idempotent: the event is retried if your endpoint fails. See The number.onboarded event.

Route inbound messages

All your customers share one webhook URL. You don't create an endpoint per customer. On API v2, every message, status and template update arrives as an envelope that names the number it belongs to in pipes.poolNumberId:

{
  "id": "evt_3f9c1a7b2d4e4f6a8b0c1d2e3f4a5b6c",
  "field": "messages",
  "createdAt": "2025-01-15T10:30:01.123Z",
  "pipes": { "appId": "app_abc123", "poolNumberId": "pn_abc123", "media": {} },
  "whatsapp": { "messaging_product": "whatsapp", "metadata": {}, "messages": [], "statuses": [] }
}

Look up the customer by pipes.poolNumberId, then handle whatsapp the way Meta documents it. The number.onboarded event and the Send Test ping are not envelopes (they have event instead of field), so check for them first:

import express from "express";
import { Webhook } from "standardwebhooks";

const app = express();
const wh = new Webhook(process.env.PIPES_WEBHOOK_SECRET!); // whsec_...

// History import chunks can be large, and Express rejects bodies over 100 KB by default
app.post("/webhooks/pipes", express.text({ type: "application/json", limit: "25mb" }), async (req, res) => {
  const headers = {
    "webhook-id": req.header("webhook-id")!,
    "webhook-timestamp": req.header("webhook-timestamp")!,
    "webhook-signature": req.header("webhook-signature")!,
  };

  let payload: any;
  try {
    payload = wh.verify(req.body, headers); // raw body, not re-serialized JSON
  } catch {
    return res.status(401).send("Invalid signature");
  }

  // Retries reuse the same webhook-id. Record it only after handling succeeds (see the end),
  // so a retry after a crash is processed again instead of skipped.
  const webhookId = headers["webhook-id"];
  if (await alreadyProcessed(webhookId)) return res.sendStatus(200);

  if (payload.event === "test") return res.sendStatus(200); // "Send Test" button

  if (payload.event === "number.onboarded") {
    const { numberId, metadata } = payload.data;
    // metadata is optional: numbers connected from the dashboard, or from a token
    // created without it, have none. Keep those for manual review.
    if (!metadata?.customerId) {
      await flagUnassignedNumber(numberId);
    } else {
      await saveNumber(numberId, metadata.customerId);
      await replayParkedEvents(numberId); // events that arrived before this one
    }
    await markProcessed(webhookId);
    return res.sendStatus(200);
  }

  // API v2 envelope
  const customer = await findCustomerByNumber(payload.pipes.poolNumberId);
  if (!customer) {
    // A message can arrive before you've stored number.onboarded:
    // keep it, and replay it once the number is saved (above)
    await parkUnmatchedEvent(payload);
    await markProcessed(webhookId);
    return res.sendStatus(200);
  }

  if (payload.field === "messages") {
    await handleMessages(customer, payload.whatsapp); // messages[] and statuses[]
  } else if (payload.field === "smb_message_echoes") {
    await storeEchoes(customer, payload.whatsapp); // sent from the phone: store, don't reply
  } else if (payload.field === "history" || payload.field === "smb_app_state_sync") {
    await enqueueImport(customer, payload); // past chats and contacts: process in a job, don't reply
  } else if (payload.field === "message_template_status_update") {
    await handleTemplateStatus(customer, payload.whatsapp);
  }

  await markProcessed(webhookId);
  res.sendStatus(200);
});

alreadyProcessed, markProcessed, saveNumber, flagUnassignedNumber, findCustomerByNumber, parkUnmatchedEvent, replayParkedEvents and the handlers are your own code. replayParkedEvents runs every event parked for that numberId through the same routing, so the customer's first messages aren't lost. A message can be parked while number.onboarded is still being handled, after the replay has already run. So after parking, look the number up again and replay if it now has a customer, or drain parked events from a worker that runs after saveNumber. Either way, claim each parked event before routing it so it isn't handled twice. Echoes only arrive if you turn them on; see Message echoes. The same goes for chat history and contacts; see Import chat history and contacts. Test the handler with the example payloads, and see Webhook Security for signature details.

Send on a customer's behalf

Send with your App key and the customer's number as poolNumberId. On API v2, the rest of the body is Meta's message format, forwarded untouched:

curl -X POST https://api.pipes.bot/v1/messages/passthrough \
  -H "Authorization: Bearer ak_your_app_key" \
  -H "Content-Type: application/json" \
  -d '{
    "poolNumberId": "pn_abc123",
    "messaging_product": "whatsapp",
    "to": "5511999999999",
    "type": "text",
    "text": { "body": "Your order has shipped." }
  }'

Free-form messages only reach users who wrote to the number in the last 24 hours. To start a conversation, send a template. See Sending Messages for templates, buttons, lists and media.

Templates per customer

Templates belong to each customer's WABA, not to your App. Create and manage them per number under /v1/pool-numbers/{poolNumberId}/templates, and wait for Meta's approval before sending. Status changes arrive on your webhook. See Template Management.

Limits

  • PipesBot send rate: the send endpoints (/v1/messages/app/send, /v1/messages/passthrough) allow 60 requests per minute per API key. Your App has one key, so the limit is shared by every number in your App. Going over returns 429 RATE_LIMITED. The counter is kept in memory on each server instance, so treat 60 per minute as your budget, not as a guarantee.
  • Coexistence numbers: Meta limits throughput to 20 messages per second (error 130429).

So one busy customer can't use up the budget for everyone, put a queue per customer in front of your sends and drain the queues in turn (round-robin), staying under 60 sends per minute in total. On 429, wait and retry the same message.

Monitor number health

A number can stop working without anything failing on your side: the customer revokes access in Meta Business Manager, or their WABA has a payment problem. Meta may still accept your sends and only report a failed status later.

There is no push event for this yet. Until there is:

  • Call GET /v1/pool-numbers/{poolNumberId}/health for each number on a schedule (for example hourly) and alert when it can't send. See Diagnostics.
  • Watch failed statuses on your webhook as a second signal.

What to do depends on the cause:

  • The number is unhealthy (Meta rejects its token, for example because the customer revoked access): ask the customer to reconnect. Disconnect the number and send them a new signup link. The reconnected number gets a new numberId, so update your mapping.
  • Payment error 141006: don't disconnect. The token is fine; your customer fixes the payment method in Meta Business Manager. See Who pays whom.

Offboard a customer

curl -X DELETE https://api.pipes.bot/v1/pool-numbers/pn_abc123 \
  -H "Authorization: Bearer ak_your_app_key"

Disconnecting removes the number from your App, cleans up its conversations, and revokes the Meta webhook subscription (best-effort). Billing for the number stops at the end of the current cycle. The number can be onboarded again later. See Disconnecting a number.

Next steps

On this page