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

Получить пользователей (лидов). Пользователь считается лидом, если у него определено хотя бы одно из: имя, email, телефон, User ID, подписка на web-push или с ним был хотя бы один диалог.

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

URL

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

Аргументы

Этот метод следует общим правилам. Аргументы передаются как GET или POST параметры.

Аргумент Описание
auth_token Обязательный. Токен авторизации (нужен scope: users-list)
filters Фильтры. Формат фильтров. По умолчанию: все пользователи
sort_prop Свойство, по которому будет отсортирован список. По умолчанию: $last_seen (последняя активность)
sort_order Порядок сортировки (asc — по возрастанию, desc — по убыванию). По умолчанию: desc
offset Пагинция. Смещение от начала (по умолчанию: 0)
limit Пагинация. Максимальное количество пользователей, которые будут возвращены (от 0 до 50, по умолчанию: 20)

Замечания

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

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

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

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

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

Ответ

{
  "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",
        }
      },
      ...
    ]
  }
}

Ответ будет содержать массив с пользователями.

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

Поле users содержит массив пользователей. Формат здесь немного отличается от обычного объекта User.

Каждый пользователь содержит поля id (ID пользователя), presence (статус) и props (свойства).

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

Примеры

curl -X GET 'https://api.carrotquest.io/v1/apps/$self_app/users?auth_token=XXX'