Отслеживание пользовательских событий

Что это такое

Пользовательские события (Custom Events) представляют активность из вашего приложения, веб-сайта, магазина или бэкенд-системы. Определите схему события один раз, а затем отправляйте факты его возникновения, которые можно использовать в клиентских сценариях YCloud.

Перед началом работы

Выберите постоянное имя события, которое не будет меняться при изменении отображаемого текста.
Определите контакт, связанный с каждым событием.
Определите свойства события и их типы данных.
Решите, какая системная временная метка обозначает время совершения действия.

Как это работает

Создайте определение события.
Добавляйте или обновляйте определения свойств по мере развития схемы.
Отправляйте факты возникновения событий, используя точное имя определения.
Связывайте каждое событие с ID контакта, номером телефона или именем пользователя Meta.
Отслеживайте отклоненные события и несоответствия схеме.

Определения событий являются контрактами. Изменение метки или описания безопаснее, чем изменение смысла существующего имени или свойства.

Запрос

Создание определения события

POST /event/definitions

curl --request POST https://api.ycloud.com/v2/event/definitions \
  --header "X-API-Key: $YCLOUD_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "order_completed",
    "label": "Order completed",
    "description": "A customer completed an order.",
    "objectType": "CONTACT",
    "properties": [
      {
        "name": "order_value",
        "label": "Order value",
        "type": "NUMBER"
      }
    ]
  }'

Выбор идентификатора контакта

Для события, заданного с objectType: CONTACT, укажите один из следующих идентификаторов:

Поле	Как YCloud идентифицирует контакт
`objectId`	Использует числовой ID существующего контакта в вашем аккаунте. Если контакт не существует, запрос завершается ошибкой.
`contactPhoneNumber`	Выполняет поиск номера телефона в формате E.164 в вашем аккаунте и создает контакт, если совпадений не найдено.
`contactUsername`	Находит соответствие по сохраненному имени пользователя Meta существующего контакта в вашем аккаунте. Если совпадений нет, запрос завершается ошибкой без создания контакта.

Для каждого события используется только один идентификатор. Если указано несколько идентификаторов, числовой objectId имеет приоритет, затем следует непустой contactPhoneNumber, а затем contactUsername. Если числовой ID контакта не найден, YCloud отклоняет запрос без проверки номера телефона или имени пользователя. Используйте имя пользователя Meta, сохраненное в контакте, без начального символа @. contactUsername — это поле верхнего уровня запроса, отдельное от properties. Добавлять его в определения свойств события не требуется.

Отправка события по номеру телефона

POST /event/events

curl --request POST https://api.ycloud.com/v2/event/events \
  --header "X-API-Key: $YCLOUD_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "eventName": "order_completed",
    "occurTime": "2026-07-16T12:00:00.000Z",
    "contactPhoneNumber": "+16315551111",
    "properties": {
      "order_value": 99.9
    }
  }'

Отправка события по имени пользователя

Если вам известно имя пользователя контакта в Meta, вы можете отправить то же самое событие без номера телефона или ID контакта. В этом примере customer_demo уже должен быть сохранен у контакта в вашем аккаунте.

curl --request POST https://api.ycloud.com/v2/event/events \
  --header "X-API-Key: $YCLOUD_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "eventName": "order_completed",
    "occurTime": "2026-07-16T12:00:00.000Z",
    "contactUsername": "customer_demo",
    "properties": {
      "order_value": 99.9
    }
  }'

Ответ

При создании определения возвращается сохраненное определение.

{
  "name": "order_completed",
  "label": "Order completed",
  "objectType": "CONTACT",
  "properties": [
    {
      "name": "order_value",
      "label": "Order value",
      "type": "NUMBER"
    }
  ]
}

Успешно принятое событие возвращает HTTP 200 с пустым объектом JSON.

HTTP/1.1 200 OK
Content-Type: application/json

{}

Развитие схемы

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

Ограничения и устранение неполадок

Определение события должно существовать до отправки факта его возникновения.
Имена и значения свойств должны соответствовать определению.
Используйте RFC 3339 для occurTime.
Убедитесь, что идентификатор контакта сопоставляется с нужным клиентом в вашем аккаунте.
Для contactUsername проверьте, что контакт уже существует, и что имя пользователя совпадает с сохраненным значением без начального @.
Опускайте идентификаторы, которые YCloud не должен использовать. Переданный номер телефона имеет приоритет перед именем пользователя.
Ответ 200 подтверждает принятие, но не гарантирует завершение работы последующих процессов автоматизации.

Создать определение события

Просмотреть схемы определений и свойств.

Отправить событие

Просмотреть контракт запроса на отправку события.

Начало работы

Руководства

Конечные точки

Webhooks

Отслеживание пользовательских событий

Что это такое

Перед началом работы

Как это работает

Запрос

Создание определения события

Выбор идентификатора контакта

Отправка события по номеру телефона

Отправка события по имени пользователя

Ответ

Развитие схемы

Ограничения и устранение неполадок

Создать определение события

Отправить событие

​Что это такое

​Перед началом работы

​Как это работает

​Запрос

​Создание определения события

​Выбор идентификатора контакта

​Отправка события по номеру телефона

​Отправка события по имени пользователя

​Ответ

​Развитие схемы

​Ограничения и устранение неполадок

Создать определение события

Отправить событие

Что это такое

Перед началом работы

Как это работает

Запрос

Создание определения события

Выбор идентификатора контакта

Отправка события по номеру телефона

Отправка события по имени пользователя

Ответ

Развитие схемы

Ограничения и устранение неполадок