Events

#The lead.first_message_sent event

A first message was sent to the lead. data.first_message is present only with include_text=true.

Attributes

• objectstring
  Object type, always event.
• idstring
  Event ID: evt_ followed by 32 hexadecimal characters. The deduplication key. Format ^evt_[a-f0-9]{32}$.
• api_versionstring
  Event format version. Always "2026-10-18".
• timestampstring (date-time)
  When the fact occurred.
• testboolean
  Always false.
• typestring
  Event type. Always "lead.first_message_sent".
• dataobject
  Event data.
  Child attributes

  • organization_idstring (uuid)
    Organization where the event occurred.
  • workspaceobject
    Workspace at the time of the event.
    Child attributes

    • idstring (uuid)
      ID.
    • namestring or null
      Name. Can be null.
  • campaignobject or null
    Campaign at the time of the event. Can be null.
    Child attributes

    • idstring (uuid)
      ID.
    • namestring or null
      Name. Can be null.
  • leadobject
    Lead snapshot.
    Child attributes

    • idstring (uuid)
      Lead ID.
    • usernamestring or null
      Telegram username without @. Can be null.
    • statusstring
      Lead status at the time of the event. Values: new contacted completed replied blocked failed suspended deleted opted_out unknown
    • fieldsobject
      Contact record fields at the time of the event.
      Child attributes

      • record_idstring or nullmay be absent
        Record ID in an external CRM, passed when the contacts were uploaded. null if record_id_status is not valid. Up to 128 characters.
      • first_namestring or nullmay be absent
        First name. Up to 1024 characters.
      • last_namestring or nullmay be absent
        Last name. Up to 1024 characters.
      • companystring or nullmay be absent
        Company. Up to 1024 characters.
      • positionstring or nullmay be absent
        Job title. Up to 1024 characters.
      • websitestring or nullmay be absent
        Website. Up to 1024 characters.
      • sourcestring or nullmay be absent
        Contact source. Up to 1024 characters.
      • utm_sourcestring or nullmay be absent
        The utm_source tag. Up to 1024 characters.
      • utm_mediumstring or nullmay be absent
        The utm_medium tag. Up to 1024 characters.
      • utm_campaignstring or nullmay be absent
        The utm_campaign tag. Up to 1024 characters.
    • fields_truncatedboolean
      true if some values were shortened.
    • record_id_statusstring
      Reliability of fields.record_id. In v1 events return unknown, and fields.record_id is null: get record_id from GET /v1/leads/{id} using data.lead.id. Values: valid missing conflict unknown
  • accountobject or null
    Account that handled the conversation. null if unknown.
    Child attributes

    • idstring (uuid)
      Account ID.
    • usernamestring or null
      Account username without @. Can be null.
    • namestring or null
      Account display name. Can be null.
  • first_message_sent_atstring (date-time) or null
    When the first message was sent. null if sending is not confirmed; this is common for reply events.
  • first_messageobjectmay be absent
    First message text. Only with include_text=true.
    Child attributes

    • textstring or null
      Saved text, up to 4000 characters. null if the text is unavailable. Up to 4000 characters.
    • text_truncatedboolean or null
      true: the text is shortened; false: the text is complete; null: completeness is unknown.
    • text_unavailableboolean
      true if the text is not returned.
    • text_unavailable_reasonstring or null
      Reason the text is unavailable, or null. Values: not_saved ownership_unproven source_conflict purged

#The lead.replied event

The lead replied. Sent for every counted reply, so one lead can have several. Text fields in data.reply are present only with include_text=true.

Attributes

• objectstring
  Object type, always event.
• idstring
  Event ID: evt_ followed by 32 hexadecimal characters. The deduplication key. Format ^evt_[a-f0-9]{32}$.
• api_versionstring
  Event format version. Always "2026-10-18".
• timestampstring (date-time)
  When the fact occurred.
• testboolean
  Always false.
• typestring
  Event type. Always "lead.replied".
• dataobject
  Event data.
  Child attributes

  • organization_idstring (uuid)
    Organization where the event occurred.
  • workspaceobject
    Workspace at the time of the event.
    Child attributes

    • idstring (uuid)
      ID.
    • namestring or null
      Name. Can be null.
  • campaignobject or null
    Campaign at the time of the event. Can be null.
    Child attributes

    • idstring (uuid)
      ID.
    • namestring or null
      Name. Can be null.
  • leadobject
    Lead snapshot.
    Child attributes

    • idstring (uuid)
      Lead ID.
    • usernamestring or null
      Telegram username without @. Can be null.
    • statusstring
      Lead status at the time of the event. Values: new contacted completed replied blocked failed suspended deleted opted_out unknown
    • fieldsobject
      Contact record fields at the time of the event.
      Child attributes

      • record_idstring or nullmay be absent
        Record ID in an external CRM, passed when the contacts were uploaded. null if record_id_status is not valid. Up to 128 characters.
      • first_namestring or nullmay be absent
        First name. Up to 1024 characters.
      • last_namestring or nullmay be absent
        Last name. Up to 1024 characters.
      • companystring or nullmay be absent
        Company. Up to 1024 characters.
      • positionstring or nullmay be absent
        Job title. Up to 1024 characters.
      • websitestring or nullmay be absent
        Website. Up to 1024 characters.
      • sourcestring or nullmay be absent
        Contact source. Up to 1024 characters.
      • utm_sourcestring or nullmay be absent
        The utm_source tag. Up to 1024 characters.
      • utm_mediumstring or nullmay be absent
        The utm_medium tag. Up to 1024 characters.
      • utm_campaignstring or nullmay be absent
        The utm_campaign tag. Up to 1024 characters.
    • fields_truncatedboolean
      true if some values were shortened.
    • record_id_statusstring
      Reliability of fields.record_id. In v1 events return unknown, and fields.record_id is null: get record_id from GET /v1/leads/{id} using data.lead.id. Values: valid missing conflict unknown
  • accountobject or null
    Account that handled the conversation. null if unknown.
    Child attributes

    • idstring (uuid)
      Account ID.
    • usernamestring or null
      Account username without @. Can be null.
    • namestring or null
      Account display name. Can be null.
  • first_message_sent_atstring (date-time) or null
    When the first message was sent. null if sending is not confirmed; this is common for reply events.
  • replyobject
    Lead reply.
    Child attributes

    • idstring (uuid)
      Reply ID.
    • replied_atstring (date-time)
      When the reply arrived.
    • automation_stoppedboolean or null
      Whether the sequence stopped after the reply. null if the stop is not confirmed. Currently always null.
    • is_first_replybooleanmay be absent
      Whether this is the lead's first reply in the campaign. Not sent at the moment.
    • textstring or nullmay be absent
      Reply text. Only with include_text=true. Up to 4000 characters.
    • text_truncatedboolean or nullmay be absent
      Whether the text is shortened. Only with include_text=true.
    • text_unavailablebooleanmay be absent
      Whether the text is unavailable. Only with include_text=true.
    • text_unavailable_reasonstring or nullmay be absent
      Reason the text is unavailable. Only with include_text=true. Values: not_saved ownership_unproven source_conflict purged

#List events

GET/v1/events

Events in the order they occur: the first message to a lead and the lead's reply. Poll the feed with the cursor. next_cursor is always present, even on an empty page. With include_text=true the request weight is 3.

Permission

events:read

Request weight

2 (3 with include_text=true)

Parameters

• limitinteger, queryoptional
  Number of objects to return per page. From 1 to 200. Defaults to 50.
• cursorstring, queryoptional
  The next_cursor value from the previous response. Other filters must match the first request.
• workspace_idstring (uuid), queryoptional
  Only objects in this workspace.
• campaign_idstring (uuid), queryoptional
  Only objects in this campaign.
• typestring, queryoptional
  Only events of this type. Values: lead.first_message_sent lead.replied
• include_textstring, queryoptional
  Include message texts in events. Requires the messages:read permission and "Message text" enabled on the key. Values: true false Defaults to false.
• startstring, queryoptional
  now: start the feed from the current moment. Returns an empty page and a cursor. Cannot be combined with cursor. Values: now

Response

A list: object, data (an array of Event objects), has_more, next_cursor, meta. See Pagination.

The meta field

• available_fromstring (date-time) or null
  Earliest time for which the feed has events. null if unknown.
• retention_daysstring
  Number of days the feed retains events. Always 30.
• collectionobject
  Status of saved conversation collection for the API.
  Child attributes

  • statestring
    running: collection is active; paused: paused in Meliora; preparing: preparing after being enabled; degraded: data may be incomplete. Values: running paused preparing degraded
  • enabled_atstring (date-time) or null
    When collection was enabled. null if it has not been enabled yet.
  • pause_pendingboolean
    A pause or resume was requested in Meliora but has not been applied yet.
• coverageobject
  Event feed completeness.
  Child attributes

  • statusstring
    complete, partial or unknown. Values: complete partial unknown
  • gapsarray of object
    Up to 50 intervals of possible incompleteness. Up to 50 items.
    Child attributes

    • idstring (uuid)
      Interval ID.
    • fromstring (date-time)
      Start of the interval.
    • tostring (date-time) or null
      End of the interval. null if the interval is not closed yet.
    • statestring
      open, recovering, recovered, unrecoverable or unknown. Values: open recovering recovered unrecoverable unknown
  • gaps_truncatedboolean
    true if there are more than 50 intervals.
  • incomplete_fromstring (date-time) or null
    Earliest boundary of the hidden incomplete intervals. null if there are none.
• observed_atstring (date-time)
  Time the server read the data.

Endpoint-specific errors

• cursor_mismatch: The cursor is corrupted, was issued for a different route or filters, or the key's permissions and scope have changed.
• scope_required: The key does not have permission for this read. Texts also require "Message text" to be enabled.
• not_found: The object was not found or is outside the key's scope. An unknown path also returns 404.
• cursor_expired: The cursor expired: 15 minutes for lists, 30 days for the event feed.

Common errors are described in Errors.