---
title: "Referral received event"
method: POST
path: "referral.received"
tags: ["Webhook Events"]
---

# Referral received event

`POST referral.received` (webhook)

Fired when someone opens an EXISTING Instagram or Messenger thread
through an attributable entry point - an ig.me / m.me link with a
`ref` parameter, or (Messenger) a returning Click-to-Message ad click -
which Meta delivers as a standalone referral with no message attached.
A referral that rides an inbound message (first message of a thread,
icebreaker taps, returning ad clicks on Instagram) arrives on
`message.received` under `metadata.referral` instead; the two never
fire for the same click. The first referral captured on a conversation
is also persisted on it (see `metadata` on `GET
/v1/inbox/conversations`). Requires the Inbox add-on.

## Payload

- WebhookPayloadReferral — Webhook payload for referral received events (Instagram, Facebook Messenger)
  - `id` string, required — Stable webhook event ID
  - `event` 'referral.received', required
  - `referral` object, required — Meta's referral object, forwarded verbatim. Same shape as `metadata.referral` on `message.received`: `ref` + `source` for ig.me / m.me links, `ad_id` + `ads_context_data` for returning Messenger ad clicks.
    - `ref` string — The `ref` parameter of the clicked ig.me / m.me link or ad.
    - `source` string — Meta-supplied source (`SHORTLINK`, `SHORTLINKS`, `IGME-SOURCE-LINK`, `ADS` - treat as opaque).
    - `type` string — Meta-supplied referral type (e.g. `OPEN_THREAD`).
    - `referer_uri` string — URI of the originating site, when Meta supplies one. Facebook Messenger only.
    - `ad_id` string — The Meta ad ID, on returning ad clicks. Facebook Messenger only.
    - `ads_context_data` object — Snapshot of the ad's public context at click time.
      - `ad_title` string
      - `photo_url` string
      - `video_url` string
      - `post_id` string
      - `product_id` string
      - `flow_id` string
  - `sender` object, required — Who clicked - the conversation participant.
    - `id` string, required — Platform-scoped user ID (IGSID / PSID).
    - `contactId` string — Zernio CRM Contact id for this sender, when one exists.
  - `conversation` InboxWebhookConversation, required — The conversation context included in inbox webhook payloads.
    - `id` string, required
    - `platformConversationId` string, required
    - `participantId` string
    - `participantName` string
    - `participantUsername` string
    - `participantPicture` string
    - `status` 'active' | 'archived', required
    - `contactId` string — Zernio CRM Contact ID for the participant, when one exists. Resolved by joining `participantId` to the ContactChannel collection. Best-effort: omitted when no channel matches or `participantId` is absent. Lets integrators join any inbox webhook back to the CRM Contact without needing to look at the sender — which matters for outgoing and delivery-status events whose sender is the business.
  - `account` InboxWebhookAccount, required — The account context included in inbox webhook payloads.
    - `id` string, required — Social account ID
    - `accountId` string — Social account ID (same value as id). Canonical field so consumers can filter every webhook event on one field (e.g. route staging vs production by account). id is kept for backward compatibility.
    - `profileId` string — Zernio profile (workspace) ID this account belongs to. Use it to route or filter inbox webhooks by workspace. This is the profile ID only, not its name (resolve the name via the API with this ID). Optional; omitted on the shared WhatsApp sandbox account and when the account has no resolvable profile.
    - `platform` string, required
    - `username` string, required
    - `displayName` string
  - `timestamp` string, date-time, required — UTC time at which Zernio generated this event (set once when the event payload is built, before delivery is queued). Retries and redeliveries keep the original value, so it reflects the event, not the delivery attempt.

## Acknowledgement `200`

Webhook received successfully

---

[API](https://skmtc.net/zernio/apis/zernio-api.md) · [All operations](https://skmtc.net/zernio/apis/zernio-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/zernio/zernio-api/revisions/3c7cf84cec44/schema)