Перейти к содержимому
🔌 API
v2

Контакты

Контакты в API Radist.Online: поиск по имени и телефону, создание и изменение карточки клиента, теги, заметки, чаты контакта и связанные сделки CRM.

Общее

Swagger: https://api.radist.online/v2/docs#/Contacts

Необходимые права доступа (scopes) для работы с API: messaging

Контакт — карточка клиента в компании: имя, телефоны, email, теги, заметки и привязанные чаты. У одного контакта может быть несколько чатов в разных мессенджерах.

Контакты появляются двумя способами: автоматически — когда создаётся чат (правила привязки описаны в разделе Чаты), и вручную — методом создания контакта.

Удалить контакт через API нельзя.

Список контактов

ContactsListContacts (GET /companies/{company_id}/contacts/)

Параметры запроса:

  • offset, limit — постраничный вывод, limit от 1 до 100 (по умолчанию 100).
  • order_by — сортировка: id:asc (по умолчанию), id:desc, name:asc, name:desc, created_at:asc, created_at:desc. Сортировка по имени регистронезависимая.
  • tags — вернуть только контакты, у которых есть хотя бы один из перечисленных тегов (до 32 идентификаторов).
  • with_groups — включать ли контакты групповых чатов. По умолчанию false, такие контакты скрыты.
  • query — нечёткий поиск по имени, email и телефонам контакта. Ищет по отдельным словам, поэтому находит контакт и по части имени. Телефон приводится к цифрам, так что +7 900 123-45-67, 89001234567 и 1234567 найдут один и тот же номер. Взаимоисключающий с phone.
  • phone — поиск по точному номеру в формате E.164, например +18001234567. Взаимоисключающий с query.

В ответе count — сколько контактов вернулось в этом запросе, total_count — сколько их всего по заданным фильтрам.

У этого метода отдельное ограничение — 1 запрос в секунду (см. Правила/ограничения). Ответ дополнительно кешируется на 30 секунд: повторный запрос с теми же параметрами вернёт те же данные, даже если контакт за это время изменился.
Пример поиска контакта
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51

GET /companies/{company_id}/contacts/?limit=100&order_by=id:desc&query=Иван

Response
{
  "count": 1,
  "total_count": 1,
  "order_by": "id:desc",
  "items": [
    {
      "id": 1183,
      "company_id": 5,
      "name": "Иван Петров",
      "avatar_url": null,
      "is_group": false,
      "phones": [
        {
          "id": 2044,
          "type": "mobile",
          "value": "+79000000000"
        }
      ],
      "emails": [
        {
          "id": 811,
          "type": "work",
          "value": "ivan@example.com"
        }
      ],
      "tags": [
        {
          "id": 12,
          "name": "VIP",
          "description": "Постоянный клиент",
          "background_color": "#eeeeee"
        }
      ],
      "chats": [
        {
          "connection_id": 6466,
          "chat_id": 7810280,
          "source_chat_id": "79000000000@c.us",
          "name": "Иван Петров",
          "phone": "+79000000000",
          "username": null,
          "profile_link": null,
          "avatar_url": null
        }
      ]
    }
  ]
}

Карточка контакта

ContactsGetContact (GET /companies/{company_id}/contacts/{contact_id})

Возвращает один контакт в том же формате, что и элемент списка: с телефонами, email, тегами и чатами. Если контакта нет в компании, метод вернёт 404 с ошибкой 1000 (CONTACT_NOT_FOUND).

Создание контакта

ContactsCreateContact (POST /companies/{company_id}/contacts/)

Обязательно только имя (name, до 256 символов). Телефоны, email, теги и заметки можно передать сразу.

  • phones[].type — work (по умолчанию), mobile или other. Номер приводится к формату E.164.
  • emails[].type — work (по умолчанию), personal или other.
  • tags — идентификаторы существующих тегов, см. Теги. Если тега с таким id в компании нет, метод вернёт 400 с ошибкой 1002 (CONTACT_TAG_NOT_EXISTS).
  • notes[].type — сейчас поддерживается только text, текст до 8192 символов.

Телефон и email уникальны в пределах компании: если контакт с таким номером или адресом уже есть, метод вернёт 409 с ошибкой 1001 (CONTACT_PHONE_EMAIL_CONFLICT). Чтобы не плодить дубликаты, перед созданием ищите контакт по phone в списке контактов.

Создать контакт
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56

POST /companies/{company_id}/contacts/
{
  "name": "Иван Петров",
  "phones": [
    {
      "type": "mobile",
      "value": "+79000000000"
    }
  ],
  "emails": [
    {
      "type": "work",
      "value": "ivan@example.com"
    }
  ],
  "tags": [12],
  "notes": [
    {
      "type": "text",
      "text": "Пришёл с сайта, интересует тариф Standard"
    }
  ]
}


Response
{
  "id": 1183,
  "company_id": 5,
  "name": "Иван Петров",
  "avatar_url": null,
  "is_group": false,
  "phones": [
    {
      "id": 2044,
      "type": "mobile",
      "value": "+79000000000"
    }
  ],
  "emails": [
    {
      "id": 811,
      "type": "work",
      "value": "ivan@example.com"
    }
  ],
  "tags": [
    {
      "id": 12,
      "name": "VIP",
      "description": "Постоянный клиент",
      "background_color": "#eeeeee"
    }
  ],
  "chats": []
}

Изменение контакта

ContactsUpdateContact (PATCH /companies/{company_id}/contacts/{contact_id})

Несмотря на PATCH, списки phones, emails и tags заменяются целиком: что не передали — то удалится. У каждого из них значение по умолчанию — пустой список, поэтому запрос вида {"name": "Новое имя"} не просто переименует контакт, а сотрёт у него все телефоны, email и теги. Передавайте вместе с изменением полный список того, что должно остаться, а для одних только тегов используйте отдельный метод ниже.

Поле name — единственное необязательное в прямом смысле: если его не передать, имя не изменится.

Переименовать контакт, сохранив телефоны и теги
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

PATCH /companies/{company_id}/contacts/1183
{
  "name": "Иван Петров (ООО «Ромашка»)",
  "phones": [
    {
      "type": "mobile",
      "value": "+79000000000"
    }
  ],
  "emails": [
    {
      "type": "work",
      "value": "ivan@example.com"
    }
  ],
  "tags": [12]
}

Теги контакта

ContactsUpdateContactTags (PUT /companies/{company_id}/contacts/{contact_id}/tags/)

Меняет только теги, не трогая остальную карточку. Тело запроса — массив идентификаторов тегов, а не объект. Список заменяется целиком: теги, которых нет в массиве, с контакта снимаются.

Сами теги создаются отдельно, см. Теги.

Проставить контакту теги
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

PUT /companies/{company_id}/contacts/1183/tags/
[12, 13]


Response
[
  {
    "contact_id": 1183,
    "tag_id": 12
  },
  {
    "contact_id": 1183,
    "tag_id": 13
  }
]

Заметки

Заметка — произвольный текст в карточке контакта: до 8192 символов, тип пока только text. Метод создания и изменения запоминает сотрудника, который это сделал, в полях created_by и updated_by.

  • ContactsGetNotes (GET /companies/{company_id}/contacts/{contact_id}/notes/) — список заметок контакта, свежие изменения выше.
  • ContactsGetNote (GET /companies/{company_id}/contacts/{contact_id}/notes/{note_id}) — одна заметка.
  • ContactsCreateNote (POST /companies/{company_id}/contacts/{contact_id}/notes/) — создать.
  • ContactsUpdateNote (PATCH /companies/{company_id}/contacts/{contact_id}/notes/{note_id}) — изменить текст.
  • ContactsDeleteNote (DELETE /companies/{company_id}/contacts/{contact_id}/notes/{note_id}) — удалить, в ответ приходит 204 No Content.

Если заметки с таким id у контакта нет, методы вернут 404 с ошибкой 2000 (NOTE_NOT_FOUND).

Добавить заметку
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

POST /companies/{company_id}/contacts/1183/notes/
{
  "type": "text",
  "text": "Просил перезвонить после 18:00"
}


Response
{
  "id": 940,
  "contact_id": 1183,
  "type": "text",
  "text": "Просил перезвонить после 18:00",
  "created_at": "2026-09-09T10:15:00.123456Z",
  "updated_at": "2026-09-09T10:15:00.123456Z",
  "created_by": 77,
  "updated_by": 77
}

Чаты контакта

ContactsGetContactChatsList (GET /companies/{company_id}/contacts/{contact_id}/chats/)

Все чаты, привязанные к контакту, во всех мессенджерах. В каждом чате приходят chat_id (наш идентификатор, с ним работают методы чатов) и source_chat_id (идентификатор на стороне мессенджера, он же приходит в вебхуках в поле message.chat_id).

Профили в мессенджерах

ContactsGetSocialProfiles (GET /companies/{company_id}/contacts/{contact_id}/social_profiles/)

Профили клиента в мессенджерах, где он не идентифицируется номером телефона: telegram, max, vk, avito. Пригодится, чтобы показать ссылку на профиль или username рядом с карточкой.

Пример ответа
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

GET /companies/{company_id}/contacts/1183/social_profiles/

Response
[
  {
    "social_profile_type": "telegram",
    "user_id": "123456789",
    "name": "Иван Петров",
    "username": "ivan",
    "profile_link": "https://t.me/ivan"
  }
]

Связанные сущности CRM

ContactsGetContactLinkedEntities (GET /companies/{company_id}/contacts/{contact_id}/linked_entities/)

Контакты и сделки в CRM, связанные с этим контактом через интеграцию. linked_entity_type — external_contact (контакт в CRM) или external_lead (сделка), external_id — идентификатор на стороне CRM, is_closed — закрыта ли сделка, url — ссылка на карточку в CRM.

Пример ответа
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

GET /companies/{company_id}/contacts/1183/linked_entities/

Response
{
  "response_metadata": {},
  "data": {
    "linked_entities": [
      {
        "id": 51,
        "linked_entity_type": "external_lead",
        "external_id": "24680",
        "name": "Заявка с сайта",
        "is_closed": false,
        "url": "https://example.amocrm.ru/leads/detail/24680"
      }
    ]
  }
}
Помогла ли статья?
Последнее обновление
Чаты (API v2)Теги