MelioraAPI EN
Ранний доступ. Ключи выдаются по запросу. Как получить ключ

События

Лента событий: первое сообщение лиду и ответ лида. Читайте ее по курсору, чтобы узнавать об изменениях без обхода всех лидов.

Маршруты

#Событие lead.first_message_sent

Лиду отправлено первое сообщение. data.first_message есть только при include_text=true.

Поля

  • objectstring
    Тип объекта, всегда event.
  • idstring
    Идентификатор события: evt_ и 32 шестнадцатеричных знака. Ключ дедупликации. Формат ^evt_[a-f0-9]{32}$.
  • api_versionstring
    Версия формата события. Всегда "2026-10-18".
  • timestampstring (date-time)
    Когда произошел факт.
  • testboolean
    Всегда false.
  • typestring
    Тип события. Всегда "lead.first_message_sent".
  • dataobject
    Данные события.
    Вложенные поля
    • organization_idstring (uuid)
      Организация, в которой произошло событие.
    • workspaceobject
      Пространство на момент события.
      Вложенные поля
      • idstring (uuid)
        Идентификатор.
      • namestring или null
        Название. Может быть null.
    • campaignobject или null
      Кампания на момент события. Может быть null.
      Вложенные поля
      • idstring (uuid)
        Идентификатор.
      • namestring или null
        Название. Может быть null.
    • leadobject
      Снимок лида.
      Вложенные поля
      • idstring (uuid)
        Идентификатор лида.
      • usernamestring или null
        Ник Telegram без @. Может быть null.
      • statusstring
        Статус лида на момент события. Значения: new contacted completed replied blocked failed suspended deleted opted_out unknown
      • fieldsobject
        Поля карточки на момент события.
        Вложенные поля
        • record_idstring или nullможет отсутствовать
          Идентификатор записи во внешней CRM, переданный при загрузке контактов. null, если record_id_status не valid. До 128 знаков.
        • first_namestring или nullможет отсутствовать
          Имя. До 1024 знаков.
        • last_namestring или nullможет отсутствовать
          Фамилия. До 1024 знаков.
        • companystring или nullможет отсутствовать
          Компания. До 1024 знаков.
        • positionstring или nullможет отсутствовать
          Должность. До 1024 знаков.
        • websitestring или nullможет отсутствовать
          Сайт. До 1024 знаков.
        • sourcestring или nullможет отсутствовать
          Источник контакта. До 1024 знаков.
        • utm_sourcestring или nullможет отсутствовать
          Метка utm_source. До 1024 знаков.
        • utm_mediumstring или nullможет отсутствовать
          Метка utm_medium. До 1024 знаков.
        • utm_campaignstring или nullможет отсутствовать
          Метка utm_campaign. До 1024 знаков.
      • fields_truncatedboolean
        true, если часть значений сокращена.
      • record_id_statusstring
        Надежность fields.record_id. В v1 у событий приходит unknown, а fields.record_id равен null: берите record_id из GET /v1/leads/{id} по data.lead.id. Значения: valid missing conflict unknown
    • accountobject или null
      Аккаунт, который вел переписку. null, если неизвестно.
      Вложенные поля
      • idstring (uuid)
        Идентификатор аккаунта.
      • usernamestring или null
        Ник аккаунта без @. Может быть null.
      • namestring или null
        Отображаемое имя аккаунта. Может быть null.
    • first_message_sent_atstring (date-time) или null
      Когда отправлено первое сообщение. null, если отправка не подтверждена; у события ответа это частый случай.
    • first_messageobjectможет отсутствовать
      Текст первого сообщения. Только при include_text=true.
      Вложенные поля
      • textstring или null
        Сохраненный текст, до 4000 знаков. null, если текст недоступен. До 4000 знаков.
      • text_truncatedboolean или null
        true: текст сокращен; false: текст полный; null: полнота неизвестна.
      • text_unavailableboolean
        true, если текст не выдается.
      • text_unavailable_reasonstring или null
        Причина недоступности текста или null. Значения: not_saved ownership_unproven source_conflict purged
lead.first_message_sent
{
  "object": "event",
  "id": "evt_3b9e2c7a1f4d4e8a9b6c0d2e5f7a8c91",
  "type": "lead.first_message_sent",
  "api_version": "2026-10-18",
  "timestamp": "2026-10-26T07:30:00.000Z",
  "test": false,
  "data": {
    "organization_id": "2c8f4a61-7d3e-4b9a-8f21-6a0d5e9c3b17",
    "workspace": {
      "id": "3f6a9d21-8b4c-4e7f-a102-5c9e8d7b6a43",
      "name": "Основное пространство"
    },
    "campaign": {
      "id": "4d8b2f73-6e1a-4c95-b7d0-8a3f5e2c9b14",
      "name": "Пример кампании"
    },
    "lead": {
      "id": "5a7c3e92-1f4b-4d68-9c2e-7b0a6d4f8e31",
      "username": "example_user",
      "status": "contacted",
      "fields": {
        "record_id": null,
        "first_name": "Анна",
        "company": "ООО Пример"
      },
      "fields_truncated": false,
      "record_id_status": "unknown"
    },
    "account": {
      "id": "1d9f6b28-4c3e-4a75-8b19-5e7a2c0f6d83",
      "username": "example_sender",
      "name": "Мария из Примера"
    },
    "first_message_sent_at": "2026-10-26T07:30:00.000Z"
  }
}

#Событие lead.replied

Лид ответил. Приходит на каждый засчитанный ответ, у одного лида их может быть несколько. Поля текста в data.reply есть только при include_text=true.

Поля

  • objectstring
    Тип объекта, всегда event.
  • idstring
    Идентификатор события: evt_ и 32 шестнадцатеричных знака. Ключ дедупликации. Формат ^evt_[a-f0-9]{32}$.
  • api_versionstring
    Версия формата события. Всегда "2026-10-18".
  • timestampstring (date-time)
    Когда произошел факт.
  • testboolean
    Всегда false.
  • typestring
    Тип события. Всегда "lead.replied".
  • dataobject
    Данные события.
    Вложенные поля
    • organization_idstring (uuid)
      Организация, в которой произошло событие.
    • workspaceobject
      Пространство на момент события.
      Вложенные поля
      • idstring (uuid)
        Идентификатор.
      • namestring или null
        Название. Может быть null.
    • campaignobject или null
      Кампания на момент события. Может быть null.
      Вложенные поля
      • idstring (uuid)
        Идентификатор.
      • namestring или null
        Название. Может быть null.
    • leadobject
      Снимок лида.
      Вложенные поля
      • idstring (uuid)
        Идентификатор лида.
      • usernamestring или null
        Ник Telegram без @. Может быть null.
      • statusstring
        Статус лида на момент события. Значения: new contacted completed replied blocked failed suspended deleted opted_out unknown
      • fieldsobject
        Поля карточки на момент события.
        Вложенные поля
        • record_idstring или nullможет отсутствовать
          Идентификатор записи во внешней CRM, переданный при загрузке контактов. null, если record_id_status не valid. До 128 знаков.
        • first_namestring или nullможет отсутствовать
          Имя. До 1024 знаков.
        • last_namestring или nullможет отсутствовать
          Фамилия. До 1024 знаков.
        • companystring или nullможет отсутствовать
          Компания. До 1024 знаков.
        • positionstring или nullможет отсутствовать
          Должность. До 1024 знаков.
        • websitestring или nullможет отсутствовать
          Сайт. До 1024 знаков.
        • sourcestring или nullможет отсутствовать
          Источник контакта. До 1024 знаков.
        • utm_sourcestring или nullможет отсутствовать
          Метка utm_source. До 1024 знаков.
        • utm_mediumstring или nullможет отсутствовать
          Метка utm_medium. До 1024 знаков.
        • utm_campaignstring или nullможет отсутствовать
          Метка utm_campaign. До 1024 знаков.
      • fields_truncatedboolean
        true, если часть значений сокращена.
      • record_id_statusstring
        Надежность fields.record_id. В v1 у событий приходит unknown, а fields.record_id равен null: берите record_id из GET /v1/leads/{id} по data.lead.id. Значения: valid missing conflict unknown
    • accountobject или null
      Аккаунт, который вел переписку. null, если неизвестно.
      Вложенные поля
      • idstring (uuid)
        Идентификатор аккаунта.
      • usernamestring или null
        Ник аккаунта без @. Может быть null.
      • namestring или null
        Отображаемое имя аккаунта. Может быть null.
    • first_message_sent_atstring (date-time) или null
      Когда отправлено первое сообщение. null, если отправка не подтверждена; у события ответа это частый случай.
    • replyobject
      Ответ лида.
      Вложенные поля
      • idstring (uuid)
        Идентификатор ответа.
      • replied_atstring (date-time)
        Когда пришел ответ.
      • automation_stoppedboolean или null
        Остановлена ли цепочка после ответа. null, если остановка не подтверждена. Сейчас всегда null.
      • is_first_replybooleanможет отсутствовать
        Первый ли это ответ лида в кампании. Сейчас не передается.
      • textstring или nullможет отсутствовать
        Текст ответа. Только при include_text=true. До 4000 знаков.
      • text_truncatedboolean или nullможет отсутствовать
        Признак сокращения текста. Только при include_text=true.
      • text_unavailablebooleanможет отсутствовать
        Текст недоступен. Только при include_text=true.
      • text_unavailable_reasonstring или nullможет отсутствовать
        Причина недоступности текста. Только при include_text=true. Значения: not_saved ownership_unproven source_conflict purged
lead.replied
{
  "object": "event",
  "id": "evt_8d4f1a6c2e9b4c7d8a3e5f0b1c6d9e27",
  "type": "lead.replied",
  "api_version": "2026-10-18",
  "timestamp": "2026-10-26T09:12:00.000Z",
  "test": false,
  "data": {
    "organization_id": "2c8f4a61-7d3e-4b9a-8f21-6a0d5e9c3b17",
    "workspace": {
      "id": "3f6a9d21-8b4c-4e7f-a102-5c9e8d7b6a43",
      "name": "Основное пространство"
    },
    "campaign": {
      "id": "4d8b2f73-6e1a-4c95-b7d0-8a3f5e2c9b14",
      "name": "Пример кампании"
    },
    "lead": {
      "id": "5a7c3e92-1f4b-4d68-9c2e-7b0a6d4f8e31",
      "username": "example_user",
      "status": "replied",
      "fields": {
        "record_id": null,
        "first_name": "Анна",
        "company": "ООО Пример"
      },
      "fields_truncated": false,
      "record_id_status": "unknown"
    },
    "account": {
      "id": "1d9f6b28-4c3e-4a75-8b19-5e7a2c0f6d83",
      "username": "example_sender",
      "name": "Мария из Примера"
    },
    "first_message_sent_at": null,
    "reply": {
      "id": "e4b7a2d9-6c1f-4e38-9a5b-0d8c3f7e1a62",
      "replied_at": "2026-10-26T09:12:00.000Z",
      "automation_stopped": null
    }
  }
}

#Лента событий

GET/v1/events

События в порядке появления: первое сообщение лиду и ответ лида. Опрашивайте ленту по курсору. next_cursor есть всегда, даже у пустой страницы. С include_text=true вес запроса 3.

Право
events:read
Вес запроса
2 (3 с include_text=true)

Параметры

  • limitinteger, в строке запросанеобязательный
    Сколько объектов вернуть на странице. От 1 до 200. По умолчанию 50.
  • cursorstring, в строке запросанеобязательный
    Значение next_cursor из предыдущего ответа. Остальные фильтры должны совпадать с первым запросом.
  • workspace_idstring (uuid), в строке запросанеобязательный
    Только объекты этого пространства.
  • campaign_idstring (uuid), в строке запросанеобязательный
    Только объекты этой кампании.
  • typestring, в строке запросанеобязательный
    Только события этого типа. Значения: lead.first_message_sent lead.replied
  • include_textstring, в строке запросанеобязательный
    Добавить тексты сообщений в события. Нужны право messages:read и включенный «Текст сообщений» у ключа. Значения: true false По умолчанию false.
  • startstring, в строке запросанеобязательный
    now: начать ленту с текущего момента. Возвращает пустую страницу и курсор. Нельзя вместе с cursor. Значения: now

Ответ

Список: object, data (массив объектов Event), has_more, next_cursor, meta. Подробнее в руководстве Пагинация.

Поле meta

  • available_fromstring (date-time) или null
    С какого момента в ленте есть события. null, если неизвестно.
  • retention_daysstring
    Сколько суток лента хранит события. Всегда 30.
  • collectionobject
    Состояние сбора сохраненной переписки для API.
    Вложенные поля
    • statestring
      running: сбор идет; paused: приостановлен в кабинете; preparing: готовится после включения; degraded: данные могут быть неполными. Значения: running paused preparing degraded
    • enabled_atstring (date-time) или null
      Когда сбор был включен. null, если еще не включен.
    • pause_pendingboolean
      Пауза или возобновление запрошены в кабинете, но еще не применены.
  • coverageobject
    Полнота ленты событий.
    Вложенные поля
    • statusstring
      complete, partial или unknown. Значения: complete partial unknown
    • gapsarray of object
      До 50 интервалов возможной неполноты. До 50 элементов.
      Вложенные поля
      • idstring (uuid)
        Идентификатор интервала.
      • fromstring (date-time)
        Начало интервала.
      • tostring (date-time) или null
        Конец интервала. null, если интервал еще не закрыт.
      • statestring
        open, recovering, recovered, unrecoverable или unknown. Значения: open recovering recovered unrecoverable unknown
    • gaps_truncatedboolean
      true, если интервалов больше 50.
    • incomplete_fromstring (date-time) или null
      Самая ранняя граница скрытых неполных интервалов. null, если таких нет.
  • observed_atstring (date-time)
    Время чтения данных сервером.

Особые ошибки

  • cursor_mismatch: Курсор поврежден, выдан для другого маршрута или фильтров, либо права и охват ключа изменились.
  • scope_required: Ключ не имеет права на это чтение. Для текстов нужен также включенный «Текст сообщений».
  • not_found: Объект не найден или находится вне охвата ключа. Неизвестный путь тоже дает 404.
  • cursor_expired: Срок курсора истек: 15 минут для списков, 30 суток для ленты событий.

Общие ошибки описаны в руководстве Ошибки.

Запрос
curl -G https://api.melioralab.io/v1/events \
  -H "Authorization: Bearer $MELIORA_API_KEY" \
  -d limit=100
Ответ
{
  "object": "list",
  "data": [
    {
      "object": "event",
      "id": "evt_3b9e2c7a1f4d4e8a9b6c0d2e5f7a8c91",
      "type": "lead.first_message_sent",
      "api_version": "2026-10-18",
      "timestamp": "2026-10-26T07:30:00.000Z",
      "test": false,
      "data": {
        "organization_id": "2c8f4a61-7d3e-4b9a-8f21-6a0d5e9c3b17",
        "workspace": {
          "id": "3f6a9d21-8b4c-4e7f-a102-5c9e8d7b6a43",
          "name": "Основное пространство"
        },
        "campaign": {
          "id": "4d8b2f73-6e1a-4c95-b7d0-8a3f5e2c9b14",
          "name": "Пример кампании"
        },
        "lead": {
          "id": "5a7c3e92-1f4b-4d68-9c2e-7b0a6d4f8e31",
          "username": "example_user",
          "status": "contacted",
          "fields": {
            "record_id": null,
            "first_name": "Анна",
            "company": "ООО Пример"
          },
          "fields_truncated": false,
          "record_id_status": "unknown"
        },
        "account": {
          "id": "1d9f6b28-4c3e-4a75-8b19-5e7a2c0f6d83",
          "username": "example_sender",
          "name": "Мария из Примера"
        },
        "first_message_sent_at": "2026-10-26T07:30:00.000Z"
      }
    },
    {
      "object": "event",
      "id": "evt_8d4f1a6c2e9b4c7d8a3e5f0b1c6d9e27",
      "type": "lead.replied",
      "api_version": "2026-10-18",
      "timestamp": "2026-10-26T09:12:00.000Z",
      "test": false,
      "data": {
        "organization_id": "2c8f4a61-7d3e-4b9a-8f21-6a0d5e9c3b17",
        "workspace": {
          "id": "3f6a9d21-8b4c-4e7f-a102-5c9e8d7b6a43",
          "name": "Основное пространство"
        },
        "campaign": {
          "id": "4d8b2f73-6e1a-4c95-b7d0-8a3f5e2c9b14",
          "name": "Пример кампании"
        },
        "lead": {
          "id": "5a7c3e92-1f4b-4d68-9c2e-7b0a6d4f8e31",
          "username": "example_user",
          "status": "replied",
          "fields": {
            "record_id": null,
            "first_name": "Анна",
            "company": "ООО Пример"
          },
          "fields_truncated": false,
          "record_id_status": "unknown"
        },
        "account": {
          "id": "1d9f6b28-4c3e-4a75-8b19-5e7a2c0f6d83",
          "username": "example_sender",
          "name": "Мария из Примера"
        },
        "first_message_sent_at": null,
        "reply": {
          "id": "e4b7a2d9-6c1f-4e38-9a5b-0d8c3f7e1a62",
          "replied_at": "2026-10-26T09:12:00.000Z",
          "automation_stopped": null
        }
      }
    }
  ],
  "has_more": false,
  "next_cursor": "v1.k1.Qm9hcmRfMWZ4.c3RyaWN0bHlfb3BhcXVl.dGFnX2V4YW1wbGU.bWFjX2V4YW1wbGVfdmFsdWU",
  "meta": {
    "available_from": "2026-10-20T08:00:00.000Z",
    "retention_days": 30,
    "collection": {
      "state": "running",
      "enabled_at": "2026-10-20T08:00:00.000Z",
      "pause_pending": false
    },
    "coverage": {
      "status": "unknown",
      "gaps": [],
      "gaps_truncated": false,
      "incomplete_from": null
    },
    "observed_at": "2026-10-27T09:15:42.000Z"
  }
}