Получить пользователей

Получить пользователей (лидов). Пользователь считается лидом, если у него выполняется хотя бы одно из условий:

• Определено имя (свойство пользователя $name)
• Определен email (свойство пользователя $email),
• Определен телефон (свойство пользователя $phone)
• Определен User ID
• Есть подписка на web-push
• Был хотя бы один диалог

Мы используем этот метод на странице "База лидов".

URL

GET https://api.carrotquest.io/apps/{id}/users

Аргументы

Параметры аутентификации.
Параметр id_as_string.

Параметр	Тип	Описание
filters	Объект фильтров	По умолчанию: все пользователи.
sort_prop	Optional[Строка]	Свойство, по которому будет отсортирован список перед пагинацией. По умолчанию: $last_seen (последняя активность)
sort_order	Optional[asc/desc]	Порядок сортировки (asc — по возрастанию, desc — по убыванию). По умолчанию: desc
offset	Optional[integer]	Пагинция. Смещение от начала (по умолчанию: 0)
limit	Optional[integer]	Пагинация. Максимальное количество пользователей, которые будут возвращены (от 1 до 50, по умолчанию: 20)
convert_props_types	Optional[boolean]	По умолчанию true. Если флаг не установлен (false), свойства пользователя возвращаются как строки.

Note: опциональные поля объекта User для этого метода включить нельзя.

Замечания

По умолчанию возвращаются все пользователи (без фильтров). Для поиска нужных следует использовать поле filters. Например, чтобы получить только пользователей из заданного сегмента, например, тех, кто заходил за последний день, найти пользователей по имени, email и т.д.

Данные, возвращаемые этим методом, обновляются с задержкой в несколько минут. Поэтому они могут отличаться от данных, находящихся в карточке пользователя (если они не успели обновиться).

Пагинация в этом методе немного отличается от пагинации в других методах. Вместо обычных paginate_position и paginate_count здесь используются другие параметры: offset и limit. При получении большого количества пользователей через пагинацию возможна ситуация, когда в верх списка добавляются новые пользователи. Поэтому возможно, что один и тот же пользователь окажется в нескольких последовательных запросах.

Например, если при первом запросе задано offset=0, limit=20, при втором — offset=20, limit=20 и между вызовами вверху был добавлен один новый пользователь, то двадцатый пользователь при первом вызове будет первым во втором вызове. Чтобы исключать дубли, вам нужно проверять ID на своей стороне. Другой вариант — использовать экспорт пользователей в административной панели, чтобы получить большое количество пользователей за раз (при экспорте эту проблему мы решим за вас).

Этим методом нельзя выбрать более 10000 лидов. Это техническое ограничение. Попытка указать offset + limit больше 10000 приведет к ошибке. Чтобы выгружать большое количество пользователей используйте экспорт пользователей в административной панели.

Если возвращенных пользователей меньше чем limit, значит все пользователи получены. Например, если при лимите 20 получено 5 пользователей, значит все пользователи получены.

Ответ

Ответ в поле data содержит словарь из 2 элементов:

• Поле total содержит общее количество пользователей, удовлетворяющих заданным фильтрам.
• Поле users содержит массив объектов, описывающих пользователей. Формат объекта здесь отличается от обычного объекта User. Объект содержит:
• id (ID пользователя)
• presence (статус)
• props (свойства). Свойства пользователя возвращаются как единый словарь без разделения на системные, кастомные и свойства событий.

Подробнее о свойствах пользователя и о статусах пользователя.

Note: поскольку способ пагинации отличается от стандартного, поле meta не будет содержать данных пагинации.

{
  "meta": {
    "status": 200
  },
  "data": {
    "total": 245,
    "users": [
      {
        "id": 3568,
        "presence": "offline",
        "props": {
          "$event_18_first": "2014-06-15T22:14:08",
          "$event_18_last": "2014-06-23T07:50:46",
          "$event_18_count": 4,
          "$last_contacted": "2016-02-12T15:33:31",
          "$email": "maks@gmail.com",
          "$sessions": 1,
          "$last_seen": "2014-06-17T08:56:03",
        }
      },
      ...
    ]
  }
}

Примеры

curl -X GET -H "Authorization: Token XXX" "https://api.carrotquest.io/apps/$self_app/users"