OMNIDESK API
Пользователи
Создание пользователя

POST  |  https://[domain].omnidesk.ru/api/users.json
Добавление нового пользователя.
Параметры
Запрос

{
  "user" : {
    "user_email" : "user@domain.ru",
    "user_whatsapp_phone" : "+79261234567",
    "user_full_name" : "User's full name",
    "company_name" : "User's company name",
    "company_position" : "User's position",
    "user_note" : "Some note",
    "language_id" : 2,
    "custom_fields" : {
        "cf_20" : "some data",
        "cf_23" : true
    }
  }
}
Ответ

{
  "user" : {
    "user_id" : 200,
    "user_full_name" : "User's full name",
    "company_name" : "User's company name",
    "company_position" : "User's position",
    "thumbnail" : "",
    "confirmed" : false,
    "active" : true,
    "deleted" : false,
    "created_at" : "Mon, 05 May 2014 00:15:17 +0300",
    "updated_at" : "Tue, 23 Dec 2014 10:55:23 +0200",
    "password" : "bsdegs",
    "type" : "email",
    "user_email" : "user@domain.ru",
    "language_id" : 2,
    "custom_fields" : {
        "cf_20" : "some data",
        "cf_23" : true
    },
    "linked_users" : [123,456]
  }
}
Пример кода

curl -u [staff_email]:[api_key] -H "Content-Type: application/json" -X POST -d '{ "user": { "user_email":"user@domain.ru", "user_full_name":"User\u0027s full name", "language_id":2, "custom_fields":{"cf_20":"some data", "cf_23":true} }}' https://[domain].omnidesk.ru/api/users.json
Получение списка пользователей

GET  |  https://[domain].omnidesk.ru/api/users.json
Просмотр списка пользователей.
1. В рамках одного запроса можно получить до 100 пользователей, то есть максимальное значение параметра «limit» — 100.

2. Чтобы получать пользователей пачками, нужно передавать параметры «page» и «limit». Параметр «page» позволяет получить нужную страницу с пользователями, количество которых определяет параметр «limit».

3. Определить, сколько всего есть страниц с пользователями по заданным вами параметрам фильтрации, можно через «total_count» в ответе на первый запрос.

4. Если в запросе не указывать параметры «page» и «limit», вы получите 100 первых пользователей, отсортированных по времени создания, начиная с самого нового.

5. Максимальное значение параметра «page» — 500.

Если у вас много пользователей и вы хотите получить всех пользователей, нужно в аккаунте сотрудника в разделе «Пользователи» проверить, когда был создан первый пользователь, а после разделить весь период на небольшие интервалы и в рамках каждого интервала передавать параметры «page» и «limit».

Допустим, вы использовали Омнидеск в течение года, и за этот период в вашем аккаунте было создано 200 000 пользователей. Можно разделить год на 12 месяцев и получать данные за каждый месяц, передавая не только параметры «page» и «limit», но и параметры «from_time» и «to_time», чтобы в выборку попадали пользователи за нужный месяц с учётом времени создания.

В некоторых случаях, вместо параметров «from_time» и «to_time», может быть уместнее использовать параметры «from_updated_time» и «to_updated_time».
Параметры
Ответ

{
    "0": {
      "user" : {
        "user_id" : 200,
        "user_full_name" : "User's full name",
        "company_name" : "User's company name",
        "company_position" : "User's position",
        "thumbnail" : "",
        "confirmed" : false,
        "active" : true,
        "deleted" : false,
        "created_at" : "Mon, 05 May 2014 00:15:17 +0300",
        "updated_at" : "Tue, 23 Dec 2014 10:55:23 +0200",
        "type" : "email",
        "user_email" : "user@domain.ru",
        "language_id" : 2,
        "custom_fields" : {
            "cf_20" : "some data",
            "cf_23" : true
        }
      }
    },
    "1": {
      "user" : {
        "user_id" : 300,
        "user_full_name" : "Second user's full name",
        "company_name" : "Second user's company name",
        "company_position" : "Second user's position",
        "thumbnail" : "",
        "confirmed" : false,
        "active" : true,
        "deleted" : false,
        "created_at" : "Mon, 05 May 2014 00:15:17 +0300",
        "updated_at" : "Tue, 23 Dec 2014 10:55:23 +0200",
        "type" : "facebook",
        "facebook_id" : 123123123,
        "language_id" : 2,
        "custom_fields" : {
            "cf_20" : "some data",
            "cf_23" : true
        }
      }
    },
    "2": {
      "user" : {
        "user_id" : 400,
        "user_full_name" : "Third user's full name",
        "company_name" : "Third user's company name",
        "company_position" : "Third user's position",
        "thumbnail" : "",
        "confirmed" : false,
        "active" : true,
        "deleted" : false,
        "created_at" : "Mon, 05 May 2014 00:15:17 +0300",
        "updated_at" : "Tue, 23 Dec 2014 10:55:23 +0200",
        "type" : "twitter",
        "facebook_id" : 3333333,
        "language_id" : 1,
        "custom_fields" : {
            "cf_20" : "some data",
            "cf_23" : true
        }
      }
    },
    "total_count":20
}
Пример кода

curl -u [staff_email]:[api_key] -H "Content-Type: application/json" -g -X GET "https://[domain].omnidesk.ru/api/users.json?limit=50&page=2&language_id=2&custom_fields[cf_20]=data"
Просмотр пользователя

GET  |  https://[domain].omnidesk.ru/api/users/[id].json
Просмотр данных конкретного пользователя.
Ответ

{
  "user" : {
    "user_id" : 200,
    "user_full_name" : "User's full name",
    "company_name" : "User's company name",
    "company_position" : "User's position",
    "thumbnail" : "",
    "confirmed" : false,
    "active" : true,
    "deleted" : false,
    "created_at" : "Mon, 05 May 2014 00:15:17 +0300",
    "updated_at" : "Tue, 23 Dec 2014 10:55:23 +0200",
    "type" : "email",
    "user_email" : "user@domain.ru",
    "language_id" : 2,
    "custom_fields" : {
        "cf_20" : "some data",
        "cf_23" : true
    },
    "linked_users" : [123,456]
  }
}
Пример кода

curl -u [staff_email]:[api_key] -H "Content-Type: application/json" -X GET https://[domain].omnidesk.ru/api/users/200.json
Редактирование пользователя

PUT  |  https://[domain].omnidesk.ru/api/users/[id].json
Изменение данных конкретного пользователя.
Параметры
Запрос

{
  "user" : {
    "user_full_name" : "User's full name changed",
    "language_id" : 1,
    "custom_fields" : {
        "cf_20" : "some data",
        "cf_23" : true
    }
  }
}
Ответ

{
  "user" : {
    "user_id" : 200,
    "user_full_name" : "User's full name changed",
    "company_name" : "User's company name",
    "company_position" : "User's position",
    "thumbnail" : "",
    "confirmed" : false,
    "active" : true,
    "deleted" : false,
    "created_at" : "Mon, 05 May 2014 00:15:17 +0300",
    "updated_at" : "Tue, 23 Dec 2014 10:55:23 +0200",
    "type" : "email",
    "user_email" : "user@domain.ru",
    "language_id" : 1,
    "custom_fields" : {
        "cf_20" : "some data",
        "cf_23" : true
    }
  }
}
Пример кода

curl -u [staff_email]:[api_key] -H "Content-Type: application/json" -X PUT -d '{ "user": { "user_full_name":"User\u0027s full name changed", "language_id":2, "custom_fields":{"cf_20":"some data", "cf_23":true} }}' https://[domain].omnidesk.ru/api/users/200.json
Получение кода идентификации

POST  |  https://[domain].omnidesk.ru/api/users/identification.json
Практически все соцсети и мессенджеры, кроме WhatsApp, не передают данных, по которым можно идентифицировать пользователя.

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

{
  "user" : {
    "user_full_name" : "Семёнов Алексей",
    "company_name" : "ABCompany",
    "user_email" : "a.semenov@abcompany.com",
    "user_phone" : "+79221110000",
    "user_whatsapp_phone" : "+79221110000",
    "user_custom_id" : "a.semenov",
    "user_custom_channel" : "481", 
    "custom_fields" : {
        "cf_7264" : "some data",
        "cf_7786" : 2,
        "cf_7486" : true
    }
  }
}
Ответ

{
    "code": "o_37BD49_uv"
}
Пример кода

curl -u [staff_email]:[api_key] -H "Content-Type: application/json" -X POST -d '{ "user": { "user_email":"a.semenov@abcompany.com", "user_phone":"+79221110000", "user_full_name":"Семёнов Алексей", "custom_fields":{"cf_7264":"some data", "cf_7786":2, "cf_7486":true} }}' https://[domain].omnidesk.ru/api/users/identification.json
Связка профилей

PUT  |  https://[domain].omnidesk.ru/api/users/[id]/link.json
Когда клиент пишет через любой из каналов, мы автоматически создаём профиль, который относится именно к этому каналу.

К примеру, клиент написал через почту, и мы создали email-профиль. Далее этот же клиент написал через Телеграм, и мы создали Телеграм-профиль. Автоматически сервис никак не может понять, что этот один и тот же клиент. Поэтому у вас есть возможность связать профили, указав в Телеграм-профиле email-адрес клиента.

Данный метод позволяет выполнять такую связку через API.

ID в URL — пользователь, с профилем которого будет выполняться связка. Это именно связка профилей, а не объединение. То есть в базе данных мы их в любом случае храним отдельно, но фиксируем при этом, что они связаны (параметр linked_users в данных пользователя). Это сделано для того, чтобы в любой момент можно было отвязать связанные профили.
Параметры
Запрос

{
    "user_email" : "user@domain.ru"
}
Ответ

{
  "user" : {
    "user_id" : 1307386,
    "user_full_name" : "User's full name",
    "company_name" : "User's company name",
    "company_position" : "User's position",
    "thumbnail" : "",
    "confirmed" : false,
    "active" : true,
    "deleted" : false,
    "created_at" : "Mon, 05 May 2014 00:15:17 +0300",
    "updated_at" : "Tue, 23 Dec 2020 10:55:23 +0200",
    "language_id" : 2,
    "custom_fields" : {
        "cf_20" : "some data",
        "cf_23" : true
    },
    "type" : "telegram",
    "telegram_id" : 495582869,
    "linked_users" : [1307386,25830712]
  }
}
Пример кода

curl -u [staff_email]:[api_key] -H "Content-Type: application/json" -X PUT -d '{"user_email":"user@domain.ru"}' "https://[domain].omnidesk.ru/api/users/25830712/link.json"
Отвязка профилей

PUT  |  https://[domain].omnidesk.ru/api/users/[id]/unlink.json
Когда клиент пишет через любой из каналов, мы автоматически создаём профиль, который относится именно к этому каналу.

К примеру, клиент написал через почту, и мы создали email-профиль. Далее этот же клиент написал через Телеграм, и мы создали Телеграм-профиль. Автоматически сервис никак не может понять, что этот один и тот же клиент. Поэтому у вас есть возможность связать профили, указав в Телеграм-профиле email-адрес клиента.

Если связка была выполнена ошибочно, профили можно разъединить. Данный метод позволяет выполнять разъединение профилей через API.

ID в URL — пользователь, от которого будет отвязываться пользователь, передаваемый через параметры запроса.
Параметры
Запрос

{
    "user_id" : 25830712
}
Ответ

{
  "user" : {
    "user_id" : 1307386,
    "user_full_name" : "User's full name",
    "company_name" : "User's company name",
    "company_position" : "User's position",
    "thumbnail" : "",
    "confirmed" : false,
    "active" : true,
    "deleted" : false,
    "created_at" : "Mon, 05 May 2014 00:15:17 +0300",
    "updated_at" : "Tue, 23 Dec 2020 10:55:23 +0200",
    "language_id" : 2,
    "custom_fields" : {
        "cf_20" : "some data",
        "cf_23" : true
    },
    "type" : "telegram",
    "telegram_id" : 495582869,
    "linked_users" : [1307386]
  }
}
Пример кода

curl -u [staff_email]:[api_key] -H "Content-Type: application/json" -X PUT -d '{"user_id": 25830712}' "https://[domain].omnidesk.ru/api/users/25830712/unlink.json"
Удаление пользователя

PUT  |  https://[domain].omnidesk.ru/api/users/[id]/disable.json
Удаление пользователя. В этом случае пользователь переносится в список удалённых и при необходимости его можно восстановить.
Ответ

{
  "user" : {
    "user_id" : 200,
    "user_full_name" : "User's full name changed",
    "company_name" : "User's company name",
    "company_position" : "User's position",
    "thumbnail" : "",
    "confirmed" : false,
    "active" : true,
    "deleted" : true,
    "created_at" : "Mon, 05 May 2014 00:15:17 +0300",
    "updated_at" : "Tue, 23 Dec 2014 10:55:23 +0200",
    "type" : "email",
    "user_email" : "user@domain.ru",
    "language_id" : 2,
    "custom_fields" : {
        "cf_20" : "some data",
        "cf_23" : true
    }
  }
}
Пример кода

curl -u [staff_email]:[api_key] -H "Content-Type: application/json" -X PUT -d '' https://[domain].omnidesk.ru/api/users/200/disable.json
Блокирование пользователя

PUT  |  https://[domain].omnidesk.ru/api/users/[id]/block.json
Блокирование пользователя. Все последующие обращения пользователя автоматически попадают в спам.
Ответ

{
  "user" : {
    "user_id" : 200,
    "user_full_name" : "User's full name changed",
    "company_name" : "User's company name",
    "company_position" : "User's position",
    "thumbnail" : "",
    "confirmed" : false,
    "active" : false,
    "deleted" : false,
    "created_at" : "Mon, 05 May 2014 00:15:17 +0300",
    "updated_at" : "Tue, 23 Dec 2014 10:55:23 +0200",
    "type" : "email",
    "user_email" : "user@domain.ru",
    "language_id" : 2,
    "custom_fields" : {
        "cf_20" : "some data",
        "cf_23" : true
    }
  }
}
Пример кода

curl -u [staff_email]:[api_key] -H "Content-Type: application/json" -X PUT -d '' https://[domain].omnidesk.ru/api/users/200/block.json
Восстановление пользователя

PUT  |  https://[domain].omnidesk.ru/api/users/[id]/restore.json
Включение пользователя после блокировки или восстановление после удаления.
Ответ

{
  "user" : {
    "user_id" : 200,
    "user_full_name" : "User's full name changed",
    "company_name" : "User's company name",
    "company_position" : "User's position",
    "thumbnail" : "",
    "confirmed" : false,
    "active" : true,
    "deleted" : false,
    "created_at" : "Mon, 05 May 2014 00:15:17 +0300",
    "updated_at" : "Tue, 23 Dec 2014 10:55:23 +0200",
    "type" : "email",
    "user_email" : "user@domain.ru",
    "language_id" : 2,
    "custom_fields" : {
        "cf_20" : "some data",
        "cf_23" : true
    }
  }
}
Пример кода

curl -u [staff_email]:[api_key] -H "Content-Type: application/json" -X PUT -d '' https://[domain].omnidesk.ru/api/users/200/restore.json
Полное удаление пользователя

DELETE  |  https://[domain].omnidesk.ru/api/users/[id].json
Безвозвратное удаление пользователя. Доступно только для сотрудников с полным доступом.
Ответ

HTTP Status: 200 OK
Пример кода

curl -u [staff_email]:[api_key] -H "Content-Type: application/json" -X DELETE https://[domain].omnidesk.ru/api/users/200.json