Recipients API — контакты, атрибуты, фильтры

Коротко: Recipients API управляет получателями: контактами, атрибутами, фильтрами (таргетами) и тегами. Доступен только в сервисе «Мой диалог».

Кому подходит

• Роль: Разработчик, Интегратор
• Уровень: Опытный

Что это

Recipients API — интерфейс для работы с базой получателей. Позволяет создавать, читать, обновлять и удалять контакты, управлять их атрибутами, а также получать списки фильтров и тегов.

Все эндпоинты используют префикс /api/v1/recipient/.

Эндпоинты

Полный URL: https://web.mydialogi.ru/api/v1/recipient/....

Контакты

Список получателей

Эндпоинт: GET /recipient/recipients

Query-параметры:

Пример 1. Список по тегам:

curl --location 'https://web.mydialogi.ru/api/v1/recipient/recipients?limit=5&tags=test,test1' \
  --header 'X-API-Key: <ваш-ключ>'

Пример 2. Список по атрибуту:

curl --location 'https://web.mydialogi.ru/api/v1/recipient/recipients?limit=5&Age=30' \
  --header 'X-API-Key: <ваш-ключ>'

Формат ответа:

{
  "limit": 5,
  "offset": 0,
  "size": 2,
  "results": [
    {
      "id": 14045930,
      "name": "Anna",
      "phoneNumber": "48732231269",
      "surname": null,
      "city": null,
      "email": "Anna.test@gmail.com",
      "tags": ["test"],
      "attributes": {
        "Age": 30
      }
    }
  ]
}

Создание получателей

Эндпоинт: POST /recipient/recipients

Тело запроса:

Объект получателя в массиве recipients:

Пример:

curl --location 'https://web.mydialogi.ru/api/v1/recipient/recipients' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <ваш-ключ>' \
  --data-raw '{
    "recipients": [
      {
        "email": "test.email@gmail.com",
        "tags": ["test1"]
      },
      {
        "name": "Alice",
        "phoneNumber": "48732231255",
        "tags": ["test2"]
      }
    ],
    "tag": "test-test",
    "type": "ENRICH"
  }'

Формат ответа:

{
  "imported": 1,
  "overwritten": 0,
  "failed": 1,
  "enriched": 0
}

Обновление получателя

Эндпоинт: PUT /recipient/recipients

Тело запроса:

Пример:

curl --location --request PUT 'https://web.mydialogi.ru/api/v1/recipient/recipients' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <ваш-ключ>' \
  --data-raw '{
    "phoneNumber": "48732231255",
    "name": "Alice",
    "attributes": {
      "Age": 25
    },
    "tags": ["new tag"]
  }'

Формат ответа — обновлённый объект получателя.

Удаление получателя

Эндпоинт: DELETE /recipient/recipients

Тело запроса:

*- нужен либо phoneNumber, либо email.

Пример:

curl --location --request DELETE 'https://web.mydialogi.ru/api/v1/recipient/recipients' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <ваш-ключ>' \
  --data-raw '{
    "phoneNumber": "4915735987904"
  }'

Атрибуты

Атрибуты — дополнительные поля контакта (например, возраст, город, hobby).

Список атрибутов

Эндпоинт: GET /recipient/attributes

curl --location 'https://web.mydialogi.ru/api/v1/recipient/attributes' \
  --header 'X-API-Key: <ваш-ключ>'

Формат ответа:

{
  "limit": 0,
  "offset": 0,
  "size": 8,
  "results": [
    {
      "id": 1,
      "name": "phoneNumber",
      "typeId": 5,
      "type": null,
      "title": "Phone number",
      "nullable": false
    },
    {
      "id": 3,
      "name": "name",
      "typeId": 7,
      "type": null,
      "title": "Name",
      "nullable": true
    }
  ]
}

Поля атрибута:

Создание атрибута

Эндпоинт: POST /recipient/attributes

Тело запроса:

Обновление атрибута

Эндпоинт: PUT /recipient/attributes/{id}

Тело запроса:

Удаление атрибута

Эндпоинт: DELETE /recipient/attributes/{id}

Успешное удаление возвращает 204 No Content.

Типы атрибутов

Эндпоинт: GET /recipient/attributes/types

curl --location 'https://web.mydialogi.ru/api/v1/recipient/attributes/types' \
  --header 'X-API-Key: <ваш-ключ>'

Базовые типы (baseType):

Фильтры (таргеты)

Эндпоинт: GET /recipient/filters

Возвращает список фильтров (таргетов) компании.

curl --location 'https://web.mydialogi.ru/api/v1/recipient/filters' \
  --header 'X-API-Key: <ваш-ключ>'

Формат ответа:

Поля фильтра:

Теги

Эндпоинт: GET /recipient/tags

Возвращает список всех тегов компании.

curl --location 'https://web.mydialogi.ru/api/v1/recipient/tags' \
  --header 'X-API-Key: <ваш-ключ>'

Ответ — массив строк с названиями тегов.

Коды ответов

Пример ответа с ошибкой:

{
  "execId": null,
  "key": "errors.recipient_service.phone_not_valid",
  "code": "ValidationError",
  "message": "Phone number can`t be null",
  "args": null
}

Частые проблемы

См. также

Нужна помощь?

• Мой диалог: support@mydialogi.ru