support.conversation.opened

This fires once per member, per channel, ever. It is a "new contact" signal, not a "new question" signal. For every question a member asks, listen to support.message.received.

When this fires

A member sends your project bot a message it does not recognise as a command, an access code, or an answer the bot was waiting for — and they have no conversation on that channel yet. Subscriby creates the conversation and emits this event, immediately followed by support.message.received for the message itself.

The message can be text, a photo, a document, a voice note or any other supported media. A bare photo with no caption opens a conversation just as text does.

It does not fire when:

The member already has a conversation on that channel, even a resolved one. A resolved thread reopens and raises support.conversation.reopened instead.
The message was a recognised bot command, or an answer the bot was waiting for during a guided setup step.
The member is blocked, or has tripped the inbound rate limit.
Support is switched off for the project.

Required ability

support-conversation:view — token must carry this at mint time to subscribe an endpoint to this event.

Payload

{
  "id": "evt_01HX...",
  "type": "support.conversation.opened",
  "created_at": "2026-08-20T10:05:00Z",
  "api_version": "2026-05-01",
  "project_id": "prj_01HX...",
  "data": {
    "conversation_id": "sup_01HX...",
    "project_id": "prj_01HX...",
    "subscriber_id": "usr_01HX...",
    "channel": "telegram"
  }
}

Field reference

Field	Type	Notes
`id`	string ULID	Unique event id, prefixed `evt_`. Use for idempotent processing.
`type`	string	Always `support.conversation.opened` for this event.
`created_at`	ISO 8601 timestamp	Server-side emission time.
`api_version`	string	Webhook API contract version.
`project_id`	string ULID	Project this event belongs to.
`data.conversation_id`	string ULID	The new conversation. Use it against the support API to read the message.
`data.project_id`	string ULID	Mirrors the envelope `project_id`.
`data.subscriber_id`	string ULID	The member's project-scoped user id.
`data.channel`	string	Transport the conversation lives on. `telegram` today.

Caveats

The payload carries no message body and no member name. Fetch them with GET /v1/support/conversations/{conversation_id}/messages.
The member may be a lead rather than a subscriber. Anyone who can reach the bot can open a conversation, including someone who has never paid — data.subscriber_id resolves to a project user whose status may be lead.
Opening a conversation is not the same as the creator being notified. Notification is throttled to one Telegram DM per conversation per five minutes, so a burst of messages produces one ping but many events.

support.message.received — fires alongside this event, for the message itself.
support.conversation.reopened — the returning-member counterpart.
Support events overview — back to family overview.