# referral.received

Someone opened an existing Instagram or Messenger thread through an ig.me or m.me `ref` link or returning ad click.

### Payload notes

Meta's referral object is forwarded verbatim: `ref` and `source` for links, `ad_id` and `ads_context_data` for ad clicks.

### When it does not fire

A referral that rides an inbound message arrives on `message.received` under `metadata.referral` instead. The two never fire for the same click.

### Stored referral

The first referral captured on a conversation is also persisted on it (`metadata` on `GET /v1/inbox/conversations`).




**Payload for `referral.received`:**

- **id** (required) `string`: Stable webhook event ID: the dedupe key, also sent as the X-Zernio-Event-Id header and identical on every retry and redelivery. It identifies the event only, never an account or other resource.
- **profiles**: `WebhookProfiles` - See schema definition
- **test** `boolean`: Always true when present: only a sample sent by POST /v1/webhooks/test with an event carries it. Real deliveries never do.
- **event** (required) `string`: No description - one of: referral.received
- **referral** (required) `object`: 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`: No description
    - **photo_url** `string`: No description
    - **video_url** `string`: No description
    - **post_id** `string`: No description
    - **product_id** `string`: No description
    - **flow_id** `string`: No description
- **sender** (required) `object`: Who clicked - the conversation participant.
  - **id** (required) `string`: Platform-scoped user ID (IGSID / PSID).
  - **contactId** `string`: Zernio CRM Contact id for this sender, when one exists.
- **conversation** (required): `InboxWebhookConversation` - See schema definition
- **account** (required): `InboxWebhookAccount` - See schema definition
- **timestamp** (required) `string` (date-time): 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.