Установить свойства пользователя

Устанавливает (создает, обновляет, удаляет) свойства пользователя. В одном запросе можно установить не более 250 свойств.

URL

POST https://api.carrotquest.io/users/{id}/props

В качестве {id} можно использовать:

ID из нашей системы
Ваш User ID (укажите параметр by_user_id=true). Если пользователя с таким идентификатором не существует, он будет создан автоматически.

Параметры

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

Параметр	Тип	Описание
`by_user_id`	Optional[boolean]	Если вы делаете выборку не по ID из Carrot quest, а по своему User ID, этот параметр должен иметь значение `true`. По умолчанию: `false`
`operations`	Array[Dict]	Массив атомарных операций, которые будут проведены над свойствами пользователя. Формат свойств
`double_subscribe`	Optional[boolean]	Позволяет переподписать отписанного пользователя, если операция обновляет свойство `$email`. По умолчанию: `false`
`parse_custom_props_type`	Optional[boolean]	Если флаг установлен в `true`, то система автоматически определит тип устанавливаемых кастомных свойств. По умолчанию: `true`
`source`	Optional[Dict]	Задает источник установки контакта при записи свойств `$email` и `$phone`.
`app`	Optional[ID]	ID приложения, делающего запрос. По умолчанию определяется на основе токена доступа.

Замечания

Подробнее об операциях над свойствами и их форматом можно почитать здесь.

Операции выполняются в порядке их задания в массиве operations. Допустимо последовательное выполнение операций над одним свойством.

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

Поскольку метод позволяет осуществлять много операций над свойствами одним запросом, некоторые из них могут быть корректны, а некоторые - нет. Например, может быть задан неверный тип для системного свойства. Чтобы сохранить максимум информации, которую вы записываете, запрос не будет возвращать ошибку, когда операции невалидны и выполнит все валидные операции. Вместо этого, в поле meta будет возвращено:

affected_props: List[строка] - список обновленных свойств
not_changed_props: List[строка] - список свойств, которые не изменили своего значения
ignored_operations: List[Dict] - список словарей с операциями, которые были проигнорированы. Словари содержат операцию, а также дополнительное поле reason, поясняющее ошибку.

По умолчанию при передаче значений кастомных свойств в запросе, их тип будет определен системой автоматически. Например, если задать в качестве значения строку "12345", в свойство будет записано число 12345, а не строка. В некоторых случаях, это поведение нежелательно (например, при записи "длинных" чисел, которые неверно интерпретируются бразуером). Чтобы избежать автоматического распознания, установите параметр parse_custom_props_type=false.

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

Если пользователь отписался от Email-рассылок (имеет статус Отписан в карточке пользователя), а затем снова оставил тот же Email на вашем сайте, то его статус не изменится при записи свойства этим методом и Email-ы ему не будут приходить. Это может привести к ситуации, когда пользователь отписался, пришел через какое-то время уже не помня, что отписался и повторно оставил Email, считая, что письма ему будут приходить. Чтобы повторно переподписать такого пользователя при обновлении Email-а, установите параметр double_subscribe=true.

Параметр source является системным и служит для идентификации источника контактов - поп-апа, бота и других. Источник помогает нам определять статистику по собранным контактам в ботах и автосообщениях Это словарь, который обязательно содержит поле "type" - тип источника и опционально - поле "id", идентифицирующего конкретное сообщение. Пример: {"type": "popup_small", "id": 123}

Ответ

Поле data будет содержать id обновленного пользователя.
Поле meta помимо стандартных полей будет содержать:

affected_props: List[строка] - список обновленных свойств
not_changed_props: List[строка] - список свойств, которые не изменили своего значения
ignored_operations: List[Dict] - список словарей с операциями, которые были проигнорированы. Словари содержат операцию, а также дополнительное поле reason, поясняющее ошибку.

{
  "meta": {
    "status": 200,
    "affected_props": [],
    "ignored_operations": []
  },
  "data": {
    "id": 123123123,
    "app": 12345
  }
}

Ошибки

Стандартные ошибки Web API.

Примеры

Записать имя "Maks" у пользователя с CarrotquestId=8173131 (ID из нашей системы):

curl -X POST \
  --data-urlencode "operations=[{"op": "update_or_create", "key": "$name", "value": "Maks"}]" \
  -H "Authorization: Token XXX" \
  https://api.carrotquest.io/users/8173131/props

Записать имя "Maks" у пользователя с UserId=user-7216 (ID из вашей системы):

curl -X POST \
  --data-urlencode "operations=[{"op": "update_or_create", "key": "$name", "value": "Maks"}]" \
  --data-urlencode "by_user_id=true" \
  -H "Authorization: Token XXX" \
  https://api.carrotquest.io/users/user-7216/props

Записать свойство my-prop со значением Hello и увеличить значение свойства projects на 3 у пользователя с UserId=user-7216 (ID из вашей системы):

curl -X POST \
  --data-urlencode 'operations=[{"op": "update_or_create", "key": "my-prop", "value": "Hello"},{"op": "add", "key": "projects", "value": "3"}]' \
  --data-urlencode 'by_user_id=true' \
  -H "Authorization: Token XXX" \
  "https://api.carrotquest.io/users/user-7216/props"