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

Лиды

Лид: участие одного контакта в одной кампании. Если один человек есть в двух кампаниях, это два лида с разными id.

Маршруты

#Объект Lead

Лид: участие одного контакта в одной кампании. Один и тот же человек в двух кампаниях дает два разных лида.

Поля

  • objectstring
    Тип объекта, всегда lead.
  • idstring (uuid)
    Идентификатор лида (участия в кампании).
  • workspace_idstring (uuid)
    Пространство кампании.
  • campaign_idstring (uuid)
    Кампания, в которой участвует контакт.
  • usernamestring или null
    Ник Telegram без @. Может быть null. Не уникален: используйте fields.record_id для связи с CRM.
  • statusstring
    Статус лида в кампании. Значения: new contacted completed replied blocked failed suspended deleted opted_out unknown
  • external_idnull
    Зарезервировано для следующих версий. В v1 всегда null.
  • 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: valid, missing, conflict или unknown. Значения: valid missing conflict unknown
  • first_contact_accountobject или null
    Аккаунт, который отправил первое сообщение. null, если неизвестно.
    Вложенные поля
    • idstring (uuid)
      Идентификатор аккаунта.
    • usernamestring или null
      Ник аккаунта без @. Может быть null.
    • namestring или null
      Отображаемое имя аккаунта. Может быть null.
  • first_message_sent_atstring (date-time) или null
    Когда отправлено первое сообщение. null, если отправка не подтверждена.
  • first_reply_atstring (date-time) или null
    Когда пришел первый ответ. null, если ответа не было.
  • delivery_statestring
    Состояние доставки ближайшего или последнего сообщения цепочки. Значения: waiting_queue queued held sent failed unknown
  • automation_statestring
    Состояние автоматической цепочки для этого лида. У лидов без запланированного сообщения, например ответивших, сейчас часто unknown. Значения: running paused held stopped completed unknown
  • reasonobject
    Почему цепочка ждет, если это известно.
    Вложенные поля
    • reason_codestring
      Код причины. Значения: none schedule_window daily_limit queue_pending telegram_wait account_unavailable account_restricted campaign_paused subscription_inactive manual_hold automation_stopped service_unavailable unknown
    • reason_observed_atstring (date-time) или null
      Когда причина была зафиксирована. null, если неизвестно.
    • next_attempt_atstring (date-time) или null
      Когда ожидается следующая попытка. null, если срок неизвестен.
    • requires_customer_actionboolean или null
      Нужны ли действия в кабинете, чтобы отправка продолжилась. null, если неизвестно.
  • created_atstring (date-time)
    Когда контакт добавлен в кампанию.
  • observed_atstring (date-time)
    Время чтения данных сервером.
Lead
{
  "object": "lead",
  "id": "5a7c3e92-1f4b-4d68-9c2e-7b0a6d4f8e31",
  "workspace_id": "3f6a9d21-8b4c-4e7f-a102-5c9e8d7b6a43",
  "campaign_id": "4d8b2f73-6e1a-4c95-b7d0-8a3f5e2c9b14",
  "username": "example_user",
  "status": "replied",
  "external_id": null,
  "fields": {
    "record_id": "crm-10482",
    "first_name": "Анна",
    "company": "ООО Пример",
    "position": "Руководитель отдела продаж",
    "utm_source": "partner"
  },
  "fields_truncated": false,
  "record_id_status": "valid",
  "first_contact_account": {
    "id": "1d9f6b28-4c3e-4a75-8b19-5e7a2c0f6d83",
    "username": "example_sender",
    "name": "Мария из Примера"
  },
  "first_message_sent_at": "2026-10-26T07:30:00.000Z",
  "first_reply_at": "2026-10-26T09:12:00.000Z",
  "delivery_state": "sent",
  "automation_state": "unknown",
  "reason": {
    "reason_code": "none",
    "reason_observed_at": null,
    "next_attempt_at": null,
    "requires_customer_action": null
  },
  "created_at": "2026-10-25T14:00:00.000Z",
  "observed_at": "2026-10-27T09:15:42.000Z"
}

#Список лидов

GET/v1/leads

Лиды (участия контактов в кампаниях) в охвате ключа, от старых к новым по created_at.

Право
leads:read
Вес запроса
2

Параметры

  • limitinteger, в строке запросанеобязательный
    Сколько объектов вернуть на странице. От 1 до 100. По умолчанию 50.
  • cursorstring, в строке запросанеобязательный
    Значение next_cursor из предыдущего ответа. Остальные фильтры должны совпадать с первым запросом.
  • workspace_idstring (uuid), в строке запросанеобязательный
    Только объекты этого пространства.
  • campaign_idstring (uuid), в строке запросанеобязательный
    Только объекты этой кампании.
  • usernamestring, в строке запросанеобязательный
    Точный ник Telegram. Знак @ в начале и регистр не важны.
  • statusstring, в строке запросанеобязательный
    Только лиды с этим статусом. Значения: new contacted completed replied blocked failed suspended deleted opted_out unknown
  • delivery_statestring, в строке запросанеобязательный
    Только лиды с этим состоянием доставки. Значения waiting_queue и failed сейчас не выдаются, фильтр по ним вернет пустой список. Значения: waiting_queue queued held sent failed unknown

Ответ

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

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

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

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

Запрос
curl -G https://api.melioralab.io/v1/leads \
  -H "Authorization: Bearer $MELIORA_API_KEY" \
  -d campaign_id=4d8b2f73-6e1a-4c95-b7d0-8a3f5e2c9b14 \
  -d limit=50
Ответ
{
  "object": "list",
  "data": [
    {
      "object": "lead",
      "id": "5a7c3e92-1f4b-4d68-9c2e-7b0a6d4f8e31",
      "workspace_id": "3f6a9d21-8b4c-4e7f-a102-5c9e8d7b6a43",
      "campaign_id": "4d8b2f73-6e1a-4c95-b7d0-8a3f5e2c9b14",
      "username": "example_user",
      "status": "replied",
      "external_id": null,
      "fields": {
        "record_id": "crm-10482",
        "first_name": "Анна",
        "company": "ООО Пример",
        "position": "Руководитель отдела продаж",
        "utm_source": "partner"
      },
      "fields_truncated": false,
      "record_id_status": "valid",
      "first_contact_account": {
        "id": "1d9f6b28-4c3e-4a75-8b19-5e7a2c0f6d83",
        "username": "example_sender",
        "name": "Мария из Примера"
      },
      "first_message_sent_at": "2026-10-26T07:30:00.000Z",
      "first_reply_at": "2026-10-26T09:12:00.000Z",
      "delivery_state": "sent",
      "automation_state": "unknown",
      "reason": {
        "reason_code": "none",
        "reason_observed_at": null,
        "next_attempt_at": null,
        "requires_customer_action": null
      },
      "created_at": "2026-10-25T14:00:00.000Z",
      "observed_at": "2026-10-27T09:15:42.000Z"
    },
    {
      "object": "lead",
      "id": "8c1e5a37-9d2f-4b74-a6e8-2f9b3c7d5a40",
      "workspace_id": "3f6a9d21-8b4c-4e7f-a102-5c9e8d7b6a43",
      "campaign_id": "4d8b2f73-6e1a-4c95-b7d0-8a3f5e2c9b14",
      "username": "sample_contact",
      "status": "contacted",
      "external_id": null,
      "fields": {
        "record_id": null,
        "first_name": "Игорь"
      },
      "fields_truncated": false,
      "record_id_status": "missing",
      "first_contact_account": {
        "id": "1d9f6b28-4c3e-4a75-8b19-5e7a2c0f6d83",
        "username": "example_sender",
        "name": "Мария из Примера"
      },
      "first_message_sent_at": "2026-10-26T07:42:00.000Z",
      "first_reply_at": null,
      "delivery_state": "queued",
      "automation_state": "running",
      "reason": {
        "reason_code": "queue_pending",
        "reason_observed_at": "2026-10-27T08:58:10.000Z",
        "next_attempt_at": "2026-10-27T10:00:00.000Z",
        "requires_customer_action": false
      },
      "created_at": "2026-10-25T14:00:01.000Z",
      "observed_at": "2026-10-27T09:15:42.000Z"
    }
  ],
  "has_more": true,
  "next_cursor": "v1.k1.Qm9hcmRfMWZ4.c3RyaWN0bHlfb3BhcXVl.dGFnX2V4YW1wbGU.bWFjX2V4YW1wbGVfdmFsdWU"
}

#Получить лида

GET/v1/leads/{id}

Один лид по идентификатору. Лид вне охвата ключа дает 404.

Право
leads:read
Вес запроса
1

Параметры

  • idstring (uuid), в путиобязательный
    Идентификатор лида.

Ответ

Объект Lead.

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

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

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

Запрос
curl https://api.melioralab.io/v1/leads/5a7c3e92-1f4b-4d68-9c2e-7b0a6d4f8e31 \
  -H "Authorization: Bearer $MELIORA_API_KEY"
Ответ
{
  "object": "lead",
  "id": "5a7c3e92-1f4b-4d68-9c2e-7b0a6d4f8e31",
  "workspace_id": "3f6a9d21-8b4c-4e7f-a102-5c9e8d7b6a43",
  "campaign_id": "4d8b2f73-6e1a-4c95-b7d0-8a3f5e2c9b14",
  "username": "example_user",
  "status": "replied",
  "external_id": null,
  "fields": {
    "record_id": "crm-10482",
    "first_name": "Анна",
    "company": "ООО Пример",
    "position": "Руководитель отдела продаж",
    "utm_source": "partner"
  },
  "fields_truncated": false,
  "record_id_status": "valid",
  "first_contact_account": {
    "id": "1d9f6b28-4c3e-4a75-8b19-5e7a2c0f6d83",
    "username": "example_sender",
    "name": "Мария из Примера"
  },
  "first_message_sent_at": "2026-10-26T07:30:00.000Z",
  "first_reply_at": "2026-10-26T09:12:00.000Z",
  "delivery_state": "sent",
  "automation_state": "unknown",
  "reason": {
    "reason_code": "none",
    "reason_observed_at": null,
    "next_attempt_at": null,
    "requires_customer_action": null
  },
  "created_at": "2026-10-25T14:00:00.000Z",
  "observed_at": "2026-10-27T09:15:42.000Z"
}