Skip to content
Shortcut: /, ⌘K or Ctrl+K

Receive messages

Get the messages people send to your Numbers through webhooks or an event stream.

View as Markdown

When someone messages one of your Numbers, Polymorfa emits a message.received event. Deliver it to an HTTPS endpoint with a webhook, or read it over a server-sent event stream from your server. Both carry the same event with the same ID.

Before you begin#

  • A connected Number in a project.
  • For webhooks: a public HTTPS endpoint, and a credential with webhooks:manage or a team owner or admin in the Console.
  • For event streams: a credential with events:listen. Event streams require access.

Subscribe a webhook#

Console

  1. Select the project and open Settings → Webhooks.
  2. Add an endpoint with your public URL.
  3. Expand the message events and select message.received.
  4. Save, then store the signing secret shown in the confirmation dialog. The Console never shows it again.

Only team owners and admins can add endpoints. See Manage webhooks in the Console.

API

Create a project webhook with Create project webhook:

Shell
curl -X POST "https://api.polymorfa.com/platform/projects/$PROJECT_ID/webhooks" \
  -H "Authorization: Bearer $POLYMORFA_KEY" \
  -H "Idempotency-Key: create-inbox-webhook-1" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/polymorfa/webhook",
    "eventTypes": ["message.received", "message.ack"],
    "format": "native"
  }'

The response returns the signing secret once. Store it before you discard the response.

The Graph API does not create Polymorfa webhooks. For a Graph integration, create this webhook with "format": "meta" to receive Meta's object/entry/changes/value envelope, signed with X-Hub-Signature-256, from both connection types. See Delivery formats.

Verify and read the event#

Every delivery carries an x-webhook-signature header. Verify it against the exact request bytes before you parse the body; parsing and re-serializing the JSON changes the bytes. The TypeScript SDK does both:

TypeScript
import { isEvent, webhooks } from "@polymorfa/sdk";

export async function handleWebhook(body: ArrayBuffer, signature: string, secret: string) {
  const event = await webhooks.verify({ body, signature, secret });

  if (isEvent(event, "message.received")) {
    console.log(event.session, event.payload.conversation, event.payload.type);
  }
}

The event body has this shape:

JSON
{
  "id": "…",
  "session": "739182640518203",
  "timestamp": "2026-10-19T10:05:00.000Z",
  "event": "message.received",
  "payload": {
    "id": "739182640518977",
    "whatsapp_ids": { "linked_devices": "3EB0C767D8A1A2B5" },
    "conversation": { "id": "739182640518203", "phoneNumber": "+15550001111" },
    "fromMe": false,
    "isGroup": false,
    "pushName": "Ana",
    "timestamp": 1792405500,
    "type": "text",
    "text": "Is my order on its way?"
  }
}
FieldMeaning
idThe event ID. Deduplicate with it; retries reuse it.
sessionThe Number ID that received the message.
payload.idThe message ID. Use it to reply, react or mark it seen.
payload.conversationWho sent it: id, and phoneNumber, bsuid or username when known. Group messages add conversation.sender.
payload.typetext, image, video, audio, document, location, contact, sticker, sticker_pack, poll, reaction, button_reply, list_reply, native_flow_response, phone_number_shared, revoke, edited or unknown.
payload.timestampWhen the message was sent, in Unix seconds. Meta Cloud API Numbers send it as a decimal string.

The remaining payload fields depend on type: text, caption, mimeType, media, replyChoice, nativeFlowResponse, parentMessageId for a quoted message, and others. Meta Cloud API payloads also carry senderName, interactive, order and referral. See the message.received reference for every field, and Media previews and HD images for media details.

Respond to the delivery#

  • Return any 2xx only after you have durably accepted the event.
  • Store processed event IDs and skip repeats. Deliveries are retried and can arrive out of order.
  • Do not log raw bodies: they contain message content.

To reply, send to the received payload.conversation.id and quote payload.id if you want. See Send messages.

Read events from a stream#

Open a stream from your server instead of, or beside, a webhook:

Shell
curl -N "https://api.polymorfa.com/platform/projects/$PROJECT_ID/events/stream?types=message.received" \
  -H "Authorization: Bearer $POLYMORFA_KEY" \
  -H "Accept: text/event-stream"

Each event message holds the same event ID as the webhook. Its body is present only when hosted message storage is on for the Number; otherwise payload is null. Resume after a disconnect with the last cursor. See Stream events in real time.

Test it#

Send a message to the Number from another phone, or between two test numbers in the same project, and confirm your handler logs the event. To send a signed sample to your endpoint without a message, see Send a test delivery.

EventWhen
message.update, message.edited, message.revoked, message.deleteA received message changed or was removed.
message.reaction, message.voteSomeone reacted or voted in a poll.
message.echoA coexistence Number sent a message from the WhatsApp Business app.
message.sent, message.ack, message.failedDelivery of messages you send. See Send messages.

See also#

API version 2026-11-10 adds sticker packs and account sticker updates. These operations are a release candidate, unavailable in staging and production. See Stickers and sticker packs.