Messaging Events

Early access — content events

The message and chat events are newly wired on the current platform substrate. The delivery envelope is stable and safe to build against — the top-level event plus the data object, which always carries account_id and occurred_at. Individual data field shapes may still be refined as live validation completes, so pin your handler to the envelope and treat per-field additions as backward-compatible.

Quick reference

Event	Description
`message.received`	A new inbound message arrived in the account's inbox.
`message.delivered`	An outbound message was confirmed delivered to the recipient.
`message.read`	A message in the conversation was read.
`message.reaction`	A reaction was added to a message.
`message.edited`	A message was edited; the payload carries the updated text.
`message.deleted`	A message was deleted from the conversation.
`chat.updated`	A chat's container state changed (e.g. archived, muted, read-state). Opt-in.
`chat.deleted`	A chat thread was deleted. Opt-in.

The six message.* events share the same data shape (with per-event additions noted below); the two chat.* events carry a minimal chat-container shape (documented at the end). All are Core-tier. Subscribe to any subset when creating your webhook — the chat.* events are opt-in and must be named explicitly:

curl -X POST https://api.curviate.com/v1/webhooks \
  -H "Authorization: Bearer cvt_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source": "messaging",
    "request_url": "https://hooks.example.com/curviate",
    "account_ids": ["acc_YOUR_ACCOUNT_ID"],
    "events": [
      "message.received",
      "message.delivered",
      "message.read",
      "message.reaction",
      "message.edited",
      "message.deleted"
    ]
  }'

`message.received`

Fired when a new inbound message arrives in the connected account's inbox — classic LinkedIn messages or InMail.

Inbound only

message.received fires only for messages the account received — not for messages it sent. A message the account sent does not trigger this event. For outbound delivery confirmation use message.delivered.

{
  "id":          "wdl_YOUR_DELIVERY_ID",
  "webhook_id":  "wh_YOUR_WEBHOOK_ID",
  "event":       "message.received",
  "data": {
    "account_id":  "acc_YOUR_ACCOUNT_ID",
    "chat_id":     "chat_YOUR_CHAT_ID",
    "message_id":  "msg_YOUR_MESSAGE_ID",
    "text":        "Hello, I saw your profile and wanted to connect.",
    "sender": {
      "name":        "Alex Jordan",
      "profile_url": "https://www.linkedin.com/in/alexjordan",
      "provider_id": "urn:li:member:123456789"
    },
    "attachments": [],
    "occurred_at": "2026-05-28T14:22:05.000Z"
  },
  "delivered_at": "2026-05-28T14:22:06.789Z"
}

Notable fields

text — the full message body.
sender — the LinkedIn member who sent the message: name, profile_url, and provider_id (the LinkedIn member URN).
attachments — array of attachment objects; empty when there are none. Each item carries id, type, url, mimetype, and size.
chat_id — identifies the conversation; consistent across all events in the same thread.

`message.delivered`

Fired when an outbound message sent from the connected account was confirmed delivered by the platform. Use this event to close the send loop in fire-and-forget agent patterns.

{
  "id":          "wdl_YOUR_DELIVERY_ID",
  "webhook_id":  "wh_YOUR_WEBHOOK_ID",
  "event":       "message.delivered",
  "data": {
    "account_id":  "acc_YOUR_ACCOUNT_ID",
    "chat_id":     "chat_YOUR_CHAT_ID",
    "message_id":  "msg_YOUR_MESSAGE_ID",
    "text":        "Thanks for reaching out — happy to connect.",
    "sender": {
      "name":        "Jordan Lee",
      "profile_url": "https://www.linkedin.com/in/jordanlee",
      "provider_id": "urn:li:member:987654321"
    },
    "attachments": [],
    "occurred_at": "2026-05-28T14:23:10.000Z"
  },
  "delivered_at": "2026-05-28T14:23:11.456Z"
}

`message.read`

Fired when a message in the conversation is read. The payload carries the standard messaging data shape. Reader identity is included where available from the platform.

{
  "id":          "wdl_YOUR_DELIVERY_ID",
  "webhook_id":  "wh_YOUR_WEBHOOK_ID",
  "event":       "message.read",
  "data": {
    "account_id":  "acc_YOUR_ACCOUNT_ID",
    "chat_id":     "chat_YOUR_CHAT_ID",
    "message_id":  "msg_YOUR_MESSAGE_ID",
    "text":        "Hello, I saw your profile and wanted to connect.",
    "sender": {
      "name":        "Alex Jordan",
      "profile_url": "https://www.linkedin.com/in/alexjordan",
      "provider_id": "urn:li:member:123456789"
    },
    "attachments": [],
    "occurred_at": "2026-05-28T14:25:00.000Z"
  },
  "delivered_at": "2026-05-28T14:25:01.012Z"
}

`message.reaction`

Fired when a reaction is added to a message in the conversation.

{
  "id":          "wdl_YOUR_DELIVERY_ID",
  "webhook_id":  "wh_YOUR_WEBHOOK_ID",
  "event":       "message.reaction",
  "data": {
    "account_id":  "acc_YOUR_ACCOUNT_ID",
    "chat_id":     "chat_YOUR_CHAT_ID",
    "message_id":  "msg_YOUR_MESSAGE_ID",
    "text":        "Thanks for reaching out — happy to connect.",
    "reaction":    "👍",
    "sender": {
      "name":        "Alex Jordan",
      "profile_url": "https://www.linkedin.com/in/alexjordan",
      "provider_id": "urn:li:member:123456789"
    },
    "attachments": [],
    "occurred_at": "2026-05-28T14:26:30.000Z"
  },
  "delivered_at": "2026-05-28T14:26:31.234Z"
}

Notable fields

reaction — the reaction value added to the message (e.g. an emoji string).

`message.edited`

Fired when a message is edited after it was sent. The text field carries the post-edit content.

{
  "id":          "wdl_YOUR_DELIVERY_ID",
  "webhook_id":  "wh_YOUR_WEBHOOK_ID",
  "event":       "message.edited",
  "data": {
    "account_id":  "acc_YOUR_ACCOUNT_ID",
    "chat_id":     "chat_YOUR_CHAT_ID",
    "message_id":  "msg_YOUR_MESSAGE_ID",
    "text":        "Thanks for reaching out — let's schedule a call.",
    "sender": {
      "name":        "Jordan Lee",
      "profile_url": "https://www.linkedin.com/in/jordanlee",
      "provider_id": "urn:li:member:987654321"
    },
    "attachments": [],
    "occurred_at": "2026-05-28T14:27:45.000Z"
  },
  "delivered_at": "2026-05-28T14:27:46.789Z"
}

Notable fields

text — the post-edit content. The original message text is not included.

`message.deleted`

Fired when a message is deleted from the conversation. The text field may be absent when the platform does not include the deleted content.

{
  "id":          "wdl_YOUR_DELIVERY_ID",
  "webhook_id":  "wh_YOUR_WEBHOOK_ID",
  "event":       "message.deleted",
  "data": {
    "account_id":  "acc_YOUR_ACCOUNT_ID",
    "chat_id":     "chat_YOUR_CHAT_ID",
    "message_id":  "msg_YOUR_MESSAGE_ID",
    "sender": {
      "name":        "Jordan Lee",
      "profile_url": "https://www.linkedin.com/in/jordanlee",
      "provider_id": "urn:li:member:987654321"
    },
    "attachments": [],
    "occurred_at": "2026-05-28T14:28:00.000Z"
  },
  "delivered_at": "2026-05-28T14:28:01.345Z"
}

Notable fields

text — may be absent on deletion; do not depend on it being present when handling this event.

`chat.updated`

Fired when a chat's container state changed — for example the thread was archived, muted, or its read-state changed. Useful for inbox automation that mirrors thread state. This event is about a chat thread, not a single message.

Opt-in event

chat.updated is not in the messaging default set. Name it explicitly in the events array when creating or updating the webhook to receive it.

{
  "id":          "wdl_YOUR_DELIVERY_ID",
  "webhook_id":  "wh_YOUR_WEBHOOK_ID",
  "event":       "chat.updated",
  "data": {
    "account_id":  "acc_YOUR_ACCOUNT_ID",
    "chat_id":     "chat_YOUR_CHAT_ID",
    "occurred_at": "2026-05-28T14:30:00.000Z"
  },
  "delivered_at": "2026-05-28T14:30:01.000Z"
}

Notable fields

account_id and chat_id are always present — chat_id identifies the thread whose container state changed. The delivery carries these identifying fields; use them to look up the current thread state on your side.

`chat.deleted`

Fired when a chat thread was deleted — actionable for inbox agents that mirror thread state.

Opt-in event

chat.deleted is not in the messaging default set. Name it explicitly in the events array to receive it.

{
  "id":          "wdl_YOUR_DELIVERY_ID",
  "webhook_id":  "wh_YOUR_WEBHOOK_ID",
  "event":       "chat.deleted",
  "data": {
    "account_id":  "acc_YOUR_ACCOUNT_ID",
    "chat_id":     "chat_YOUR_CHAT_ID",
    "occurred_at": "2026-05-28T14:31:00.000Z"
  },
  "delivered_at": "2026-05-28T14:31:01.000Z"
}

Notable fields

account_id and chat_id are always present — chat_id identifies the deleted thread.

Field remapping

When creating a messaging-source webhook you can include a data array to control which fields appear in the delivered data object and under which names. The full set of 27 keys available for the messaging source:

account_id        account_type      account_info
chat_id           timestamp         webhook_name
message_id        message           mentions
reaction          reaction_sender   read_by
sender            is_sender         attendees
attachments       subject           provider_chat_id
provider_message_id  is_event       chat_pinned
quoted            is_forwarded      chat_content_type
message_type      is_group          folder

When data is omitted the default payload shape documented above is delivered. Use is_sender (computed from account_info.user_id == sender.provider_id) to distinguish messages the account sent from those it received without a separate lookup.

Data	Why
Account identity (name, email, sign-in method)	Create and secure your account
Your LinkedIn credentials	Operate the actions you request
LinkedIn content returned by an API call	Fulfil that specific request, nothing more
API keys and connector (OAuth) authorizations	Authenticate your API, CLI, MCP, or SDK requests
Billing details	Charge you correctly and meet our tax obligations
Usage and security logs	Keep the service reliable and abuse-free
Support messages	Respond to you
Website analytics, only if you opt in	Understand how the site is used

Data	Retention
Account and workspace data	While your account is active
Closed account	Recoverable for 7 days, then deleted on day 8
LinkedIn credentials	Until you disconnect that account
LinkedIn content	Not stored; any transient cache clears within 1 hour, never indexed, never used for training
API keys	Until you revoke or rotate them
Connector (OAuth) authorizations	Access token ~1 hour; refresh token up to ~12 months, or until you revoke it, whichever comes first
Billing records	As required by German tax law, currently up to 10 years
Logs	A short operational window; metadata only, never message content

Name	Purpose	Expiry
`cc_cookie`	Remembers your cookie choice	12 months
`curviate-theme`	Remembers light/dark mode (local storage, not a cookie)	Persistent
`sb-*-auth-token`	Keeps you signed in	While active; cleared on sign-out

Name	Purpose	Expiry
`_ga`	Google Analytics: distinguishes visitors	2 years
`_gid`	Google Analytics: distinguishes visitors	24 hours
`_ga_<container id>`	Google Analytics: persists session state	2 years

Quick reference

message.received

message.delivered

message.read

message.reaction

message.edited

message.deleted

chat.updated

chat.deleted

Field remapping

`message.received`

`message.delivered`

`message.read`

`message.reaction`

`message.edited`

`message.deleted`

`chat.updated`

`chat.deleted`