Messaging API

Every WhatsApp number, one API

Linked Devices and Meta Cloud API numbers answer the same endpoints, SDK calls and webhook events. Send 20 message kinds, run groups, channels and catalogs, or keep Meta's request format.

Start building Read the messaging guide

Two routes

Your code does not pick a side.

The number decides the route. Endpoints, SDK calls and event names stay the same, and anything a route cannot do returns a clear capability error.

Linked Devices

The business keeps its number and WhatsApp app
Groups, channels, edits, polls and catalogs
BanSafe Health on every linked number

Meta Cloud API

Official numbers and approved templates
Credential and registration checks
Meta's pricing report per number

Hybrid Link

Both connections on one Pro number
A preferred route per team, project or number
Pin a single send to either route

What you can send

One send call, 20 message kinds.

Put exactly one kind inside content: text, media and voice notes, polls, locations and contacts, buttons, lists and Flows, products, orders and templates. Some kinds work on one route only.

Each kind validates on its own. Send media from a URL or base64, reply to a message, mention people and mark a message as forwarded on the same call. Poll votes come back as message.vote.

Act on the conversation. React, edit, delete, star, mark as seen and show typing, with the message ID the send returned.

Groups, channels and commerce

What the app does, through the API.

Run groups and channels, manage the Business App catalog and send Brazil orders with Pix from the same API.

Groups. Create groups, add members, promote admins and choose who can send or join. Official numbers run groups too.

Channels. Create, follow and mute channels, react to updates and read their view and reaction counts.

Catalogs and Pix orders. Manage products and collections on linked numbers. Official numbers send orders with a Pix code, payment link or boleto, and you receive each payment update.

In your code

From key to reply in four steps.

Each step in TypeScript, the CLI or plain REST. Pick what fits your stack.

Read the messaging guide SDK docs CLI docs

send.ts

import { MessagingClient } from "@polymorfa/sdk";

const messaging = new MessagingClient({
  credential: { type: "apiKey", value: process.env.POLYMORFA_KEY! },
});

const sent = await messaging.messages.send("my-number", {
  conversation: { phoneNumber: "+15550001111" },
  content: { image: { url: "https://acme.example/1042.jpg", caption: "Packed and ready" } },
});

Receive

Events that wait for you.

Signed webhooks retry for 24 hours. Event streams carry the same events over one connection and resume from your last cursor.

88 event types. Messages, calls, groups, orders, campaigns and customers. Choose the native or Meta webhook format; both are signed with HMAC-SHA256 over the raw body.

Retries on a fixed schedule. Up to 8 attempts over 24 hours. A retry keeps the event ID, so you can drop duplicates.

Event streams. Server-sent events for servers without a public endpoint. A cursor resumes the stream for 24 hours.

Retries never send twice. Repeat a send with the same Idempotency-Key within 24 hours and it returns idempotency_completed instead of sending again.

Bring your code

Keep the code you already run.

Point Meta Cloud API code at the Graph API base URL, or connect an existing Baileys client to the Raw WhatsApp Bridge.

Meta's format on any number. Change the base URL and keep the request shape. Linked Devices numbers answer the same requests, and anything a route cannot do returns Meta's capability error.

Raw WhatsApp Bridge. A project token resolves a WebSocket endpoint. Connect your Baileys client to it.

API surface

The parts you call most.

A selection of the Messaging API. The reference lists every endpoint with its scope, request and response.

Full API reference

Messages and routing

POST/messaging/{number}/messages/sendSend any message kind
POST/messaging/{number}/messages/reactReact to a message
PUT/messaging/{number}/chats/{chat}/messages/{id}Edit a sent message
POST/messaging/{number}/messages/seenMark messages as seen
GET/messaging/{number}/contacts/checkCheck numbers are on WhatsApp
PUT/messaging/routing/hybridSet a Hybrid Link routing policy

Groups, channels and commerce

POST/messaging/{number}/groupsCreate a group
POST/messaging/{number}/groups/{id}/participants/addAdd group members
POST/messaging/{number}/official-groupsCreate a group on an official number
POST/messaging/{number}/channelsCreate a channel
POST/messaging/{number}/business/productsAdd a catalog product
POST/messaging/{number}/business/orders/{orderId}/lookupRead an order's details

Webhook events

Eventmessage.receivedSomeone wrote to the number
Eventmessage.ackDelivered and read receipts
Eventmessage.voteSomeone voted in a poll
Eventgroup.participantMembers joined, left or changed role
Eventorder.payment_updatedWhatsApp reported a payment update
Eventsession.statusThe number connected or disconnected

Streams, history and bridges

GET/platform/projects/{projectId}/events/streamStream events over SSE
GET/platform/projects/{projectId}/eventsRead event history
POST/platform/projects/{projectId}/events/{eventId}/replaysReplay an event to a webhook
POST/graph/whatsapp/v26.0/{phoneNumberId}/messagesSend in Meta's format
GET/messaging/bridge/routeResolve the Bridge endpoint

Start with a free number

Your first real number is free. Add more numbers on Pay-As-You-Go.

Start building See pricing