Рецепт: синхронизация контактов с CRM

Обновлено: 11 ноября 2026 · 9 мин чтения

Шаги

1. 1

   Что Вы получите

   • Контакт Clomni каждого клиента в CRM: имя, телефон, e-mail, пользовательские поля.
   • Контакт, созданный или изменённый в Clomni, за несколько секунд попадает в CRM.
   • Данные, изменённые в CRM (например, уровень клиента), записываются в Clomni, и оператор видит их в диалоге.
   • При желании история диалогов клиента в CRM.
2. 2

   Нужные scope

   • contacts:read (средний риск): чтение контактов и вебхуки contact.*.
   • contacts:write (средний риск): запись из CRM в Clomni. Если данные идут только из Clomni в CRM, не запрашивайте его.
   • custom_attributes:read (низкий риск): список пользовательских полей.
   • conversations:read и messages:read (средний риск): только если CRM показывает историю диалогов.

   При создании приложения можно выбрать готовый набор «Синхронизация с CRM» и убрать лишнее. contacts:write даёт и contacts:read, но чтобы выбрать тему вебхука, должен быть одобрен именно contacts:read. Приложение и токен: Создание приложения на developer.clomni.ai: пошагово, Токены и аутентификация в Developer API.

3. 3

   1. Один раз загрузите все контакты

   GET /v1/sync/contacts возвращает контакты в порядке (updated_at, id), начиная с самого старого изменения. limit от 1 до 100. Для следующей страницы передайте next_cursor из ответа в параметре after. Когда has_more равно false, Вы получили всё.

   curl "https://api.clomni.ai/v1/sync/contacts?limit=100" \
     -H "Authorization: Bearer clomni_pat_xxx"

   {
     "data": [
       {
         "id": 981,
         "name": "Leyla Hasanova",
         "email": "[email protected]",
         "phone_number": "+994501234567",
         "identifier": "crm-10422",
         "custom_attributes": { "customer_tier": "gold" },
         "created_at": "2026-07-25T11:02:00.000Z",
         "updated_at": "2026-11-08T09:14:03.120Z"
       }
     ],
     "next_cursor": "MjAyNi0xMS0wOFQwOToxNDowM1p8OTgx",
     "has_more": true
   }

   Не пытайтесь расшифровать или собрать next_cursor сами, передавайте его как есть.

4. 4

   2. Затем забирайте только изменения

   После первой загрузки сохраните самое большое значение updated_at. В следующий раз получите то, что изменилось после него, через updated_since:

   curl "https://api.clomni.ai/v1/sync/contacts?updated_since=2026-11-08T09:12:00Z&limit=100" \
     -H "Authorization: Bearer clomni_pat_xxx"

   • Отступите от сохранённого времени на 1-2 минуты, чтобы не потерять записи, сделанные в ту же секунду.
   • Записывайте контакты по id (upsert): если контакт пришёл дважды, новая копия заменяет старую.
   • Пока has_more равно true, продолжайте через after и не меняйте updated_since.
   • Новое время сохраняйте только после того, как все страницы успешно записаны.

   Для endpoint синхронизации лимит 60 запросов в минуту на токен. Запускать раз в несколько минут достаточно.

5. 5

   3. Получайте изменения сразу

   На портале разработчика в разделе приложения «Вебхуки» укажите свой HTTPS-адрес и выберите темы contact.created и contact.updated. В событии приходит полный объект контакта. Вебхук может прийти дважды и в любом порядке: проверяйте updated_at и отбрасывайте старое событие, если запись в CRM новее. Шаг 2 оставьте на случай сбоя вебхуков, например раз в час. Настройка и проверка подписи: Вебхуки приложения и события: настройка, темы, проверка подписи.

6. 6

   4. Пишите из CRM в Clomni

   Записывайте ID из CRM в поле контакта identifier: оно уникально в пределах workspace. Сначала проверьте, есть ли контакт в Clomni (поиск идёт по имени, e-mail, телефону и identifier):

   curl "https://api.clomni.ai/v1/contacts/search?q=crm-10422" \
     -H "Authorization: Bearer clomni_pat_xxx"

   Если нет, создайте:

   curl -X POST "https://api.clomni.ai/v1/contacts" \
     -H "Authorization: Bearer clomni_pat_xxx" \
     -H "Content-Type: application/json" \
     -d '{"name": "Leyla Hasanova", "email": "[email protected]", "phone_number": "+994501234567", "identifier": "crm-10422", "custom_attributes": {"customer_tier": "gold"}}'

   Если есть, обновите. PATCH меняет только переданные поля, custom_attributes объединяются с прежними значениями:

   curl -X PATCH "https://api.clomni.ai/v1/contacts/981" \
     -H "Authorization: Bearer clomni_pat_xxx" \
     -H "Content-Type: application/json" \
     -d '{"custom_attributes": {"customer_tier": "platinum"}}'

   Телефон должен быть в международном формате: с + и кодом страны, без пробелов. Второй контакт с тем же e-mail или телефоном вернёт 422.

7. 7

   5. Сопоставьте пользовательские поля

   Ключи custom_attributes должны быть заранее заведены в workspace. Список:

   curl "https://api.clomni.ai/v1/custom_attribute_definitions?attribute_model=contact_attribute" \
     -H "Authorization: Bearer clomni_pat_xxx"

   Один раз сопоставьте поля CRM с этими ключами. Незаведённый ключ в панели не отображается. Новый ключ создайте в панели или через API (custom_attributes:write).

8. 8

   6. Не попадите в бесконечный цикл

   При двусторонней синхронизации Ваше собственное изменение возвращается к Вам вебхуком. Если снова записать его в CRM, получится цикл. При записи в Clomni сохраняйте updated_at из ответа и отбрасывайте событие с тем же updated_at. Или храните хеш синхронизируемых полей и ничего не делайте, если он не изменился.

9. 9

   Частые ошибки

   • updated_since сохраняется без перекрытия, и контакты, изменённые в ту же секунду, теряются. Отступайте на 1-2 минуты.
   • Между страницами меняется updated_since. Листайте страницы только через after.
   • Контакт создаётся без проверки, и приходит 422. Сначала ищите, потом обновляйте.
   • Телефон записан как 0501234567, без кода страны.
   • В custom_attributes пишется ключ, которого нет в workspace, и он не виден в панели.
   • Одобрен contacts:write, но не contacts:read, поэтому вебхук contact.* не выбирается.
   • После 429 запрос сразу повторяется. Подождите столько секунд, сколько указано в Retry-After.
   • Путаются форматы времени: endpoint синхронизации возвращают ISO 8601 (UTC), старые списки возвращают секунды Unix.

   Все endpoint контактов: Scope и endpoint: контакты, метки, пользовательские поля, готовые ответы.