Примеры Webhook для обновлений контакта и заметок

Полный каталог на основе схемы см. в разделе все примеры.

Что это такое

Обработка событий contact.attributes_changed и contact.note.updated.

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

Создайте общедоступную конечную точку HTTPS в вашем приложении.
Настройте конечную точку Webhook в YCloud для необходимых типов событий.
Обеспечьте безопасное хранение секрета подписи конечной точки.
Сделайте обработку событий идемпотентной.

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

YCloud отправляет HTTP-запрос POST при возникновении события. Проверьте подпись, надежно сохраните событие, верните ответ 2xx и обработайте длительные задачи асинхронно.

Запрос

Приведенные ниже сценарии демонстрируют запросы, доставляемые на ваш URL Webhook. Используйте поле события id как идентификатор доставки, а type — для маршрутизации полезной нагрузки.

Ответ

Верните статус 2xx после успешного принятия события.

HTTP/1.1 200 OK

Информацию о настройке конечной точки, проверке подписи и механизме повторных попыток см. в разделе Настройка Webhook.

Происходит при изменении атрибутов контакта. Полезная нагрузка Webhook содержит информацию об измененных атрибутах, включая их старые и новые значения.

Пример изменения тегов (добавление тегов)

Запрос

{
  "id": "evt_1234567892",
  "type": "contact.attributes_changed",
  "apiVersion": "v2",
  "createTime": "2024-01-01T12:00:00.000Z",
  "contactAttributesChanged": {
    "id": "1824266594102064128",
    "updateTime": "2024-01-01T12:00:00.000Z",
    "changedAttributes": {
      "tags": {
        "oldValue": ["premium", "newsletter"],
        "newValue": ["premium", "newsletter", "vip"],
        "extra": [
          {
            "action": "ADDED",
            "id": "686dd294334be8606a5bf312",
            "value": "vip"
          }
        ]
      }
    }
  }
}

Ответ

Подтвердите доставку после надежного принятия события.

HTTP/1.1 200 OK

Пояснение

Выполняйте маршрутизацию события по type, дедупликацию — по id, а длительные или подверженные сбоям задачи передавайте асинхронному обработчику.

Пример изменения тегов (удаление тегов)

Запрос

{
  "id": "evt_1234567893",
  "type": "contact.attributes_changed",
  "apiVersion": "v2",
  "createTime": "2024-01-01T12:00:00.000Z",
  "contactAttributesChanged": {
    "id": "1824266594102064128",
    "updateTime": "2024-01-01T12:00:00.000Z",
    "changedAttributes": {
      "tags": {
        "oldValue": ["premium", "newsletter", "vip"],
        "newValue": ["premium", "newsletter"],
        "extra": [
          {
            "action": "REMOVED",
            "id": "686dd294334be8606a5bf312",
            "value": "vip"
          }
        ]
      }
    }
  }
}

Ответ

Подтвердите доставку после надежного принятия события.

HTTP/1.1 200 OK

Пояснение

Пример изменения

Запрос

{
  "id": "evt_1234567900",
  "type": "contact.attributes_changed",
  "apiVersion": "v2",
  "createTime": "2024-01-01T12:00:00.000Z",
  "contactAttributesChanged": {
    "id": "1824266594102064128",
    "updateTime": "2024-01-01T12:00:00.000Z",
    "changedAttributes": {
      "waba_id": {
        "oldValue": "waba_old_123456",
        "newValue": "waba_new_789012",
        "extra": [
          {
            "action": "CHANGED"
          }
        ]
      }
    }
  }
}

Ответ

Подтвердите доставку после надежного принятия события.

HTTP/1.1 200 OK

Пояснение

Корректная структура: объект contactAttributesChanged содержит три обязательных поля: id, updateTime и changedAttributes.
Измененные атрибуты: поле changedAttributes представляет собой объект, где каждый ключ — это имя атрибута, а значение — объект ContactAttributeChange.
Конфигурация свойств события: при включении событий contact.attributes_changed необходимо настроить поле eventProperties в вашей конечной точке Webhook, чтобы указать, какие атрибуты должны быть включены в полезную нагрузку Webhook.
Типы атрибутов: поля oldValue и newValue могут содержать различные типы данных:
- String: текстовые значения
- Number: числовые значения (целые или десятичные)
- Boolean: логические значения (true/false)
- Array: массивы строк
- Object: сложные объекты с вложенными свойствами
- Null: когда атрибут удален или сброшен
Изменения тегов: для атрибутов тегов поле extra предоставляет подробную информацию о том, какие теги были добавлены или удалены, включая их идентификаторы и значения.
Значения Null: когда атрибут удален или установлен в null, newValue будет null. Когда атрибут добавляется впервые, oldValue может быть null.
Пользовательские атрибуты: пользовательские атрибуты включаются в объект changedAttributes так же, как и стандартные атрибуты, где их пользовательские ключи выступают в качестве имен атрибутов.
Определение изменений: в объект changedAttributes включаются только те атрибуты, которые действительно изменились.
Дополнительное поле: поле extra является необязательным и используется преимущественно для изменений, связанных с тегами, предоставляя дополнительный контекст о выполненных действиях.

Заметка контакта обновлена

Используйте contact.note.updated, когда обновляется заметка контакта.

Запрос

{
  "id": "evt_2234567890abcdef12345678",
  "type": "contact.note.updated",
  "apiVersion": "v2",
  "createTime": "2024-01-02T12:00:00.000Z",
  "contactNote": {
    "id": "6a3de646e18f344f743aaa4d",
    "contactId": "1824266594102064128",
    "username": "alice_01",
    "phoneNumber": "+16315551111",
    "content": "Customer now prefers afternoon follow-up.",
    "createTime": "2024-01-01T12:00:00.000Z",
    "updateTime": "2024-01-02T12:00:00.000Z"
  }
}

Ответ

Подтвердите доставку после надежного принятия события.

HTTP/1.1 200 OK

Пояснение

Используйте contactNote.id для идентификации заметки и contactId для идентификации связанного с ней контакта. Поля username и phoneNumber описывают контакт и могут иметь значение null. Полезная нагрузка содержит моментальный снимок заметки для клиента, включая content, без внутренних идентификаторов оператора.

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

Руководства

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

Webhooks

Примеры Webhook для обновлений контакта и заметок

Что это такое

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

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

Запрос

Ответ

Пример изменения тегов (добавление тегов)

Запрос

Ответ

Пояснение

Пример изменения тегов (удаление тегов)

Запрос

Ответ

Пояснение

Пример изменения

Запрос

Ответ

Пояснение

Заметка контакта обновлена

Запрос

Ответ

Пояснение

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

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

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

​Запрос

​Ответ

​Пример изменения тегов (добавление тегов)

​Запрос

​Ответ

​Пояснение

​Пример изменения тегов (удаление тегов)

​Запрос

​Ответ

​Пояснение

​Пример изменения

​Запрос

​Ответ

​Пояснение

​Заметка контакта обновлена

​Запрос

​Ответ

​Пояснение

Что это такое

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

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

Запрос

Ответ

Пример изменения тегов (добавление тегов)

Запрос

Ответ

Пояснение

Пример изменения тегов (удаление тегов)

Запрос

Ответ

Пояснение

Пример изменения

Запрос

Ответ

Пояснение

Заметка контакта обновлена

Запрос

Ответ

Пояснение