Навигация по API
Вернуться наверх

Введение


Интерфейс API абсолютно бесплатен и доступен на всех учетных записях Novofon

Ссылка на API
https://api.novofon.com
Версия
v1
Ссылка на метод
https://api.novofon.com/v1/METHOD/

Авторизация

Каждый запрос, который нуждается в авторизации, сопровождается дополнительным заголовком, вида:
"Authorization: ключ_пользователя:подпись"

Ключи для авторизации необходимо получить в личном кабинете.

Подпись составляется по следующему алгоритму:

  • массив из передаваемых параметров (GET, POST, PUT, DELETE) сортируется по названию ключа по алфавиту;
  • из полученного массива формируется строка запроса (например, функция http_build_query в PHP), пример "from=DATEFROM&to=DATETO…";
  • и далее - соединяется по формуле: строка = имя_метода строка_запроса md5( строка_запроса ), где "имя_метода" - строка запроса, начиная от домена (с указанием версии АПИ), до начала перечисления параметров, например - '/v1/sip/'
  • полученная строка хешируется по алгоритму sha1 с секретным ключом пользователя: хеш = hash( строка, секретный_ключ )
  • и далее хеш кодируется в base64 подпись = base64_encode( хеш )

                                    ksort($params);
$paramsStr = http_build_query($params, null, '&', PHP_QUERY_RFC1738);
$sign = base64_encode(hash_hmac('sha1', $method . $paramsStr . md5($paramsStr), $secret));
$header = 'Authorization: ' . $userKey . ':' . $sign;

Заголовок Content-Type для POST запросов должен быть равным application/x-www-form-urlencoded либо multipart/form-data.

Форматы ответа: json (по умолчанию) и xml.

Чтобы получить ответ от АПИ в формате xml, в строку запроса добавляется параметр "format=xml".

Ограничения 

                                    {
    "status":"error",
    "message":"Check phone's number"
}

В ответе также содержится информация о лимитах и текущем запросе, например:

X-Zadarma-Method: /v1/ X-RateLimit-Reset: 1434371160 X-RateLimit-Limit: 100 X-RateLimit-Remaining: 99

где,

  • X-Zadarma-Method - текущий вызываемый метод;
  • X-RateLimit-Remaining - количество оставшихся запросов, с учетом лимита на метод и на пользователя;
  • X-RateLimit-Limit - цифра общего лимита обращений в минуту;
  • X-RateLimit-Reset - время сброса лимита.

Общие ограничения - 100 запросов в минуту, на методы статистики - 3 запроса в минуту.

В случае блокировки, метод отдает ответ с 429 заголовком "You exceeded the rate limit".

Ответ состоит из обязательного ключа "status" (success или error). Далее, в зависимости от метода, отдаются свои ключи с запрашиваемой информацией.

В случае ошибки, отдается дополнительный ключ "message" с описанием ошибки.

Также, все ответы сопровождаются соответствующими HTTP-заголовками.

Внимание: если нужна постоянно актуальная статистика АТС, не нужно запрашивать каждую минуту метод statistics/pbx/. Включите уведомления webhooks и получайте информацию о каждом звонке в момент его начала и окончания.

Методы

get /v1/info/balance/

баланс пользователя

                                    {
    "status":"success", 
    "balance":10.34, 
    "currency":"RUB"
}

get /v1/info/price/

стоимость звонка с учетом текущего тарифа пользователя

                                    {
    "status":"success",
    "info": {
        "prefix":"1234",
        "description":"Russia, Moscow",
        "price":"0.009",
        "currency":"RUB",
    }
}

Параметры

  • number – номер телефона
  • caller_id (опционально) – CallerID, который будет использоваться при совершении звонка.


get /v1/info/timezone/

часовой пояс пользователя

                                    {
    "status":"success",
    "unixtime":1483228800,
    "datetime":"2017-01-01 00:00:00",
    "timezone":"UTC+0"
}

get /v1/tariff/

информация о текущем тарифе пользователя

                                    {
    "status":"success",
    "info": {
        "tariff_id":5,
        "tariff_name":"Standart, special",
        "is_active":false,
        "cost":0,
        "currency":RUB,
        "used_seconds":1643,
        "used_seconds_mobile":34,
        "used_seconds_fix":726,
        "tariff_id_for_next_period":5,
        "tariff_for_next_period":Standart, special
    }
}

Где:

  • tariff_id – ID текущего тарифа пользователя;
  • tariff_name – наименование текущего тарифа пользователя;
  • is_active – активен или не активен текущий тариф;
  • cost – стоимость тарифа;
  • currency – валюта тарифа;
  • used_seconds – количество использованных секунд тарифа;
  • used_seconds_mobile –количество использованных секунд тарифа на мобильные телефоны;
  • used_seconds_fix – количество использованных секунд тарифа на стационарные телефоны;
  • used_seconds_speech_recognition – количество использованных секунд тарифа на распознавание речи;
  • tariff_id_for_next_period – ID тарифа пользователя на следующий период;
  • tariff_for_next_period – наименование тарифа пользователя на следующий период.

get /v1/request/callback/

обратный звонок

                                    {
    "status":"success", 
    "from":74951270777, 
    "to":74951270778, 
    "time":1435573082
}

Параметры

  • from – ваш номер телефона или SIP, или внутренний номер АТС, или номер сценария АТС (в формате 0-1, где 0 - номер голосового меню, 1 - номер сценария), на который вызывается callback;
  • to – номер телефона или SIP, которому звонят;
  • sip (опционально) – номер SIP-пользователя или внутренний номер АТС (например 100), через который произойдет звонок. Будет использован CallerID этого номера, в статистике будет отображаться данный номер SIP/АТС, если для указанного номера включена запись звонков либо префиксы набора, они также будут задействованы;

  • predicted (опционально) – если указан этот флаг, то запрос является предикативным (система изначально звонит на номер "to" и только если ему дозванивается, соединяет с вашим SIP либо телефонным номером);

get /v1/request/checknumber/

подтверждение номера

                                    {
    "status":"success",
    "from":74951270777,
    "to":74951270778,
    "lang":"ru",
    "time":1612779278
}

Параметры

  • caller_id - номер, отображаемый при звонке, доступны только номера, подключенные в системе;
  • to - номер телефона или SIP, которому звонят;
  • code - код, который будет воспроизводиться. Только цифры и длина не более 20 символов;
  • lang - язык начитки. При отсутствии - берется из ЛК клиента, проверяется на наличие в языках системы.

post /v1/info/number_lookup/

актуализация контактов

Параметры

  • numbers – список номеров для актуализации в международном формате.

Если numbers содержит 1 номер, результат будет возвращен сразу, если указан список номеров, результат будет отправлен по адресу, указанному на странице актуализации контактов, либо отправлен на email, если адрес не задан.

Обратите внимание: настройки данного метода проводятся на странице актуализации номеров в личном кабинете.

Пример ответа для 1 номера:

(Пример 1) 

                                    Пример 1:
{
    "status":"success",
    "info":{
        "mcc":"250",
        "mnc":"01",
        "mccName":"Russia",
        "mncName":"Mobile TeleSystems",
        "ported":false,
        "roaming":false,
        "errorDescription":"No Error"
    }
}

Пример ответа для нескольких номеров:

(Пример 2) 

                                    Пример 2:
{
    "status":"success"
}

Пример результата, отправленного по адресу, указанному на странице актуализации:

(Пример 3) 

                                    Пример 3:
{
    "success":true,
    "description":"Success",
    "result": [
        {
            "mcc":"250",
            "mnc":"01",
            "ported":false,
            "roaming":false,
            "errorDescription":"No Error",
            "mccName":"Russia",
            "mncName":"Mobile TeleSystems",
            "number":"791234567890",
        }, ...
    ]
}

get /v1/info/lists/currencies/

Список валют

                                    {
    "status": "success",
    "currencies": [
        "RUB"
    ]
}

get /v1/info/lists/languages/

Список доступных языков в ЛК

                                    {
    "status": "success",
    "languages": [
        "ru"
    ]
}

get /v1/info/lists/tariffs/

Список тарифов

                                    {
    "status": "success",
    "currency": "RUS",
    "tariffs": [
        {
            "tariff_id": 5,
            "name": "Standard",
            "cost": 0,
            "days": "30"
        },
        ...
    ],
    "package_tariffs": [
        {
            "id": 1,
            "name": "RU",
            "tariffs": [
                {
                    "tariff_id": 23,
                    "name": "Office",
                    "cost": 22,
                    "cost_annual": 216
                },
                ...
            ]
        },
        ...
    ]
}

Параметры:

  • currency – валюта

SIP

get /v1/sip/

список SIP-номеров пользователя

                                    {
    "status":"success",
    "sips":[
        {"id":"00001", "display_name":"SIP 1", "lines":3},
        {"id":"00002", "display_name":"SIP 2", "lines":3}
    ],
    "left":3
}

Где:

  • id – SIP-id;
  • display_name – отображаемое имя;
  • lines – количество линий;
  • left – количество оставшихся SIP, которые можно создать (зависит от баланса пользователя и общего количества уже созданных SIP).

get /v1/sip/<SIP>/status/

online-статус SIP-номера пользователя

                                    {
    "status":"success",
    "sip":"00001",
    "is_online":"false"
}

put /v1/sip/callerid/

изменение CallerID

                                    {
    "status":"success",
    "sip":"00001",
    "new_caller_id":"74951270777"
}

Параметры

  • id – SIP id, которому меняют CallerID;
  • number – номер, на который меняют в международном формате (из списка подтвержденных либо приобретенных номеров пользователя).

get /v1/sip/redirection/

отображение текущих переадресаций по SIP-номерам пользователя

                                    {
    "status":"success",
    "info": [
        {
            "sip_id":"00001",
            "status":"on",
            "condition":"always",
            "destination":"phone",
            "destination_value":"74951270777"
        },
    ...
    ]
}

Параметры

  • id – (опциональный) выбор конкретного SIP id.

Где:

  • sip_id – SIP id пользователя;
  • status – текущий статус: on или off;
  • condition – условия переадресации: always – всегда (по-умолчанию), unavailable – в случае не поднятия трубки либо отсутствии SIP-соединения;
  • destination – куда переадресовывается: phone – на номер телефона, pbx – на АТС;
  • destination_value – номер, куда переадресовывать: номер телефона или ID АТС.

put /v1/sip/redirection/

включение/выключение переадресации по номеру SIP

                                    {
    "status":"success",
    "sip":"00001",
    "current_status":"on"
}

Параметры

  • id – SIP id;
  • status – выставляемый статус переадресации на выбранный SIP-номер.

put /v1/sip/redirection/

изменение параметров переадресации

                                    {
    "status":"success",
    "sip":"00001",
    "destination":"74951270777"
}

Параметры

  • id – SIP id;
  • type – тип переадресации: phone – на телефон;
  • number – номер телефона.
  • condition – необязательный параметр, условие переадресации (always - всегда, unavailable - в случае не поднятия трубки либо отсутствии SIP-соединения)

post /v1/sip/create/

Создание SIP номера

                                    {
    "status": "success",
    "sip": "123456"
}

Параметры

  • name - отображаемое имя;
  • password - пароль;
  • callerid - номер для CallerID;
  • redirect_to_phone - необязательный параметр, переадресация SIP на телефон;
  • user_id - необязательный параметр, доступен для использование только дилерами и только для тех пользователей, которые ими созданы.

Статистика

get /v1/statistics/

получение общей статистики

(Пример 1) 

                                    Пример 1:
{
    "status":"success",
    "start":"2015-06-01 00:00:00",
    "end":"2015-06-29 13:45:23",
    "stats":[
        {
            "id":"155112249",
            "sip":"00001",
            "callstart":"2015-06-02 12:20:25",
            "from":74951270777,
            "to":74951270778,
            "description":"Russia, Moscow",
            "disposition":"busy",
            "billseconds":0,
            "cost":0.1950,
            "billcost":0.0000,
            "currency":"RUB"
        },
        …
    ]
}

Параметры

  • start - дата начала просмотра статистики (формат - YYYY-MM-DD HH:MM:SS);
  • end - дата окончания просмотра статистики (формат - YYYY-MM-DD HH:MM:SS);
  • sip (опционально) - фильтр по определенному SIP-номеру;
  • cost_only (опционально) - просмотр только потраченных средств за период;
  • type (опционально - только на общей статистики) - тип запроса: общий (не указывается в запросе), toll и ru495. (для статистики номеров 800 и бесплатных номеров 495);
  • skip (опционально - не учитывается при заданном параметре cost_only) - количество строк, которое необходимо пропустить в выборке, вывод начнется со строки skip + 1 (используется для пагинации совместно с параметром limit, по умолчанию равняется 0);
  • limit (опционально - не учитывается при заданном параметре cost_only) - ограничение на количество выводимых строк (используется для пагинации совместно с параметром skip, максимальное значение 1000, по умолчанию 1000).

Максимальный период получения статистики - месяц. В случае превышения лимита в запросе - период автоматически сокращается до 30 дней. Если не указана дата начала выборки, выбирается начало текущего месяца. Если не указана дата конца выборки – выборка ограничивается текущей датой и временем.

Максимальное количество выводимых строк для одного запроса - 1000. Для пагинации используйте параметры skip и limit.

?type=cost_only:

(Пример 2) 

                                    Пример 2:
{
    "status":"success",
    "start":"2015-06-01 00:00:00",
    "end":"2015-06-29 14:03:57",
    "stats":[
        {
            "cost":38.094,
            "currency":"RUB",
            "seconds":9785
        }
    ]
}

Где:

  • start – дата начала отображения статистики;
  • end – дата окончания отображения статистики;
  • id – id звонка;
  • sip – SIP-номер;
  • callstart – время начала звонка;
  • description – описание направления звонка;
  • disposition – состояние звонка:
    • 'answered' – разговор,
    • 'busy' – занято,
    • 'cancel' - отменен,
    • 'no answer' - без ответа,
    • 'call failed' - не удался,
    • 'no money' - нет средств, превышен лимит,
    • 'unallocated number' - номер не существует,
    • 'no limit' - превышен лимит,
    • 'no day limit' - превышен дневной лимит,
    • 'line limit' - превышен лимит линий,
    • 'no money, no limit' - превышен лимит;
  • billseconds – количество секунд звонка;
  • cost – стоимость минуты звонка по данному направлению;
  • billcost – стоимость оплаченных минут;
  • currency – валюта стоимости;
  • from – с какого номера звонили;
  • to – куда звонили.

get /v1/statistics/pbx/

статистика по АТС

                                    {
    "status":"success",
    "start":"2015-06-01 00:00:00",
    "end":"2015-06-30 23:59:59",
    "version":2,
    "stats":[
        {
            "call_id":1439981389.2702773,
            "sip":200,
            "callstart":"2015-06-01 15:04:00",
            "clid":200,
            "destination":5,
            "disposition":"answered",
            "seconds":5,
            "is_recorded":true,
            "pbx_call_id":"in_ae6b03b3b0765d127ec0b739209346bbc4f0d52d"
        },
        …
    ]
}

Внимание: если нужна постоянно актуальная статистика АТС, не нужно запрашивать каждую минуту метод statistics/pbx/. Включите уведомления webhooks и получайте информацию о каждом звонке в момент его начала и окончания.

Параметры

  • start - дата начала просмотра статистики (формат - YYYY-MM-DD HH:MM:SS);
  • end - дата окончания просмотра статистики (формат - YYYY-MM-DD HH:MM:SS);
  • version - формат вывода статистики (2 - новый, 1 - старый);
  • skip (опционально) - количество строк, которое необходимо пропустить в выборке, вывод начнется со строки skip + 1 (используется для пагинации совместно с параметром limit, по умолчанию равняется 0);
  • limit (опционально) - ограничение на количество выводимых строк (используется для пагинации совместно с параметром skip, максимальное значение 1000, по умолчанию 1000);
  • call_type (опционально) - направление звонков ('in' для входящих, 'out' для исходящих). Если не указан, выводятся все звонки.

Где:

  • start – дата начала отображения статистики;
  • end – дата окончания отображения статистики;
  • version - формат вывода статистики (2 - новый, 1 - старый);
  • call_id – уникальный id звонка, этот id указан в названии файла с записью разговора (уникален для каждой записи в статистике);
  • sip – SIP-номер;
  • callstart – время начала звонка;
  • clid – CallerID;
  • destination – куда звонили;
  • disposition – состояние звонка:
    • 'answered' – разговор,
    • 'busy' – занято,
    • 'cancel' - отменен,
    • 'no answer' - без ответа,
    • 'call failed' - не удался,
    • 'no money' - нет средств, превышен лимит,
    • 'unallocated number' - номер не существует,
    • 'no limit' - превышен лимит,
    • 'no day limit' - превышен дневной лимит,
    • 'line limit' - превышен лимит линий,
    • 'no money, no limit' - превышен лимит;
  • seconds – количество секунд звонка;
  • is_recorded – (true, false) записан или нет разговор;
  • pbx_call_id – постоянный ID внешнего звонка в АТС (не меняется при прохождении сценариев, голосового меню, transfer и т.д., отображается в статистике и уведомлениях);

get /v1/statistics/callback_widget/

статистика по Виджету обратного звонка

                                    {
    "status":"success",
    "start":"2016-09-01 00:00:00",
    "end":"2016-09-30 23:59:59",
    "stats":[
        {
            "id":"57d16d6a1e46c53d1f8ce323",
            "widget_id":"1",
            "sip":"00001",
            "ip":"127.0.0.1",
            "actions":[
                {
                    "kind":"come",
                    "date":"2016-09-08 16:53:45",
                    "referrer_url":"http://test.domain.com/page1/",
                    "url":"http://home.domain.com/page2/"
                },
                {
                    "kind":"show",
                    "date":"2016-09-08 16:53:46",
                    "rate":15
                },
                {
                    "kind":"call_request",
                    "date":"2016-09-08 16:54:07",
                    "number":"442037691880",
                    "request_call_date":"2016-09-09 10:00:00",
                    "redial":"n"
                },
                {
                    "kind":"close",
                    "date":"2016-09-08 16:54:35"
                }
            ]
        },
        ...
    ]
}

Параметры

  • start - дата начала просмотра статистики (формат - YYYY-MM-DD HH:MM:SS);
  • end - дата окончания просмотра статистики (формат - YYYY-MM-DD HH:MM:SS);
  • widget_id - (опционально) - идентификатор виджета, в случае отсутствия параметра берется статистика по всем виджетам;

Максимальный период получения статистики - месяц. В случае превышения лимита в запросе - период автоматически сокращается до 30 дней. Если не указана дата начала выборки, выбирается начало текущего месяца. Если не указана дата конца выборки – выборка ограничивается текущей датой и временем.

Максимальное количество выводимых строк для одного запроса - 1000. Для пагинации используйте параметры skip и limit.

Где:

  • start – дата начала отображения статистики;
  • end – дата окончания отображения статистики;
  • id – id сессии;
  • widget_id – id виджета;
  • sip – SIP-номер;
  • ip – IP-адрес посетителя;
  • kind – тип события:
    • 'come' – посетитель пришел на страницу с виджетом,
    • 'show' – показана форма виджета,
    • 'call' – заказ обратного звонка,
    • 'call_request' – заказ отложенного обратного звонка,
    • 'rate' – посетитель оценил разговор,
    • 'fail' – посетитель отметил, что обратного звонка не было,
    • 'close' – посетитель закрыл форму виджета;
  • date – дата и время события;
  • referrer_url – адрес страницы, с которой посетитель перешел на страницу с виджетом (только для события 'come');
  • url – адрес страницы виджета (только для события 'come');
  • rate – для события 'show' - количество набранных очков, для события 'rate' - оценка разговора;
  • request_call_date – дата и время указанное посетителем, как удобное для обратного звонка (только для события 'call_request');
  • redial – (true, false) перезвонили или нет в ответ на заказ отложенного обратного звонка (только для события 'call_request');
  • number – номер введенный посетителем (для событий 'call', 'call_request', 'rate', 'fail').

get /v1/statistics/incoming-calls/

получение общей статистики входящих вызовов

                                    {
    "status":"success",
    "start":"2015-06-01 00:00:00",
    "end":"2015-06-29 13:45:23",
    "stats":[
        {
            "id":"155112249",
            "sip":"00001",
            "callstart":"2015-06-02 12:20:25",
            "from":74951270777,
            "to":74951270778,
            "billseconds":0,
            "disposition":"busy",
            "description":"United Kingdom, London"
        },
        …
    ]
}

Параметры

  • start - дата начала просмотра статистики (формат - YYYY-MM-DD HH:MM:SS);
  • end - дата окончания просмотра статистики (формат - YYYY-MM-DD HH:MM:SS);
  • sip (опционально) - фильтр по определенному SIP-номеру;
  • skip (опционально - не учитывается при заданном параметре cost_only) - количество строк, которое необходимо пропустить в выборке, вывод начнется со строки skip + 1 (используется для пагинации совместно с параметром limit, по умолчанию равняется 0);
  • limit (опционально - не учитывается при заданном параметре cost_only) - ограничение на количество выводимых строк (используется для пагинации совместно с параметром skip, максимальное значение 1000, по умолчанию 1000).

Максимальный период получения статистики - месяц. В случае превышения лимита в запросе - период автоматически сокращается до 30 дней. Если не указана дата начала выборки, выбирается начало текущего месяца. Если не указана дата конца выборки – выборка ограничивается текущей датой и временем.

Максимальное количество выводимых строк для одного запроса - 1000. Для пагинации используйте параметры skip и limit.

Где:

  • start – дата начала отображения статистики;
  • end – дата окончания отображения статистики;
  • id – id звонка;
  • sip – SIP-номер;
  • callstart – время начала звонка;
  • from – с какого номера звонили;
  • to – куда звонили;
  • billseconds – количество секунд звонка;
  • disposition – состояние звонка:
    • 'answered' – разговор,
    • 'busy' – занято,
    • 'cancel' - отменен,
    • 'no answer' - без ответа,
    • 'call failed' - не удался,
    • 'no money' - нет средств, превышен лимит,
    • 'unallocated number' - номер не существует,
    • 'no limit' - превышен лимит,
    • 'no day limit' - превышен дневной лимит,
    • 'line limit' - превышен лимит линий,
    • 'no money, no limit' - превышен лимит;
  • description – описание направления звонка.

АТС

post /v1/pbx/redirection/

изменение параметров переадресации на внутреннем номере АТС

                                    {
    "status":"success",
    "current_status":"on",
    "pbx_id":"1234",
    "pbx_name":"100",
    "type":"phone",
    "destination":"79123456789",
    "condition":"noanswer"
}

Параметры

Для включения и настройки переадресации:

  • pbx_number – внутренний номер АТС, например 100;
  • status – on;
  • type – тип переадресации voicemail или phone;
  • destination – телефон или электронная почта, в зависимости от предыдущего параметра;
  • condition – условие переадресации, возможные значения: always или noanswer;
  • voicemail_greeting – оповещение о переадресации, возможные значения: no, standart, own. Указывается только при type = voicemail;
  • greeting_file – файл с оповещением в формате mp3 или wav до 5 MB. Указывается только при type = voicemail и voicemail_greeting = own;

Для выключения переадресации:

  • pbx_number – внутренний номер АТС, например 100;
  • status – off;

get /v1/pbx/redirection/

получение параметров переадресации на внутреннем номере АТС

                                    {
    "status":"success",
    "current_status":"on",
    "pbx_id":"1234",
    "pbx_name":"100",
    "type":"phone",
    "destination":"79123456789",
    "condition":"noanswer",
}

Параметры

  • pbx_number – внутренний номер АТС, например 100;

get /v1/pbx/record/request/

запрос на файл записи разговора

Параметры

  • call_id – уникальный id звонка, этот id указан в названии файла с записью разговора (уникален для каждой записи в статистике);
  • pbx_call_id – постоянный ID внешнего звонка в АТС (не меняется при прохождении сценариев, голосового меню, transfer и т.д., отображается в статистике и уведомлениях);
  • lifetime – (опциональный) время жизни ссылки в секундах (минимум - 180, максимум - 5184000, по-умолчанию - 1800).

Примечание: достаточно указать один из двух параметров идентификации (pbx_call_id или call_id), при указании pbx_call_id ссылок в ответе на запрос может быть несколько.

Пример ответа когда указан только call_id, ссылка только одна:

(Пример 1) 

                                    Пример 1:
{
    "status":"success",
    "link": "https://api.novofon.com/v1/pbx/record/download/NjM3M..NzM2Mg/1-1458313316.343456-100-2016-01-11-100155.mp3",
    "lifetime_till": "2016-01-01 23:56:22"
}

Пример ответа когда указан только pbx_call_id, ссылок может быть несколько:

(Пример 2) 

                                    Пример 2:
{
    "status":"success",
    "links":[
        "https://api.novofon.com/v1/pbx/record/download/NjM3M..NzM2Mg/1-1458313316.343456-100-2016-01-11-100155.mp3",
        "https://api.novofon.com/v1/pbx/record/download/pw7Cj..iOzn99/1-1458313475.213487-101-2016-01-11-100211.mp3"
    ],
    "lifetime_till": "2016-01-01 23:56:22"
}

Параметры:

  • link – ссылка на файл разговора;
  • lifetime_till – до которого времени ссылка будет работать.

post /v1/pbx/waitmelody/upload

загрузка мелодии

Параметры

  • file - сам файл

put /v1/pbx/waitmelody/switch

вкл/выкл мелодию для АТС

Параметры

  • state - состояние (on - вкл, off - выкл);
  • melody - тип мелодии (none - по умолчанию без мелодии, mymelody - ранее загруженная мелодия пользователя)

delete /v1/pbx/waitmelody/delete

удаление мелодии

get /v1/pbx/callinfo/

получить настройки pbx call info

                                    {
    "status": "success",
    "url": "",
    "notifications": {
        "notify_start": "true",
        "notify_internal": "false",
        "notify_end": "true",
        "notify_out_start": "false",
        "notify_out_end": "false",
        "notify_answer": "false"
    }
}

Параметры:

  • user_id - необязательный параметр, доступен для использование только дилерами и только для тех пользователей, которые ими созданы.

post /v1/pbx/callinfo/url/

изменение url для pbx call info

                                    {
    "status": "success",
    "url": ""
}

Параметры:

  • url - ссылка на ваш скрипт, с проверочным кодом <?php if (isset($_GET['zd_echo'])) exit($_GET['zd_echo']); ?> в начале скрипта;
  • user_id - необязательный параметр, доступен для использование только дилерами и только для тех пользователей, которые ими созданы.

post /v1/pbx/callinfo/notifications/

изменение реакции на события NOTIFY_* для pbx call info

                                    {
    "status": "success",
    "notifications": {
        "notify_start": "true",
        "notify_internal": "false",
        "notify_end": "true",
        "notify_out_start": "false",
        "notify_out_end": "false",
        "notify_answer": "false"
    }
}

Параметры:

  • user_id - необязательный параметр, доступен для использование только дилерами и только для тех пользователей, которые ими созданы;
  • notify_start - "true" или "false" необязательный параметр;
  • notify_internal - "true" или "false" необязательный параметр;
  • notify_end - "true" или "false" необязательный параметр;
  • notify_out_start - "true" или "false" необязательный параметр;
  • notify_out_end - "true" или "false" необязательный параметр;
  • notify_answer - "true" или "false" необязательный параметр.

delete /v1/pbx/callinfo/url/

удаление url для pbx call info

                                    {
    "status": "success",
    "url": ""
}

Параметры:

  • user_id - необязательный параметр, доступен для использование только дилерами и только для тех пользователей, которые ими созданы.

post /v1/pbx/create/

создание АТС

                                    {
    "status": "success",
    "stop_datetime": "2021-12-31 23:59:59"
}

Параметры:

  • sip_id - SIP номер для привязки АТС, если не задан попробует выбрать свободный SIP (необязательный параметр);
  • password - пароль для первого номера АТС '100';
  • user_id - необязательный параметр, доступен для использование только дилерами и только для тех пользователей, которые ими созданы.

get /v1/pbx/webhooks/

получить настройки pbx webhooks

                                    {
    "status": "success",
    "url": "",
    "hooks": {
        "number_lookup": "true",
        "call_tracking": "false",
        "sms": "true",
        "speech_recognition": "true"
    }
}

Параметры:

  • user_id - необязательный параметр, доступен для использование только дилерами и только для тех пользователей, которые ими созданы.

post /v1/pbx/webhooks/url/

изменение url для pbx webhooks

                                    {
    "status": "success",
    "url": ""
}

Параметры:

  • user_id - необязательный параметр, доступен для использование только дилерами и только для тех пользователей, которые ими созданы;
  • url - ссылка на ваш скрипт, с проверочным кодом <?php if (isset($_GET['zd_echo'])) exit($_GET['zd_echo']); ?> в начале скрипта.

post /v1/pbx/webhooks/hooks/

изменение реакции на события для других уведомлений (Актуализация контактов, Коллтрекинг, СМС и Речевая аналитика)

                                    {
    "status": "success",
    "hooks": {
        "number_lookup": "true",
        "call_tracking": "false",
        "sms": "true",
        "speech_recognition": "true"
    }
}

Параметры:

  • user_id - необязательный параметр, доступен для использование только дилерами и только для тех пользователей, которые ими созданы;
  • number_lookup - "true" или "false" необязательный параметр;
  • call_tracking - "true" или "false" необязательный параметр;
  • sms - "true" или "false" необязательный параметр;
  • speech_recognition - "true" или "false" необязательный параметр.

delete /v1/pbx/webhooks/url/

удаление url для других уведомлений (Актуализация контактов, Коллтрекинг, СМС и Речевая аналитика)

                                    {
    "status": "success",
    "url": ""
}

Параметры:

  • user_id - необязательный параметр, доступен для использование только дилерами и только для тех пользователей, которые ими созданы.

АТС (внутренние номера)

get /v1/pbx/internal/

отображение внутренних номеров АТС

                                    {
    "status":"success",
    "pbx_id":1234,
    "numbers": [
        100,
        101,
        ...
    ]
}

Где:

  • pbx_id – id ATC пользователя;
  • numbers – список внутренних номеров.

get /v1/pbx/internal/<PBXSIP>/status/

online-статус внутреннего номера АТС

                                    {
    "status":"success",
    "pbx_id":1234,
    "number":100,
    "is_online":"false"
}

Где:

  • pbx_id – АТС-id;
  • number – внутренний номер АТС;
  • is_online – online-статус (true|false).

get /v1/pbx/internal/<PBXSIP>/info/

информация о внутреннем номере АТС

                                    {
    "status": "success",
    "pbx_id": 12345,
    "number": 100,
    "name": "Extension 100",
    "caller_id": "74990000000",
    "caller_id_app_change": "true",
    "caller_id_by_direction": "false",
    "lines": "3",
    "ip_restriction": "1.1.1.1",
    "record_store": "For automatic speech recognition",
    "record_email": "email@server.com",
    "supervisor_status": 1
}

где:

  • pbx_id – атс-id;
  • number – внутренний номер атс;
  • name – отображаемое имя;
  • caller_id – CallerID;
  • caller_id_app_change – смена CallerID из приложения (true|false);
  • caller_id_by_direction – CallerID по направлению (true|false);
  • lines – количество линий;
  • ip_restriction – ограничение доступа по ip (false если не задано);
  • record_store – запись разговоров в облако (Without recognition|For manual recognition|For automatic speech recognition|false);
  • record_email – email для отправки записей разговоров (false если не включено);
  • supervisor_status – статус супервизора, 0 - выключен, 1 - включен.

put /v1/pbx/internal/recording/

включение записи разговоров на внутреннем номере АТС

                                    {
    "status":"success",
    "internal_number":100,
    "recording":"on",
    "email":"test@test.com",
    "speech_recognition":"all"
}

Параметры

  • id – внутренний номер АТС;
  • status – статус: "on" - включить, "off" - отключить, "on_email" - включить только запись на почту, "off_email" - отключить только запись на почту, "on_store" - включить только запись в хранилище, "off_store" - отключить только запись в хранилище;
  • email – (опциональный) изменение электронного адреса, куда будут отправляться записи разговоров. Вы можете указать до 3х email адресов через запятую;
  • speech_recognition – (опциональный) изменение настроек распознавания речи: "all" - распознавать все, "optional" - распознавать выборочно в статистике, "off" - отключить.

post /v1/pbx/internal/create/

создание номера АТС

                                    {
    "status": "success",
    "numbers": [
        {
            "number": 200,
            "password": "PASSWORD"
        },
        {
            "number": 201,
            "password": "PASSWORD"
        }
    ]
}

Параметры:

  • user_id - необязательный параметр, доступен для использование только дилерами и только для тех пользователей, которые ими созданы;
  • start_number - номер с которого начать создание 100 ...999 или "any" начать с любого первого доступного номера в рамках диапазона 100-999;
  • quantity - количество создаваемых номеров;
  • return_password - необязательный параметр, если 'true' в ответе будут пароли для вновь созданных номеров.

get /v1/pbx/internal/<SIP>/password/

запрос пароля внутреннего номера АТС, пароль доступен для просмотра ограниченное время

Параметры:

  • user_id - необязательный параметр, доступен для использование только дилерами и только для тех пользователей, которые ими созданы.

Пример ответа:

                                    {
    "status": "success",
    "pbx_id": 114,
    "number": 200,
    "password": "PASSWORD"
}

где

  • password - может принимать значение hidden, если пароль не доступен для просмотра.

put /v1/pbx/internal/<SIP>/password/

смена пароля на внутреннем номере

                                    {
    "status": "success",
    "pbx_id": 114,
    "number": 200
}

Параметры:

  • value - новый пароль;
  • user_id - необязательный параметр, доступен для использование только дилерами и только для тех пользователей, которые ими созданы.

put /v1/pbx/internal/<SIP>/edit/

изменение внутреннего номера АТС

Параметры

  • supervisor_status - статус супервизора, 0 - выключен, 1 - включен;
  • user_id - необязательный параметр, доступен для использование только дилерами и только для тех пользователей, которые ими созданы.

АТС (IVR)

get /v1/pbx/ivr/sounds/list

список файлов в хранилище АТС

post /v1/pbx/ivr/sounds/upload

загрузка файла

Параметры:

  • name - имя файла,
  • file - сам файл.

delete /v1/pbx/ivr/sounds/delete

удаление файла по айди

Параметры:

  • id - идентификатор файла

get /v1/pbx/ivr/

список IVR

                                    {
    "status": "success",
    "pbx_id": 114,
    "ivrs": [
        {
            "menu_id": "0",
            "title": "",
            "type": "file",
            "status": "on",
            "waitexten": 5,
            "auto_responder": {
                "status": "on",
                "waitexten": 1,
                "working_days": [
                    {
                        "day": "mon",
                        "is_active": true,
                        "begin": {
                            "hour": 9,
                            "minute": 0
                        },
                        "end": {
                            "hour": 18,
                            "minute": 0
                        }
                    },
                    {
                        "day": "tue",
                        "is_active": true,
                        "begin": {
                            "hour": 9,
                            "minute": 0
                        },
                        "end": {
                            "hour": 18,
                            "minute": 0
                        }
                    },
                    ...
                    {
                        "day": "sun",
                        "is_active": false
                    }
                ]
            },
            "dinner_status": "on",
            "dinner_time": {
                "begin": {
                    "hour": 12,
                    "minute": 0
                },
                "end": {
                    "hour": 13,
                    "minute": 0
                }
            }
        },
        {
            "menu_id": "1",
            "title": "Menu 1",
            "type": "readtext",
            "status": "off",
            "waitexten": 5,
            "auto_responder": {
                "status": "off",
                "waitexten": 1
            }
        },
        ...
    ]
}

Параметры:

  • user_id - необязательный параметр, доступен для использование только дилерами и только для тех пользователей, которые ими созданы.

post /v1/pbx/ivr/create/

создать IVR

                                    {
    "status": "success",
    "menu_id": 2
}

Параметры:

  • user_id - необязательный параметр, доступен для использование только дилерами и только для тех пользователей, которые ими созданы;
  • buy - 'true' - платное создание меню.

delete /v1/pbx/ivr/delete/

удаление IVR

                                    {
    "status": "success"
}

Параметры:

  • user_id - необязательный параметр, доступен для использование только дилерами и только для тех пользователей, которые ими созданы;
  • menu_id - должно быть > 0.

get /v1/pbx/ivr/scenario/

список сценариев IVR

                                    {
    "status": "success",
    "scenarios": [
        {
            "id": "132",
            "title": "-1",
            "push_button": -1,
            "first_sips": [
                "102"
            ],
            "second_sips": [],
            "second_sips_delay": 10,
            "third_sips": [],
            "third_sips_delay": 20
        },
        ...
    ]
}

Параметры:

  • user_id - необязательный параметр, доступен для использование только дилерами и только для тех пользователей, которые ими созданы;
  • menu_id - ID меню/IVR.

post /v1/pbx/ivr/scenario/create/

создание сценария IVR

                                    {
    "status": "success",
    "menu_id": 0,
    "scenario_id": 2
}

Параметры:

  • push_button - срабатывание сценария при нажатии кнопки: если абонент не нажимает кнопку срабатывает сценарий без нажатия, 0-9 - кнопки, 10 - автоответчик, 11-30 - дополнительные сценарии;
  • title - название;
  • extension - внутренний номер, или номера через пробел, или "fax";
  • menu_id - ID меню/IVR;
  • user_id - необязательный параметр, доступен для использование только дилерами и только для тех пользователей, которые ими созданы;
  • trigger_to_did_ext_lines - необязательный параметр . Указывает при звонках на какие номера срабатывает сценарий. Может содержать номер или список номеров через пробел;
  • trigger_from_clid_numbers - необязательный параметр. Указывет при звонках с каких номеров срабатывает сценарий. Может содержать номер или список номеров через пробел.

put /v1/pbx/ivr/scenario/edit/

изменение сценария IVR

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

(Пример 1) 

                                    Пример 1:
[
  "id": "630cb6b3dc666e947503a77a",
  "title": "Сценарий 1",
  "queue_strategy": "off",
  "queue_announce_position": 0,
  "numbers": [
    [
      "number": 100,
      "delay": 0,
      "duration": 20
    ],
    [
      "number": 101,
      "delay": 20,
      "duration": 20
    ],
    [
      "number": 102,
      "delay": 40,
      "duration": 20
    ],
  ]
]

Описание:

  • id - ID сценария;
  • title - название;
  • queue_strategy - стратегия распределения вызовов по внутренним номерам в очереди (off, random, roundrobin, leastrecent, rrmemory, fewestcalls)
  • queue_announce_position - cообщать номер в очереди
  • numbers - массив внутренних номеров
    • параметры задержки и длительности обзвона внутреннего номера:
    • number - внутренний номер или "fax";
    • delay - задержка обзвона в секундах
    • duration - длительность обзвона в секундах

Описание стратегий распределения вызовов по внутренним номерам в очереди:

  • off - очередь выключена
  • random - распределять случайно
  • roundrobin - распределять равномерно, отдавать приоритет кто давно не говорил, учитывать все звонки
  • leastrecent - распределять равномерно, отдавать приоритет кто давно не говорил, учитывать только отвеченные
  • rrmemory - распределять равномерно, отдавать приоритет кто меньше говорил, учитывать все звонки
  • fewestcalls - распределять равномерно, отдавать приоритет кто меньше говорил, учитывать только отвеченные

Параметры задержки и длительности обзвона внутренних номеров используются только с выключенной очередью (queue_strategy : "off").

Ответ: (Пример 2) 

                                    Пример 2:

{"status": "success"}

Ошибка: (Пример 3) 

                                    Пример 3:

{"status": "error","message": "Wrong parameters!"}

delete /v1/pbx/ivr/scenario/delete/

удаление сценария IVR

                                    {
    "status": "success"
}

Параметры:

  • scenario_id - ID сценария;
  • user_id - необязательный параметр, доступен для использование только дилерами и только для тех пользователей, которые ими созданы.

Распознавание речи

get /v1/speech_recognition/

получение результатов распознавания

                                    {        
    "status":"success",
    "lang":"ru-RU",
    "recognitionStatus":"in progress",
    "otherLangs":["ru-RU"],
    "words": [
        {
            "result": [
                {
                    "s": 0.02,
                    "e": 0.22,
                    "w": "word",
                },
                {
                    "s": 0.31,
                    "e": 0.56,
                    "w": "one",
                }
            ],
            "channel": 1
        }
    ],
    "phrases":[
        {
            "result": "word one",
            "channel": 1
        }
    ]
}

Параметры

  • call_id - уникальный id звонка, этот id указан в названии файла с записью разговора (уникален для каждой записи в статистике);
  • lang - язык распознавания (не обязательный);
  • return - возвращаемый результат. Варианты: words - слова, phrases - фразы. (не обязательный. по умолчанию phrases);
  • alternatives - возвращать ли альтернативные варианты. Варианты: 0 - нет, 1 - да. (не обязательный. по умолчанию 0).

Параметры ответа:

  • lang – язык;
  • recognitionStatus: - статус распознавания. Варианты:
    • in progress - в процессе распознавания,
    • error - при распознавании возникла ошибка,
    • recognized - распознано
    • ready for recognize - запись готова для распознавания,
    • not available for recognize - запись не доступна для распознавания.
  • result:
    • words - массив:
      • result - список слов (массив):
        • s - время начала слова
        • e - время окончания слова
        • w - слово
      • channel - номер канала
    • phrases - массив:
      • result - фраза
      • channel - номер канала.

put /v1/speech_recognition/

запуск распознавания звонка в статистике АТС, предварительно должно быть включено выборочное распознавание в настройках внутреннего номера

                                    {
    "status":"success"
}

Параметры

  • call_id – уникальный id звонка, этот id указан в названии файла с записью разговора (уникален для каждой записи в статистике);
  • lang - язык распознавания (не обязательный).

Виртуальные номера

get /v1/direct_numbers/

информация о прямых номерах пользователя

                                    {
    "status":"success",
    "info": [
        {
            "number":"74951270777",
            "status":"on",
            "country":"Russia",
            "description":"Moscow",
            "number_name":null,
            "sip":00001,
            "sip_name":null,
            "start_date":"2015-01-01 18:14:44",
            "stop_date":"2016-02-11 18:14:40",
            "monthly_fee":2,
            "currency":RUB,
            "channels":2,
            "autorenew":"true",
            "is_on_test":"false",
            "type":"common"
        },
    ...
    ]
}

Параметры

В зависимости от типа номера набор полей может отличаться! Описание полей:

  • number – купленный виртуальный номер пользователя;
  • status – статус номера;
    • on - номер включен;
    • parking - номер отключен (не было оплаты), но сохраняется на аккаунте 7 дней и может быть восстановлен после пополнения счета;
    • checking - номер заказан, оплачен, все необходимые документы загружены, ожидает активации;
    • checking_upload - номер заказан, оплачен, ожидается загрузка необходимых документов;
    • reserved_on - номер зарезервирован до оплаты;
    • reserved_checking - номер зарезервирован до оплаты, все необходимые документы загружены;
    • reserved_checking_upload - номер зарезервирован до оплаты, ожидается загрузка документов;
  • country – страна (для common и revenue);
  • description – описание: город или тип (для common и revenue);
  • number_name – "имя" виртуального номера (задается пользователем);
  • sip – SIP, привязанный к номеру;
  • sip_name – "имя" SIP, привязанного к номеру;
  • start_date – дата покупки номера пользователем;
  • stop_date – дата окончания срока оплаты номера пользователем;
  • monthly_fee – стоимость номера (для common);
  • currency – валюта стоимости номера (для common);
  • channels – количество линий на номере (для common);
  • minutes – общая длительность входящих звонков за текущий месяц (для revenue);
  • autorenew – включено ли автопродление номера (для common, revenue, rufree);
  • is_on_test – находится ли номер на тесте;
  • type – тип номера: common (виртуальный номер), order (заказанный, но не подключенный номер)

get /v1/direct_numbers/number/

информация о купленном номере

                                    {
    "status": "success",
    "info": {
    "number": "74951270777",
        "status": "on",
        "country": "Russia",
        "description": "Moscow",
        "number_name": "TT",
        "sip": "00004",
        "sip_name": "SIP",
        "start_date": "2016-06-08 14:32:17",
        "stop_date": "2016-06-29 10:52:18",
        "monthly_fee": 2,
        "currency": "RUB",
        "channels": "2",
        "autorenew": "true",
        "receive_sms": null,
        "is_on_test": "false"
    }
}

Параметры

  • type - может иметь одно из 3-х значений:
    • 'revenue' - Бесплатный московский номер 495;
    • 'common' - Обычный номер, все остальные;
  • number - номер.

get /v1/direct_numbers/autoprolongation/

статус автопродления

                                    {
    "status": "success",
    "number": "74951270777",
    "autoprolongation": "on"
}

Параметры

  • type - может иметь одно из 2-х значений:
    • 'revenue' - Бесплатный московский номер 495;
    • 'common' - Обычный номер, все остальные;
  • number - номер.

get /v1/direct_numbers/checking-wrongs/

получение информации об ошибках проверки документов или адреса

                                    {
   "status":"success",
   "info":{
      "wrong_document":{
         "document_type":"contract",
         "message":"The passport has expired. It is considered invalid."
      },
      "wrong_address":{
         "message":"Invalid address"
      }
   }
}

Параметры

  • group_id - id группы документов.

put /v1/direct_numbers/autoprolongation/

изменить статус автопродления

                                    {
    "status": "success",
    "number": "74951270777",
    "autoprolongation": "off"
}

Параметры

  • type - может иметь одно из 2-х значений:
    • 'revenue' - Бесплатный московский номер 495;
    • 'common' - Обычный номер, все остальные;
  • number - номер;
  • value - новый статус автопродления, on или off.

get /v1/direct_numbers/countries/

список стран в которых можно заказать номер

                                    {
    "status": "success",
    "info": [
        {
            "countryCode": "7",
            "countryCodeIso": "RU",
            "name": "Russia"
        },
        ...
    ]
}

Параметры

  • language - опционально, если не задано выдаст на языке ЛК.

get /v1/direct_numbers/country/

список направлений в стране, в которых можно заказать номер

                                    {
    "status": "success",
    "info": [
        {
            "id": "3753",
            "countryCode": "7",
            "areaCode": "800",
            "name": "Номер 800 (Toll-free)",
            "connect_fee": 0,
            "monthly_fee": 15,
            "currency": "RUB",
            "restrictions": {
                "upload": [
                    "Certificate of registration copy or passport or ID copy (both sides)",
                    "Proof of address (a copy of utility bill no older than of 6 months) - 
                    your current address (city, street, number and postal code). 
                    The address must be located in the country of ordered phone number"
                ]
            },
            "receive_sms": "false",
            "is_toll": "true",
            "feature": "Available from all networks"
            "connect_time": "0"
        },
        {
            "id": "3766",
            "countryCode": "7",
            "areaCode": "499",
            "name": "Москва",
            "connect_fee": 3,
            "monthly_fee": 3,
            "currency": "RUB",
            "restrictions": {
                "upload": [
                    "Passport or ID copy (both sides)"
                ],
                "specify": [
                    "You current address (city, street, number and postal code). 
                    The address must be located in the region of the city 
                    where you ordered the phone number"
                ]
            },
            "receive_sms": "false",
            "is_toll": "false",
            "feature": null,
            "connect_time": "0"
        },
        ...
    ]
}

Параметры

  • language - опционально, если не задано выдаст на языке ЛК;
  • country - iso код страны (ISO 3166-1 alpha-2);
  • direction_id - необязательный параметр, получение данных по конкретному направлению в стране.

put /v1/direct_numbers/set_caller_name/

установка Имя Номера (латиница и цифры, до 30 знаков)

                                    {
    "status": "success",
    "number": "74990000000",
    "caller_name": "test"
}

Параметры

  • type - может иметь одно из 2-х значений:
    • 'revenue' - телефонный номер в международном формате;
    • 'common' - Обычный номер, все остальные;
  • number - номер;
  • caller_name - для того чтобы убрать - просто передать пустое поле.

put /v1/direct_numbers/set_sip_id/

привязка номера к sip или включение тестового режима

                                    {
    "status": "success",
    "number": "74990000000",
    "sip_id": "00001"
}

Параметры

  • type - может иметь одно из 3-х значений:
    • 'revenue' - телефонный номер в международном формате;
    • 'common' - Обычный номер, все остальные;
  • number - номер;
  • sip_id - sip номер или адрес внешнего сервера (SIP URI);
  • test_mode - опционально, (on|off) - для включения тестового режима.

get /v1/direct_numbers/available/<DIRECTION_ID>/

номера, доступные для заказа

                                    {
    'status': 'success',
    'numbers': [
        {
            'id': 1712p0D1643D0t42r198658,
            'direction_id': 13755,
            'number': '74990000001'
        },
        {
            'id': 184bdf85006c3f1676be200,
            'direction_id': 13755,
            'number': '74990000000'
        },
        ...
    ]
}

Параметры:

  • DIRECTION_ID - ID направления;
  • mask - необязательный параметр, для поиска совпадений по номерам.

post /v1/direct_numbers/order/

заказ/покупка номера

                                    {
    'status': 'success',
    'number': '74990000000',
    'is_reserved': 'false',
    'is_activated': 'true'
}

Параметры:

  • number_id - ID заказываемого номера, полученный методом GET /v1/direct_numbers/available/<DIRECTION_ID>/ например: 1712p0D1643D0t42r198658 (если отсутствует выбор номеров, параметр не используется);
  • direction_id - ID направления/города;
  • documents_group_id - ID группы документов пользователя;
  • purpose - текстовое описание цели использования номера (только если требуется);
  • receive_sms - 1 - включение приема SMS (только если номер поддерживает прием SMS);
  • period - 'month' - один месяц, '3month' - три месяца (необязательный параметр, прием СМС активируется на номерах, подключенных минимум на 3 месяца);
  • user_id - необязательный параметр, доступен для использование только дилерами и только для тех пользователей, которые ими созданы.

post /v1/direct_numbers/prolong/

продление номера на произвольное кол-во месяцев

                                    {
    'status': 'success',
    'number': '74990000000',
    'stop_date': '2021-05-01 12:00:00',
    'total_paid': {
        'amount': 2,
        'currency': 'USD'
    }
}

Параметры:

  • number - продлеваемый номер;
  • months - кол-во месяцев;
  • user_id - необязательный параметр, доступен для использование только дилерами и только для тех пользователей, которые ими созданы.

put /v1/direct_numbers/receive_sms/

включение приема SMS (только если номер поддерживает прием SMS)

                                    {
    "status": "success", 
    "number": "", 
    "receive_sms": "on"
}

Параметры:

  • number - номер
  • value - значение (может быть "on" или "off")
  • documents_group_id - необязательный параметр, ID группы документов учетной записи
  • user_id - необязательный параметр, доступен для использование только дилерами и только для тех пользователей, которые ими созданы

Интеграция WebRTC виджета

get /v1/webrtc/get_key/

получить ключ для webrtc-виджета. Время жизни ключа - 72 часа.

                                    {
    "status":"success",
    "key": YOUR_KEY
}

Параметры:

  • sip – логин SIP'а или внутреннего номера АТС.

post /v1/webrtc/create/

Создание интеграции WebRTC виджета

                                    {
    "status": "success"
}

Параметры

  • user_id - необязательный параметр, доступен для использование только дилерами и только для тех пользователей, которые ими созданы;
  • domain - доменное имя.

put /v1/webrtc/

Изменение настроек интеграции WebRTC виджета

                                    {
    "status": "success"
}

Параметры

  • user_id - необязательный параметр, доступен для использование только дилерами и только для тех пользователей, которые ими созданы;
  • shape - форма виджета, допустимые значения: 'square', 'rounded';
  • position - расположение виджета, допустимые значения: 'top_left', 'top_right', 'bottom_right', 'bottom_left'.

get /v1/webrtc/

Данные интеграции WebRTC виджета

                                    {
    "status": "success",
    "is_exists": true,
    "domains": [
        "test.domain.com"
    ],
    "settings": {
        "shape": "square",
        "position": "top_right"
    }
}

Параметры

  • user_id - необязательный параметр, доступен для использование только дилерами и только для тех пользователей, которые ими созданы;

post /v1/webrtc/domain/

Добавить домен к интеграции WebRTC виджета

                                    {
   "status": "success"
}

Параметры

  • user_id - необязательный параметр, доступен для использование только дилерами и только для тех пользователей, которые ими созданы;
  • domain - доменное имя.

delete /v1/webrtc/domain/

Удаление домена из интеграции WebRTC виджета

                                    {
   "status": "success"
}

Параметры

  • user_id - необязательный параметр, доступен для использование только дилерами и только для тех пользователей, которые ими созданы;
  • domain - доменное имя.

delete /v1/webrtc/

Удаление интеграции WebRTC виджета

                                    {
   "status": "success"
}

Параметры

  • user_id - необязательный параметр, доступен для использование только дилерами и только для тех пользователей, которые ими созданы.

Методы CRM

Клиенты

get /v1/zcrm/customers

Возвращает список клиентов

Параметры

  • search (необязательный) — строка поиска. Поиск осуществляется комбинированно по:
    • имени клиента
    • номерам телефонов клиента
    • описанию клиента
    • адресу и почтовому индексу
    • веб-сайту
    • адресам e-mail
    • мессенджерам
    • именам сотрудников
    • номерам телефонов сотрудников
    • описаниям сотрудников
    • адресам e-mail сотрудников
    • мессенджерам сотрудников
  • filter (необязательный) — фильтр клиентов. Фильтр работает только по заданным полям. Структура фильтра:

(Пример 1) 

                                    Пример 1:
{
  "status": "company",
  "type": "client",
  "country": "RU",
  "city": "Moscow",
  "label": 12,
  "utm": 19,
  "employees_count": "50",
  "responsible": 20
}

Где:

  • status — статус клиента. Допустимые значения:
    • individual — физ. лицо
    • company — компания
  • type — тип клиента. Допустимые значения:
    • potential — потенциальный клиент
    • client — клиент
    • reseller — реселлер
    • partner — партнёр
  • country — страна клиента. Двухбуквенный код (RU, US и т.д.)
  • city — город клиента (строка)
  • label — тег (идентификатор)
  • utm — метка источника (идентификатор)
  • employees_count — кол-во сотрудников. Допустимые значения:
    • 50 — меньше 50
    • 50_250 — 50 – 250
    • 250_500 — 250 – 500

  • responsible — ответственный (идентификатор пользователя)

    Любой из параметров фильтра может быть опущен, т.е. не является обязательным.

  • sort (необязательный) — сортировка клиентов. Структура параметра:

(Пример 2) 

                                    Пример 2:
{
    "attr": "name",
    "desc": 0
}

Где:

  • attr — поле сортировки. Допустимые значения:
    • name — имя клиента
    • status — статус клиента
    • type — тип клиента
  • desc — направление сортировки. Допустимые значения:
    • 0 — по возрастанию
    • 1 — по убыванию
  • take (для постраничного вывода) — сколько клиентов вернуть (по умолчанию 20)
  • skip (для постраничного вывода) — сколько клиентов пропустить (по умолчанию 0)

Ответ

(Пример 3) 

                                    Пример 3:
{
  "totalCount": 82,
  "customers": [
    {
      "id": 65,
      "name": "Good company",
      "status": "company",
      "type": "client",
      "responsible_user_id": 20,
      "employees_count": "50",
      "comment": "",
      "country": "RU",
      "city": "Moscow",
      "address": "",
      "zip": "",
      "website": "",
      "created_at": "2020-04-28 05:47:47",
      "created_by": 20,
      "lead_source": "manual",
      "lead_created_at": null,
      "lead_created_by": null,
      "phones": [
        {
          "type": "work",
          "phone": "+74951270777"
        }
      ],
      "contacts": [
        {
          "type": "email_work",
          "value": "good_company@example.com"
        }
      ],
      "labels": [
        {
          "id": 12,
          "label": "Best clients"
        }
      ],
      "utms": [
        {
          "id": 19,
          "param": "utm_source",
          "value": "google",
          "display_value": "Google"
        }
      ]
    }
  ]
}

Где:

  • totalCount — общее кол-во клиентов (с учётом строки поиска и фильтра)
  • customers — массив клиентов (с учётом постраничного вывода). Каждый элемент массива содержит следующие параметры:
    • id — идентификатор клиента
    • name — имя клиента
    • status — статус клиента. Возможные значения:
      • individual — физ. лицо
      • company — компания
    • type — тип клиента. Возможные значения:
      • potential — потенциальный клиент
      • client — клиент
      • reseller — реселлер
      • partner — партнёр
    • responsible_user_id — ответственный (идентификатор пользователя)
    • employees_count — кол-во сотрудников. Возможные значения:
      • 50 — меньше 50
      • 50_250 — 50 – 250
      • 250_500 — 250 – 500
    • comment — описание клиента
    • country — страна клиента. Двухбуквенный код (RU, US и т.д.)
    • city — город клиента
    • address — адрес клиента
    • zip — почтовый индекс
    • website — веб-сайт клиента
    • created_at — дата и время создания клиента (в формате YYYY-MM-DD HH:mm:ss)
    • created_by — кем был создан (идентификатор пользователя)
    • lead_source — источник. Возможные значения:
      • manual — вручную
      • call_incoming — входящий звонок
      • call_outgoing — исходящий звонок
      • form — форма
    • lead_created_at — дата и время создания лида, если клиент был создан из лида (в формате YYYY-MM-DD HH:mm:ss)
    • lead_created_by — кем был создан лид, если клиент был создан из лида (идентификатор пользователя)
    • phones — массив телефонных номеров клиента. Каждый номер содержит следующие поля:
      • type — тип номера. Возможные значения:
        • work — рабочий
        • personal — личный
      • phone — значение номера
    • contacts — массив контактов клиента. Каждый контакт содержит следующие поля:
      • type — тип контакта. Возможные значения:
        • email_work — рабочий e-mail
        • email_personal — личный e-mail
        • skype
        • telegram
        • viber
        • whatsapp
      • value — значение контакта
    • labels — массив тегов, назначенных клиенту. Каждый тег содержит следующие поля:
      • id — идентификатор тега
      • label — значение тега
    • utms — массив меток источника. Каждая метка содержит следующие поля:
      • id — идентификатор метки
      • param — тип метки. Возможные значения:
        • utm_source
        • utm_medium
        • utm_campaign
        • utm_content
        • phone — телефон
        • custom — произвольная
      • value — фактическое значение метки
      • display_value — отображаемое значение метки

get /v1/zcrm/customers/<c_id>

Возвращает клиента по его ID

Параметры адреса

  • c_id — идентификатор клиента

Ответ

                                    {
  "id": 65,
  "name": "Good Company",
  "status": "company",
  "type": "client",
  "responsible_user_id": 20,
  "employees_count": "50",
  "comment": "",
  "country": "RU",
  "city": "Moscow",
  "address": "",
  "zip": "",
  "website": "",
  "created_at": "2020-04-28 05:47:47",
  "created_by": 20,
  "lead_source": "manual",
  "lead_created_at": null,
  "lead_created_by": null,
  "phones": [
    {
      "type": "work",
      "phone": "+74951270777"
    }
  ],
  "contacts": [
    {
      "type": "email_work",
      "value": "good_company@example.com"
    }
  ],
  "labels": [
    {
      "id": 12,
      "label": "Best clients"
    }
  ],
  "utms": [
    {
      "id": 19,
      "param": "utm_source",
      "value": "google",
      "display_value": "Google"
    }
  ],
  "custom_properties": [
    {
      "id": 18,
      "key": "loyalty",
      "title": "Loyalty",
      "value": "high"
    }
  ]
}

Где:

  • id — идентификатор клиента
  • name — имя клиента
  • status — статус клиента. Возможные значения:
    • individual — физ. лицо
    • company — компания
  • type — тип клиента. Возможные значения:
    • potential — потенциальный клиент
    • client — клиент
    • reseller — реселлер
    • partner — партнёр
  • responsible_user_id — ответственный (идентификатор пользователя)
  • employees_count — кол-во сотрудников. Возможные значения:
    • 50 — меньше 50
    • 50_250 — 50 – 250
    • 250_500 — 250 – 500
  • comment — описание клиента
  • country — страна клиента. Двухбуквенный код (RU, US и т.д.)
  • city — город клиента
  • address — адрес клиента
  • zip — почтовый индекс
  • website — веб-сайт клиента
  • created_at — дата и время создания клиента (в формате YYYY-MM-DD HH:mm:ss)
  • created_by — кем был создан (идентификатор пользователя)
  • lead_source — источник. Возможные значения:
    • manual — вручную
    • call_incoming — входящий звонок
    • call_outgoing — исходящий звонок
    • form — форма
  • lead_created_at — дата и время создания лида, если клиент был создан из лида (в формате YYYY-MM-DD HH:mm:ss)
  • lead_created_by — кем был создан лид, если клиент был создан из лида (идентификатор пользователя)
  • phones — массив телефонных номеров клиента. Каждый номер содержит следующие поля:
    • type — тип номера. Возможные значения:
      • work — рабочий
      • personal — личный
    • phone — значение номера
  • contacts — массив контактов клиента. Каждый контакт содержит следующие поля:
    • type — тип контакта. Возможные значения:
      • email_work — рабочий e-mail
      • email_personal — личный e-mail
      • skype
      • telegram
      • viber
      • whatsapp
    • value — значение контакта
  • labels — массив тегов, назначенных клиенту. Каждый тег содержит следующие поля:
    • id — идентификатор тега
    • label — значение тега
  • utms — массив меток источника. Каждая метка содержит следующие поля:
    • id — идентификатор метки
    • param — тип метки. Возможные значения:
      • utm_source
      • utm_medium
      • utm_campaign
      • utm_content
      • phone — телефон
      • custom — произвольная
    • value — фактическое значение метки
    • display_value — отображаемое значение метки
  • custom_properties — массив дополнительных свойств. Каждое дополнительное свойство содержит следующие поля:
    • id — идентификатор дополнительного свойства
    • key — уникальное имя дополнительного свойства
    • title — отображаемое название дополнительного свойства
    • value — значение дополнительного свойства

post /v1/zcrm/customers

Создаёт нового клиента с указанными данными

Параметры

  • customer — данные нового клиента. Структура клиента:

(Пример 1) 

                                    Пример 1:
{
    "name": "Good Company",
    "status": "company",
    "type": "client",
    "responsible_user_id": 20,
    "employees_count": "50",
    "comment": "",
    "country": "RU",
    "city": "Moscow",
    "address": "",
    "zip": "",
    "website": "",
    "lead_source": "manual",
    "phones": [
      {
        "type": "work", 
        "phone": "+74951270777"
      }
    ],
    "contacts": [
      {
        "type": "email_work",
        "value": "good_company@example.com"
      }
    ],
    "labels": [
      { "id": 12 },
      { "id": 13 }
    ],
    "utms": [
      { "id": 19 },
      { "id": 20 }
    ],
    "custom_properties": [
      {
        "id": 18,
        "value": "high"
      }
    ]
}

Где:

  • name — имя клиента
  • status — статус клиента. Допустимые значения:
    • individual — физ. лицо
    • company — компания
  • type — тип клиента. Допустимые значения:
    • potential — потенциальный клиент
    • client — клиент
    • reseller — реселлер
    • partner — партнёр
  • responsible_user_id — ответственный (идентификатор пользователя)
  • employees_count — кол-во сотрудников. Допустимые значения:
    • 50 — меньше 50
    • 50_250 — 50 – 250
    • 250_500 — 250 – 500
  • comment — описание клиента
  • country — страна клиента. Двухбуквенный код (RU, US и т.д.)
  • city — город клиента
  • address — адрес клиента
  • zip — почтовый индекс
  • website — веб-сайт клиента
  • lead_source — источник. Допустимые значения:
    • manual — вручную
    • call_incoming — входящий звонок
    • call_outgoing — исходящий звонок
    • form — форма
  • phones — массив телефонных номеров. Каждый номер должен содержать следующие поля:
    • type — тип номера. Возможные значения:
      • work — рабочий
      • personal — личный
    • phone — значение номера
  • contacts — массив контактов клиента. Каждый контакт должен содержать следующие поля:
    • type — тип контакта. Возможные значения:
      • email_work — рабочий e-mail
      • email_personal — личный e-mail
      • skype
      • telegram
      • viber
      • whatsapp
    • value — значение контакта
  • labels — массив тегов, добавляемых к клиенту. Каждый элемент должен содержать:
    • id — идентификатор существующего тега
  • utms — массив меток источника. Каждый элемент должен содержать:
    • id — идентификатор существующей метки
  • custom_properties — массив дополнительных свойств. Каждый элемент должен содержать:
    • id — идентификатор дополнительного свойства либо:
    • key — уникальное имя дополнительного свойства
    • value — значение дополнительного свойства

Ответ

(Пример 2) 

                                    Пример 2:
{
  "id": 65
}

Где:

  • id — идентификатор созданного клиента

put /v1/zcrm/customers/<c_id>

Обновляет существующего клиента с указанным ID

Параметры адреса

  • c_id — идентификатор клиента

Параметры

  • customer — новые данные клиента. Структура клиента:

                                    {
    "name": "Good Company",
    "status": "company",
    "type": "client",
    "responsible_user_id": 20,
    "employees_count": "50",
    "comment": "",
    "country": "RU",
    "city": "Moscow",
    "address": "",
    "zip": "",
    "website": "",
    "lead_source": "manual",
    "phones": [
      {
        "type": "work",
        "phone": "+74951270777"
      }
    ],
    "contacts": [
      {
        "type": "email_work",
        "value": "good_company@example.com"
      }
    ],
    "labels": [
      { "id": 12 },
      { "id": 13 }
    ],
    "utms": [
      { "id": 19 },
      { "id": 20 }
    ],
    "custom_properties": [
      {
        "id": 18,
        "value": "high"
      }
    ]
}

Где:

  • name — имя клиента
  • status — статус клиента. Допустимые значения:
    • individual — физ. лицо
    • company — компания
  • type — тип клиента. Допустимые значения:
    • potential — потенциальный клиент
    • client — клиент
    • reseller — реселлер
    • partner — партнёр
  • responsible_user_id — ответственный (идентификатор пользователя)
  • employees_count — кол-во сотрудников. Допустимые значения:
    • 50 — меньше 50
    • 50_250 — 50 – 250
    • 250_500 — 250 – 500
  • comment — описание клиента
  • country — страна клиента. Двухбуквенный код (RU, US и т.д.)
  • city — город клиента
  • address — адрес клиента
  • zip — почтовый индекс
  • website — веб-сайт клиента
  • lead_source — источник. Допустимые значения:
    • manual — вручную
    • call_incoming — входящий звонок
    • call_outgoing — исходящий звонок
    • form — форма
  • phones — массив телефонных номеров. Каждый номер должен содержать следующие поля:
    • type — тип номера. Возможные значения:
      • work — рабочий
      • personal — личный
    • phone — значение номера
  • contacts — массив контактов клиента. Каждый контакт должен содержать следующие поля:
    • type — тип контакта. Возможные значения:
      • email_work — рабочий e-mail
      • email_personal — личный e-mail
      • skype
      • telegram
      • viber
      • whatsapp
    • value — значение контакта
  • labels — массив тегов, добавляемых к клиенту. Каждый элемент должен содержать:
    • id — идентификатор существующего тега
  • utms — массив меток источника. Каждый элемент должен содержать:
    • id — идентификатор существующей метки
  • custom_properties — массив дополнительных свойств. Каждый элемент должен содержать:
    • id — идентификатор дополнительного свойства либо:
    • key — уникальное имя дополнительного свойства
    • value — значение дополнительного свойства

delete /v1/zcrm/customers/<c_id>

Удаляет клиента по его ID

Параметры адреса

  • c_id — идентификатор клиента

Метки источника

get /v1/zcrm/customers/utms

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

Ответ

                                    [
  {
    "id": 78,
    "param": "utm_source",
    "value": "google",
    "display_value": "Google",
    "count": 1267
  }
]

Где каждая метка источника содержит следующие поля:

  • id — идентификатор метки источника
  • param — тип метки источника. Возможные значения:
    • utm_source
    • utm_medium
    • utm_campaign
    • utm_content
    • phone — телефон
    • custom — произвольная
  • value — фактическое значение метки источника
  • display_value — отображаемое значение метки источника
  • count — кол-во клиентов и лидов, использующих данную метку источника

post /v1/zcrm/customers/utms

Создаёт новую метку источника

Параметры

  • utm — данные новой метки источника. Структура метки:

(Пример 1) 

                                    Пример 1:
{
  "param": "utm_source",
  "value": "google",
  "display_value": "Google"
}

Где:

  • param — тип метки источника. Допустимые значения:
    • utm_source
    • utm_medium
    • utm_campaign
    • utm_content
    • phone — телефон
    • custom — произвольная
  • value — фактическое значение метки источника
  • display_value (необязательный) — отображаемое значение метки источника

Ответ

(Пример 2) 

                                    Пример 2:
{
  "id": 78
}

Где:

  • id — идентификатор созданной метки источника

put /v1/zcrm/customers/utms/<utm_id>

Обновляет существующую метку источника с указанным ID

Параметры адреса

  • utm_id — идентификатор метки источника

Параметры

  • utm — новые данные метки источника. Структура метки источника:

                                    {
  "param": "utm_source",
  "value": "google",
  "display_value": "Google"
}

Где:

  • param — тип метки источника. Допустимые значения:
    • utm_source
    • utm_medium
    • utm_campaign
    • utm_content
    • phone — телефон
    • custom — произвольная
  • value — фактическое значение метки источника
  • display_value — отображаемое значение метки источника

delete /v1/zcrm/customers/utms/<utm_id>

Удаляет метку источника из системы по её ID

Параметры адреса

  • utm_id — идентификатор метки источника

Теги

get /v1/zcrm/customers/labels

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

Ответ

                                    {
  "totalCount": 5,
  "labels": [
    {
      "id": 12,
      "label": "Best clients",
      "count": 14
    }
  ]
}

Где:

  • totalCount — общее кол-во тегов в системе
  • labels — массив тегов. Каждый тег имеет следующие поля:
    • id — идентификатор тега
    • label — имя тега
    • count — кол-во клиентов и лидов, использующих данный тег

post /v1/zcrm/customers/labels

Создаёт новый тег

Параметры

  • name — имя нового тега

Ответ

                                    {
  "id": 13,
  "label": "Very best clients",
  "count": 0
}

Где:

  • id — идентификатор созданного тега
  • label — имя тега
  • count — кол-во клиентов и лидов, использующих данный тег (здесь всегда равен 0)

delete /v1/zcrm/customers/labels/<l_id>

Удаляет тег из системы по его ID

Параметры адреса

  • l_id — идентификатор тега

Дополнительные свойства

get /v1/zcrm/customers/custom-properties

Возвращает все дополнительные свойства

Ответ

                                    {
  "totalCount": 8,
  "customProperties": [
    {
      "id": 18,
      "key": "loyalty",
      "title": "Loyalty"
    }
  ]
}

Где:

  • totalCount — общее кол-во дополнительных свойств.
  • customProperties — массив дополнительных свойств. Каждое дополнительное свойство содержит следующие поля:
    • id — идентификатор дополнительного свойства
    • key — уникальное имя дополнительного свойства
    • title — отображаемое название дополнительного свойства

Лента клиента

get /v1/zcrm/customers/<c_id>/feed

Возвращает записи в ленте клиента

Параметры адреса

  • c_id — идентификатор клиента

Ответ

                                    {
  "totalCount": 17,
  "items": [
    {
      "id": 37825,
      "type": "note",
      "content": "Call to the client",
      "time": "2020-06-08 06:55:02",
      "user_id": 20,
      "user_name": "Иван Петров",
      "call_id": null,
      "call_type": null,
      "call_status": null,
      "call_phone": null,
      "call_duration": null,
      "call_record": null,
      "call_contact_name": null,
      "attached_files": [
        {
          "file_id": 576,
          "original_filename": "document.doc"
        }
      ]
    }
  ]
}

Где:

  • totalCount — общее кол-во записей
  • items — массив записей. Каждая запись содержит следующие атрибуты:
    • id — идентификатор записи
    • type — тип записи. Возможные значения:
      • event — событие
      • note — текстовая заметка
      • call — звонок
    • content — содержимое записи. Если тип записи — заметка, этот атрибут содержит текстовое содержание заметки. Если тип записи — событие, этот атрибут содержит идентификатор события, например:
      • CUSTOMER_CREATED — событие создания клиента
      • LEAD_CREATED — событие создания лида
    • time — время записи в формате YYYY-MM-DD hh:mm:ss
    • user_id — идентификатор пользователя, создавшего запись
    • user_name — имя пользователя, создавшего запись
    • call_id — идентификатор звонка (если тип записи — звонок)
    • call_type — тип звонка. Возможные значения:
      • incoming — входящий звонок
      • outgoing — исходящий звонок
    • call_status — статус звонка. Возможные значения:
      • answer — успешный звонок
      • noanswer — без ответа
      • cancel — отменён
      • busy — занято
      • failed — не удался
    • call_phone — телефонный номер звонка
    • call_duration — длительность звонка в секундах
    • call_record — включена ли запись звонка
    • call_contact_name — имя контакта звонка
    • attached_files — массив прикреплённых к заметке файлов (если тип записи — заметка). Каждый элемент массива содержит следующие атрибуты:
      • file_id — идентификатор файла
      • original_filename — оригинальное имя файла

post /v1/zcrm/customers/<c_id>/feed

Добавляет текстовую заметку в ленту клиента с возможностью прикрепления файлов

Параметры адреса

  • c_id — идентификатор клиента

Параметры

  • content — текстовое содержание заметки
  • files — массив прикрепляемых файлов

Ответ

                                    {
  "id": 37825,
  "type": "note",
  "content": "Call to the client",
  "time": "2020-06-08 06:55:02",
  "user_id": 20,
  "user_name": "Иван Петров",
  "attached_files": [
    {
      "file_id": 576,
      "original_filename": "document.doc"
    }
  ]
}

Где:

  • id — идентификатор записи
  • type — тип записи. В данном случае равен:
    • note — текстовая заметка
  • content — текстовое содержание заметки
  • time — время записи в формате YYYY-MM-DD hh:mm:ss
  • user_id — идентификатор пользователя, создавшего запись
  • user_name — имя пользователя, создавшего запись
  • attached_files — массив прикреплённых к заметке файлов (если тип записи — заметка). Каждый элемент массива содержит следующие атрибуты:
    • file_id — идентификатор файла
    • original_filename — оригинальное имя файла

put /v1/zcrm/customers/<c_id>/feed/<i_id>

Обновляет содержимое существующей текстовой заметки по её ID

Параметры адреса

  • c_id — идентификатор клиента
  • i_id — идентификатор текстовой заметки

Параметры

  • content — новый текст заметки

delete /v1/zcrm/customers/<c_id>/feed/<i_id>

Удаляет заметку в ленте клиента по её ID

Параметры адреса

  • c_id — идентификатор клиента
  • i_id — идентификатор заметки

Сотрудники

get /v1/zcrm/customers/<c_id>/employees

Возвращает список сотрудников клиента по его ID

Параметры адреса

  • c_id — идентификатор клиента

Ответ

                                    {
  "totalCount": 5,
  "employees": [
    {
      "id": 23,
      "customer_id": 11,
      "name": "Иван Петров",
      "position": "manager",
      "position_title": "",
      "comment": "",
      "phones": [
        {
          "type": "work",
          "phone": "+74951270777"
        }
      ],
      "contacts": [
        {
          "type": "email_work",
          "value": "i.petrov@example.com"
        }
      ]
    }
  ]
}

Где:

  • totalCount — кол-во сотрудников клиента
  • employees — массив сотрудников клиента. Каждый элемент массива содержит следующие атрибуты:
    • id — идентификатор сотрудника
    • customer_id — идентификатор клиента, к которому привязан сотрудник
    • name — имя сотрудника
    • position — должность сотрудника. Возможные значения:
      • ceo — ген. директор
      • director — директор
      • manager — менеджер
      • sales_manager — менеджер по продажам
      • hr — HR
      • support — поддержка
      • custom — произвольная
    • position_title — наименование произвольной должности (для position = custom)
    • comment — описание сотрудника
    • phones — массив телефонных номеров сотрудника. Каждый номер содержит следующие поля:
      • type — тип номера. Возможные значения:
        • work — рабочий
        • personal — личный
      • phone — значение номера
    • contacts — массив контактов сотрудника. Каждый контакт содержит следующие поля:
      • type — тип контакта. Возможные значения:
        • email_work — рабочий e-mail
        • email_personal — личный e-mail
        • skype
        • telegram
        • viber
        • whatsapp
      • value — значение контакта

get /v1/zcrm/customers/<c_id>/employees/<e_id>

Возвращает сотрудника клиента по его ID

Параметры адреса

  • c_id — идентификатор клиента
  • e_id — идентификатор сотрудника

Ответ

                                    {
  "id": 23,
  "customer_id": 11,
  "name": "Иван Петров",
  "position": "manager",
  "position_title": "",
  "comment": "",
  "phones": [
    {
      "type": "work",
      "phone": "+74951270777"
    }
  ],
  "contacts": [
    {
      "type": "email_work",
      "value": "i.petrov@example.com"
    }
  ]
}

Где:

  • id — идентификатор сотрудника
  • customer_id — идентификатор клиента, к которому привязан сотрудник
  • name — имя сотрудника
  • position — должность сотрудника. Возможные значения:
    • ceo — ген. директор
    • director — директор
    • manager — менеджер
    • sales_manager — менеджер по продажам
    • hr — HR
    • support — поддержка
    • custom — произвольная
  • position_title — наименование произвольной должности (для position = custom)
  • comment — описание сотрудника
  • phones — массив телефонных номеров сотрудника. Каждый номер содержит следующие поля:
    • type — тип номера. Возможные значения:
      • work — рабочий
      • personal — личный
    • phone — значение номера
  • contacts — массив контактов сотрудника. Каждый контакт содержит следующие поля:
    • type — тип контакта. Возможные значения:
      • email_work — рабочий e-mail
      • email_personal — личный e-mail
      • skype
      • telegram
      • viber
      • whatsapp
    • value — значение контакта

post /v1/zcrm/customers/<c_id>/employees

Создаёт и сохраняет нового сотрудника для заданного клиента

Параметры адреса

  • c_id — идентификатор клиента

Параметры

  • employee — данные нового сотрудника. Структура сотрудника:

(Пример 1) 

                                    Пример 1:
{
    "name": "Иван Петров",
    "position": "manager",
    "position_title": "",
    "comment": "",
    "phones": [
      {
        "type": "work",
        "phone": "+74951270777"
      }
    ],
    "contacts": [
      {
        "type": "email_work",
        "value": "i.petrov@example.com"
      }
    ]
}

Где:

  • name — имя сотрудника
  • position — должность сотрудника. Допустимые значения:
    • ceo — ген. директор
    • director — директор
    • manager — менеджер
    • sales_manager — менеджер по продажам
    • hr — HR
    • support — поддержка
    • custom — произвольная
  • position_title — наименование произвольной должности (для position = custom)
  • comment — описание сотрудника
  • phones — массив телефонных номеров сотрудника. Каждый номер содержит следующие поля:
    • type — тип номера. Возможные значения:
      • work — рабочий
      • personal — личный
    • phone — значение номера
  • contacts — массив контактов сотрудника. Каждый контакт содержит следующие поля:
    • type — тип контакта. Возможные значения:
      • email_work — рабочий e-mail
      • email_personal — личный e-mail
      • skype
      • telegram
      • viber
      • whatsapp
        • value — значение контакта

Ответ

(Пример 2) 

                                    Пример 2:
{
  "id": 23
}

Где:

  • id — идентификатор нового сотрудника

put /v1/zcrm/customers/<c_id>/employees/<e_id>

Обновляет существующего сотрудника с указанным ID

Параметры адреса

  • c_id — идентификатор клиента
  • e_id — идентификатор сотрудника

Параметры

  • employee — новые данные сотрудника. Структура:

                                    {
    "name": "Иван Петров",
    "position": "manager",
    "position_title": "",
    "comment": "",
    "phones": [
      {
        "type": "work",
        "phone": "+74951270777"
      }
    ],
    "contacts": [
      {
        "type": "email_work",
        "value": "petrov@example.com"
      }
    ]
}

Где:

  • name — имя сотрудника
  • position — должность сотрудника. Допустимые значения:
    • ceo — ген. директор
    • director — директор
    • manager — менеджер
    • sales_manager — менеджер по продажам
    • hr — HR
    • support — поддержка
    • custom — произвольная
  • position_title — наименование произвольной должности (для position = custom)
  • comment — описание сотрудника
  • phones — массив телефонных номеров сотрудника. Каждый номер содержит следующие поля:
    • type — тип номера. Возможные значения:
      • work — рабочий
      • personal — личный
    • phone — значение номера
  • contacts — массив контактов сотрудника. Каждый контакт содержит следующие поля:
    • type — тип контакта. Возможные значения:
      • email_work — рабочий e-mail
      • email_personal — личный e-mail
      • skype
      • telegram
      • viber
      • whatsapp
    • value — значение контакта

delete /v1/zcrm/customers/<c_id>/employees/<e_id>

Удаляет сотрудника по его ID

Параметры адреса

  • c_id — идентификатор клиента
  • e_id — идентификатор сотрудника

Лиды

get /v1/zcrm/leads

Возвращает список лидов

Параметры

  • search (необязательный) — строка поиска. Поиск осуществляется комбинированно по:
    • имени лида
    • номерам телефонов лида
    • описанию лида
    • адресу и почтовому индексу
    • веб-сайту
    • адресам e-mail
    • мессенджерам
  • filter (необязательный) — фильтр лидов. Структура фильтра:

(Пример 1) 

                                    Пример 1:
{
    "source": "call_incoming",
    "responsible": 32,
    "label": 12,
    "utm": 19,
    "createdAfter": "2020-06-11 12:24:00",
    "createdBefore": "2020-06-26 12:24:00"
}

Где:

  • source — источник лида. Допустимые значения:
    • manual — добавлен вручную
    • call_incoming — входящий звонок
    • call_outgoing — исходящий звонок
    • form — форма обратной связи
  • responsible — ответственный (идентификатор пользователя). Параметр также допускает специальные значения:
    • null — вернёт все назначенные кому-либо лиды
    • –1 — вернёт неразобранные лиды
    • –2 — вернёт все лиды (и назначенные, и неразобранные)
  • label — тег (идентификатор)
  • utm — метка источника (идентификатор)
  • createdAfter — показать только лиды, созданные после указанного времени (формат: YYYY-MM-DD hh:mm:ss)

  • createdBefore — показать только лиды, созданные до указанного времени (формат: YYYY-MM-DD hh:mm:ss)

    Любой из параметров фильтра может быть опущен, т.е. не является обязательным.

  • sort (необязательный) — сортировка лидов. Структура параметра:

(Пример 2) 

                                    Пример 2:
{
    "attr": "name",
    "desc": 0
}

Где:

  • attr — поле сортировки. Допустимые значения:
    • name — имя лида
    • lead_source — источник лида
    • lead_status — статус лида
    • responsible_user_id — ответственный пользователь
    • lead_created_at — время создания лида
  • desc — направление сортировки. Допустимые значения:
    • 0 — по возрастанию
    • 1 — по убыванию
      • take (для постраничного вывода) — сколько лидов вернуть (по умолчанию 20)
      • skip (для постраничного вывода) — сколько лидов пропустить (по умолчанию 0)

Ответ

(Пример 3) 

                                    Пример 3:
{
  "totalCount": 100,
  "uncategorizedCount": 10,
  "leads": [
    {
      "id": 3486,
      "name": "Good Company",
      "responsible_user_id": 234,
      "employees_count": "50",
      "comment": "",
      "country": "RU",
      "city": "Moscow",
      "address": "",
      "zip": "",
      "website": "",
      "lead_status": "not_processed",
      "lead_source": "manual",
      "lead_created_at": "2020-04-28 05:47:47",
      "lead_created_by": 234,
      "phones": [
        {
          "type": "work",
          "phone": "+74951270777"
        }
      ],
      "contacts": [
        {
          "type": "email_work",
          "value": "good_company@example.com"
        }
      ],
      "labels": [
        {
          "id": 22,
          "label": "Best clients"
        }
      ],
      "utms": [
        {
          "id": 19,
          "param": "utm_source",
          "value": "google",
          "display_value": "Google"
        }
      ]
    }
  ]
}

Где:

  • totalCount — общее кол-во найденных лидов (с учётом строки поиска и фильтра)
  • uncategorizedCount — общее кол-во неразобранных лидов (с учётом поиска и фильтра)
  • leads — массив лидов (с учётом постраничного вывода). Каждый элемент массива содержит следующие параметры:
    • id — идентификатор лида
    • name — имя лида
    • responsible_user_id — ответственный (идентификатор пользователя)
    • employees_count — кол-во сотрудников. Возможные значения:
      • 50 — меньше 50
      • 50_250 — 50 – 250
      • 250_500 — 250 – 500
    • comment — описание лида
    • country — страна лида. Двухбуквенный код (RU, US и т.д.)
    • city — город лида
    • address — адрес лида
    • zip — почтовый индекс
    • website — веб-сайт лида
    • lead_status — статус лида. Возможные значения:
      • not_processed — не обработан
      • in_progress — в обработке
      • finished — завершён
    • lead_source — источник лида. Возможные значения:
      • manual — вручную
      • call_incoming — входящий звонок
      • call_outgoing — исходящий звонок
      • form — форма
    • lead_created_at — дата и время создания лида (в формате YYYY-MM-DD HH:mm:ss)
    • lead_created_by — кем был создан лид (идентификатор пользователя)
    • phones — массив телефонных номеров лида. Каждый номер содержит следующие поля:
      • type — тип номера. Возможные значения:
        • work — рабочий
        • personal — личный
      • phone — значение номера
    • contacts — массив контактов лида. Каждый контакт содержит следующие поля:
      • type — тип контакта. Возможные значения:
        • email_work — рабочий e-mail
        • email_personal — личный e-mail
        • skype
        • telegram
        • viber
        • whatsapp
      • value — значение контакта
    • labels — массив тегов, назначенных лиду. Каждый тег содержит следующие поля:
      • id — идентификатор тега
      • label — значение тега
    • utms — массив меток источника. Каждая метка содержит следующие поля:
      • id — идентификатор метки
      • param — тип метки. Возможные значения:
        • utm_source
        • utm_medium
        • utm_campaign
        • utm_content
        • phone — телефон
        • custom — произвольная
      • value — фактическое значение метки
      • display_value — отображаемое значение метки

get /v1/zcrm/leads/<lead_id>

Возвращает лид по его ID

Ответ

                                    {
  "id": 3486,
  "name": "Good Company",
  "responsible_user_id": 234,
  "employees_count": "50",
  "comment": "",
  "country": "RU",
  "city": "Moscow",
  "address": "",
  "zip": "",
  "website": "",
  "lead_status": "not_processed",
  "lead_source": "manual",
  "lead_created_at": "2020-04-28 05:47:47",
  "lead_created_by": 234,
  "phones": [
    {
      "type": "work",
      "phone": "+74951270777"
    }
  ],
  "contacts": [
    {
      "type": "email_work",
      "value": "good_company@example.com"
    }
  ],
  "labels": [
    {
      "id": 22,
      "label": "Лучшие клиенты"
    }
  ],
  "utms": [
    {
      "id": 19,
      "param": "utm_source",
      "value": "google",
      "display_value": "Google"
    }
  ],
  "custom_properties": [
    {
      "id": 12,
      "key": "loyalty",
      "title": "Лояльность",
      "value": "high"
    }
  ]
}

Где:

  • id — идентификатор лида
  • name — имя лида
  • responsible_user_id — ответственный (идентификатор пользователя)
  • employees_count — кол-во сотрудников. Возможные значения:
    • 50 — меньше 50
    • 50_250 — 50 – 250
    • 250_500 — 250 – 500
  • comment — описание лида
  • country — страна лида. Двухбуквенный код (RU, US и т.д.)
  • city — город лида
  • address — адрес лида
  • zip — почтовый индекс
  • website — веб-сайт лида
  • lead_status — статус лида. Возможные значения:
    • not_processed — не обработан
    • in_progress — в обработке
    • finished — завершён
  • lead_source — источник лида. Возможные значения:
    • manual — вручную
    • call_incoming — входящий звонок
    • call_outgoing — исходящий звонок
    • form — форма
  • lead_created_at — дата и время создания лида (в формате YYYY-MM-DD HH:mm:ss)
  • lead_created_by — кем был создан лид (идентификатор пользователя)
  • phones — массив телефонных номеров лида. Каждый номер содержит следующие поля:
    • type — тип номера. Возможные значения:
      • work — рабочий
      • personal — личный
    • phone — значение номера
  • contacts — массив контактов лида. Каждый контакт содержит следующие поля:
    • type — тип контакта. Возможные значения:
      • email_work — рабочий e-mail
      • email_personal — личный e-mail
      • skype
      • telegram
      • viber
      • whatsapp
    • value — значение контакта
  • labels — массив тегов, назначенных лиду. Каждый тег содержит следующие поля:
    • id — идентификатор тега
    • label — значение тега
  • utms — массив меток источника. Каждая метка содержит следующие поля:
    • id — идентификатор метки
    • param — тип метки. Возможные значения:
      • utm_source
      • utm_medium
      • utm_campaign
      • utm_content
      • phone — телефон
      • custom — произвольная
    • value — фактическое значение метки
    • display_value — отображаемое значение метки

post /v1/zcrm/leads

Создаёт новый лид с указанными данными

Параметры

  • convert — сконвертировать лид в клиента. Допустимые значения:
    • 0 — не конвертировать, создать лид
    • 1 — создать клиента
    • 2 — некачественный (операция будет отменена — ни лид, ни клиент не будут созданы)
  • lead — данные нового лида. Структура лида:

(Пример 1) 

                                    Пример 1:
{
    "name": "Good Company",
    "responsible_user_id": 234,
    "employees_count": "50",
    "comment": "",
    "country": "RU",
    "city": "Moscow",
    "address": "",
    "zip": "",
    "website": "",
    "lead_source": "manual",
    "lead_status": "in_progress",
    "phones": [
      {
        "type": "work",
        "phone": "+74951270777"
      }
    ],
    "contacts": [
      {
        "type": "email_work",
        "value": "good_company@example.com"
      }
    ],
    "labels": [
      { "id": 22 },
      { "id": 23 }
    ],
    "utms": [
      { "id": 19 },
      { "id": 20 }
    ],
    "custom_properties": [
      {
        "id": 12,
        "value": "high"
      }
    ]
}

Где:

  • name — имя лида
  • responsible_user_id — ответственный (идентификатор пользователя)
  • employees_count — кол-во сотрудников. Допустимые значения:
    • 50 — меньше 50
    • 50_250 — 50 – 250
    • 250_500 — 250 – 500
  • comment — описание лида
  • country — страна лида. Двухбуквенный код (RU, US и т.д.)
  • city — город лида
  • address — адрес лида
  • zip — почтовый лида
  • website — веб-сайт лида
  • lead_source — источник лида. Допустимые значения:
    • manual — вручную
    • call_incoming — входящий звонок
    • call_outgoing — исходящий звонок
    • form — форма
  • lead_status — статус лида. Допустимые значения:
    • not_processed — не обработан
    • in_progress — в обработке
    • finished — завершён
  • phones — массив телефонных номеров. Каждый номер должен содержать следующие поля:
    • type — тип номера. Возможные значения:
      • work — рабочий
      • personal — личный
    • phone — значение номера
  • contacts — массив контактов лида. Каждый контакт должен содержать следующие поля:
    • type — тип контакта. Возможные значения:
      • email_work — рабочий e-mail
      • email_personal — личный e-mail
      • skype
      • telegram
      • viber
      • whatsapp
    • value — значение контакта
  • labels — массив тегов, добавляемых к лиду. Каждый элемент должен содержать:
    • id — идентификатор существующего тега
  • utms — массив меток источника. Каждый элемент должен содержать:
    • id — идентификатор существующей метки
  • custom_properties — массив дополнительных свойств. Каждый элемент должен содержать:
    • id — идентификатор дополнительного свойства либо:
    • key — уникальное имя дополнительного свойства
    • value — значение дополнительного свойства

Ответ

(Пример 2) 

                                    Пример 2:
{
  "id": 123
}

Где:

  • id — идентификатор созданного лида

put /v1/zcrm/leads/<lead_id>

Обновляет существующий лид с указанным ID

Параметры

  • convert — сконвертировать лид в клиента. Допустимые значения:
    • 0 — не конвертировать
    • 1 — создать клиента
    • 2 — некачественный (удалить лид)
  • lead — новые данные лида. Структура лида:

                                    {
    "name": "Good Company",
    "responsible_user_id": 234,
    "employees_count": "50",
    "comment": "",
    "country": "RU",
    "city": "Moscow",
    "address": "",
    "zip": "",
    "website": "",
    "lead_source": "manual",
    "lead_status": "in_progress",
    "phones": [
      {
        "type": "work",
        "phone": "+74951270777"
      }
    ],
    "contacts": [
      {
        "type": "email_work",
        "value": "good_company@example.com"
      }
    ],
    "labels": [
      { "id": 22 },
      { "id": 23 }
    ],
    "utms": [
      { "id": 19 },
      { "id": 20 }
    ],
    "custom_properties": [
      {
        "id": 12,
        "value": "high"
      }
    ]
}

Где:

  • name — имя лида
  • responsible_user_id — ответственный (идентификатор пользователя)
  • employees_count — кол-во сотрудников. Допустимые значения:
    • 50 — меньше 50
    • 50_250 — 50 – 250
    • 250_500 — 250 – 500
  • comment — описание лида
  • country — страна лида. Двухбуквенный код (FR, US и т.д.)
  • city — город лида
  • address — адрес лида
  • zip — почтовый лида
  • website — веб-сайт лида
  • lead_source — источник лида. Допустимые значения:
    • manual — вручную
    • call_incoming — входящий звонок
    • call_outgoing — исходящий звонок
    • form — форма
  • lead_status — статус лида. Допустимые значения:
    • not_processed — не обработан
    • in_progress — в обработке
    • finished — завершён
  • phones — массив телефонных номеров. Каждый номер должен содержать следующие поля:
    • type — тип номера. Возможные значения:
      • work — рабочий
      • personal — личный
    • phone — значение номера
  • contacts — массив контактов лида. Каждый контакт должен содержать следующие поля:
    • type — тип контакта. Возможные значения:
      • email_work — рабочий e-mail
      • email_personal — личный e-mail
      • skype
      • telegram
      • viber
      • whatsapp
    • value — значение контакта
  • labels — массив тегов, добавляемых к лиду. Каждый элемент должен содержать:
    • id — идентификатор существующего тега
  • utms — массив меток источника. Каждый элемент должен содержать:
    • id — идентификатор существующей метки
  • custom_properties — массив дополнительных свойств. Каждый элемент должен содержать:
    • id — идентификатор дополнительного свойства либо:
    • key — уникальное имя дополнительного свойства
    • value — значение дополнительного свойства

delete /v1/zcrm/leads/<lead_id>

Удаляет лид по его ID

Пользователи

get /v1/zcrm/users

Возвращает список пользователей

Ответ

                                    {
  "totalCount": 2,
  "users": [
    {
      "id": 234,
      "email": "john@example.com",
      "name": "Иван Петров",
      "group_id": 653,
      "is_superadmin": 1,
      "enabled": 1,
      "created_at": "2020-04-27 01:01:31",
      "avatar": 2457,
      "role": "",
      "status": "",
      "language": "ru",
      "color": "220",
      "color_hex": "5678BD",
      "internal_number": "100",
      "timezone": "Europe/Moscow",
      "first_day": 1,
      "device": "webphone",
      "phone_widget_location": "right",
      "phones": [
        {
          "phone": "+44123456789",
          "type": "work"
        }
      ],
      "contacts": [
        {
          "type": "email_work",
          "value": "ivanov@example.com"
        }
      ]
    }
  ]
}

Где:

  • totalCount — общее кол-во пользователей
  • users — массив пользователей. Каждый элеиент массива содержит следующие атрибуты:
    • id — идентификатор пользователя
    • email — e-mail аккаунта пользователя
    • name — имя пользователя
    • group_id — идентификатор группы пользователя
    • is_superadmin — указывает, является ли пользователь суперадминистратором (1 либо 0)
    • enabled — разблокирован ли пользователь (1 либо 0)
    • created_at — дата и время создания пользователя (в формате YYYY-MM-DD hh:mm:ss)
    • avatar — аватар пользователя (идентификатор файла)
    • role — должность пользователя
    • status — статус пользователя
    • language — язык интерфейса пользователя. Возможные варианты:
      • de — немецкий
      • en — английский
      • es — испанский
      • pl — польский
      • ru — русский
      • ua — украинский
    • color — цвет пользователя в интерфейсе ZCRM (только значение hue — от 0 до 359)
    • color_hex — цвет пользователя в интерфейсе ZCRM (hex-представление)
    • internal_number — внутренний номер АТС пользователя
    • timezone — временная зона пользователя
    • first_day — определяет, какой день недели является началом недели:
      • 0 — воскресенье
      • 1 — понедельник
    • device — что используется для звонков. Возможные значения:
      • webphone — веб-телефон
      • softphone — сторонний софтфон
    • phone_widget_location — расположение виджета веб-телефона. Возмодные значения:
      • left — располагать виджет телефона слева
      • right — располагать виджет телефона справа
    • phones — массив телефонных номеров пользователя. Каждый номер содержит следующие поля:
      • phone — значение номера
      • type — тип номера. Возможные значения:
        • work — рабочий
        • personal — личный
    • contacts — массив контактов пользователя. Каждый контакт содержит следующие поля:
      • type — тип контакта. Возможные значения:
        • email_work — рабочий контактный e-mail
        • email_personal — личный контактный e-mail
        • skype
        • telegram
        • viber
        • whatsapp
      • value — значение контакта

get /v1/zcrm/users/<user_id>

Возвращает пользователя по его ID

Ответ

                                    {
  "id": 234,
  "email": "john@example.com",
  "name": "Иван Петров",
  "group_id": 653,
  "is_superadmin": 1,
  "enabled": 1,
  "created_at": "2020-04-27 01:01:31",
  "avatar": 2457,
  "role": "",
  "status": "",
  "language": "ru",
  "color": "220",
  "color_hex": "5678BD",
  "internal_number": "100",
  "timezone": "Europe/Moscow",
  "first_day": 1,
  "device": "webphone",
  "phone_widget_location": "right",
  "phones": [
    {
      "phone": "+74951270777",
      "type": "work"
    }
  ],
  "contacts": [
    {
      "type": "email_work",
      "value": "simpson@example.com"
    }
  ],
  "pending_email_change_request": false
}

Где:

  • id — идентификатор пользователя
  • email — e-mail аккаунта пользователя
  • name — имя пользователя
  • group_id — идентификатор группы пользователя
  • is_superadmin — указывает, является ли пользователь суперадминистратором (1 либо 0)
  • enabled — разблокирован ли пользователь (1 либо 0)
  • created_at — дата и время создания пользователя (в формате YYYY-MM-DD hh:mm:ss)
  • avatar — аватар пользователя (идентификатор файла)
  • role — должность пользователя
  • status — статус пользователя
  • language — язык интерфейса пользователя. Возможные варианты:
    • de — немецкий
    • en — английский
    • es — испанский
    • pl — польский
    • ru — русский
    • ua — украинский
  • color — цвет пользователя в интерфейсе ZCRM (только значение hue — от 0 до 359)
  • color_hex — цвет пользователя в интерфейсе ZCRM (hex-представление)
  • internal_number — внутренний номер АТС пользователя
  • timezone — временная зона пользователя
  • first_day — определяет, какой день недели является началом недели:
    • 0 — воскресенье
    • 1 — понедельник
  • device — что используется для звонков. Возможные значения:
    • webphone — веб-телефон
    • softphone — сторонний софтфон
  • phone_widget_location — расположение виджета веб-телефона. Возмодные значения:
    • left — располагать виджет телефона слева
    • right — располагать виджет телефона справа
  • phones — массив телефонных номеров пользователя. Каждый номер содержит следующие поля:
    • phone — значение номера
    • type — тип номера. Возможные значения:
      • work — рабочий
      • personal — личный
  • contacts — массив контактов пользователя. Каждый контакт содержит следующие поля:
    • type — тип контакта. Возможные значения:
      • email_work — рабочий контактный e-mail
      • email_personal — личный контактный e-mail
      • skype
      • telegram
      • viber
      • whatsapp
    • value — значение контакта
  • pending_email_change_request — если был отправлен запрос на изменение e-mail аккаунта, но запрос пока не подтверждён, этот параметр будет установлен в true

get /v1/zcrm/users/<user_id>/working-hours

Возвращает рабочие часы пользователя

Ответ

                                    {
  "schedulePeriod": 7,
  "scheduleWorkingHours": [
    {
      "time_start": "2020-06-15 09:00:00",
      "time_end": "2020-06-15 18:00:00"
    }
  ],
  "scheduleFixes": [
    {
      "index": 2,
      "repeat_index": 1,
      "time_start": "2020-06-24 09:00:00",
      "time_end": "2020-06-24 13:00:00",
      "deleted": 0
    }
  ],
  "customWorkingHours": [
    {
      "time_start": "2020-06-27 11:00:00",
      "time_end": "2020-06-27 15:00:00"
    }
  ]
}

Где:

  • schedulePeriod — периодичность расписания, как оно повторяется. Для обычной рабочей недели это 7 дней, для графика «день через день» это 2 дня и т.д.
  • scheduleWorkingHours — массив рабочих периодов. Каждый рабочий период содержит соедующие атрибуты:
    • time_start — начало рабочего времени в формате YYYY-MM-DD hh:mm:ss
    • time_end — конец рабочего времени в формате YYYY-MM-DD hh:mm:ss
  • scheduleFixes — массив изменений, внесённых в рабочие периоды, определённые в параметре scheduleWorkingHours. Каждый элемент массива содержит следующие атрибуты:
    • index — индекс элемента в scheduleWorkingHours, т.е. какой рабочий период изменён
    • repeat_index — индекс повтора расписания, в котором происходит изменение рабочего периода
    • time_start — новое начало рабочего времени в формате YYYY-MM-DD hh:mm:ss
    • time_end — новый конец рабочего времени в формате YYYY-MM-DD hh:mm:ss
    • deleted — если равен 1, рабочий период полностью удалён
  • customWorkingHours — массив пользовательских, единичных рабочих периодов. Каждый рабочий период содержит соедующие атрибуты:
    • time_start — начало рабочего времени в формате YYYY-MM-DD hh:mm:ss
    • time_end — конец рабочего времени в формате YYYY-MM-DD hh:mm:ss

get /v1/zcrm/users/groups

Возвращает группы и права пользователей каждой из них

Ответ

                                    {
  "totalCount": 4,
  "groups": [
    {
      "id": 45,
      "type": "manager",
      "title": "",
      "permissions": {
        "customers_create": true,
        "customers_edit": true,
        "customers_delete": true,
        "customers_import_export": true,
        "customers_view_all": false,
        "calendar_other_users_access": false,
        "calls_other_users_access": false,
        "leads_view": false,
        "leads_edit": false,
        "leads_delete": false,
        "leads_import_export": false,
        "team_add": false,
        "team_edit": false
      }
    }
  ]
}

Где:

  • totalCount — общее кол-во групп
  • groups — массив групп. Каждая группа содержит следующие атрибуты:
    • id — идентификатор группы
    • type — тип группы. Возможные значения:
      • admin — администраторы
      • manager — менеджеры
      • chat_operator — операторы
      • trainee — стажёры
      • custom — пользовательская
    • title — имя пользовательской группы (для type = custom)
    • permissions — права пользователей группы. Администраторы имеют полный доступ, поэтому для администраторов данный объект будет пустым. Остальные группы содержат следующие атрибуты (каждый из которых может быть равен true или false):
      • customers_create — разрешено создание клиентов
      • customers_edit — разрешено редактирование клиентов
      • customers_delete — разрешено удаление клиентов
      • customers_import_export — разрешены импорт и экспорт клиентов
      • customers_view_all — разрешён просмотр всех клиентов, в том числе назначенных другим пользователям
      • calendar_other_users_access — разрешён просмотр задач других пользователей
      • calls_other_users_access — разрешён доступ к звонкам других пользователей
      • leads_view — разрешён просмотр лидов других пользователей
      • leads_edit — разрешено редактирование лидов других пользователей
      • leads_delete — разрешено удаление лидов других пользователей
      • leads_import_export — разрешены импорт и экспорт лидов
      • team_add — разрешено добавление и приглашение пользователей в команду
      • team_edit — разрешено редактирование пользователей

Обобщенные контакты

get /v1/zcrm/contacts

Возвращает список всех контактов (клиенты, сотрудники, лиды, пользователи) с номерами телефонов

Параметры

  • search (необязательный) — строка поиска. Поиск осуществляется комбинированно по:
    • именам и телефонам клиентов, лидов, сотрудников и пользователей
    • внутренним номерам АТС пользователей
  • take (для постраничного вывода) — сколько контактов вернуть (по умолчанию 20)
  • skip (для постраничного вывода) — сколько контактов пропустить (по умолчанию 0)

Ответ

(Пример 1) 

                                    Пример 1:
{
  "totalCount": 128,
  "contacts": [
    {
      "contact_type": "customer",
    },
    {
      "contact_type": "employee",
    },
    {
      "contact_type": "lead",
    },
    {
      "contact_type": "user",
    }
  ]
}

Где:

  • totalCount — общее кол-во контактов (с учётом строки поиска)
  • contacts — массив контактов. Каждый из контактов в зависимости от его типа (клиент, сотрудник, лид, пользователь) будет иметь собственный набор атрибутов.

Клиент

(Пример 2) 

                                    Пример 2:
{
    "contact_type": "customer",
    "id": 3486,
    "name": "Good Company",
    "status": "company",
    "type": "client",
    "phone": {
      "phone": "+74951270777",
      "type": "work"
    },
    "responsible": {
      "id": 234,
      "name": "Иван Петров",
      "ext_num": "100"
    }
}

Где:

  • contact_type — тип контакта:
    • customer — клиент
  • id — идентификатор клиента
  • name — имя клиента
  • status — статус клиента. Возможные значения:
    • individual — физ. лицо
    • company — компания
  • type — тип клиента. Возможные значения:
    • potential — потенциальный клиент
    • client — клиент
    • reseller — реселлер
    • partner — партнёр
  • phone — телефонный номер. Содержит следующие поля:
    • phone — непосредственно номер
    • type — тип номера. Возможные значения:
      • work — рабочий
      • personal — личный
  • responsible — ответственный пользователь. Содержит следующие поля:
    • id — идентификатор пользователя
    • name — имя пользователя
    • ext_num — внутренний номер АТС пользователя

Сотрудник клиента

(Пример 3) 

                                    Пример 3:
{
    "contact_type": "employee",
    "id": 8,
    "name": "Петр Семенов",
    "phone": {
      "phone": "+74951270778",
      "type": "work"
    },
    "position": {
      "position": "manager",
      "title": ""
    },
    "customer": {
      "id": 3486,
      "name": "Good Company"
    },
    "responsible": {
      "id": 234,
      "name": "Иван Петров",
      "ext_num": "100"
    }
}

Где:

  • contact_type — тип контакта:
    • employee — сотрудник
  • id — идентификатор сотрудника
  • name — имя сотрудника
  • phone — телефонный номер. Содержит следующие поля:
    • phone — непосредственно номер
    • type — тип номера. Возможные значения:
      • work — рабочий
      • personal — личный
  • position — должность сотрудника. Содержит следующие поля:
    • position — значение должности. Возможные значения:
      • ceo — ген. директор
      • director — директор
      • manager — менеджер
      • sales_manager — менеджер по продажам
      • hr — HR
      • support — поддержка
      • custom — произвольная
    • title — наименование произвольной должности (для position = custom)
  • customer — клиент, к которому прикреплён сотрудник. Содержит следующие поля:
    • id — идентификатор клиента
    • name — имя клиента
  • responsible — пользователь, ответственный за родительского клиента. Содержит следующие поля:
    • id — идентификатор пользователя
    • name — имя пользователя
    • ext_num — внутренний номер АТС пользователя

Лид

(Пример 4) 

                                    Пример 4:
{
    "contact_type": "lead",
    "id": 3486,
    "name": "Good Company",
    "phone": {
      "phone": "+74951270777",
      "type": "work"
    },
    "responsible": {
      "id": 234,
      "name": "Иван Петров",
      "ext_num": "100"
    }
}

Где:

  • contact_type — тип контакта:
    • lead — лид
  • id — идентификатор лида
  • name — имя лида
  • phone — телефонный номер. Содержит следующие поля:
    • phone — непосредственно номер
    • type — тип номера. Возможные значения:
      • work — рабочий
      • personal — личный
  • responsible — ответственный пользователь. Содержит следующие поля:
    • id — идентификатор пользователя
    • name — имя пользователя
    • ext_num — внутренний номер АТС пользователя

Пользователь

(Пример 5) 

                                    Пример 5:
{
    "contact_type": "user",
    "id": 234,
    "name": "Иван Петров",
    "avatar": 2457,
    "role": "",
    "status": "",
    "phone": {
      "phone": "100",
      "type": "internal"
    },
    "group": {
      "type": "admin",
      "title": ""
    }
}

Где:

  • contact_type — тип контакта:
    • user — пользователь
  • id — идентификатор пользователя
  • name — имя пользователя
  • avatar — аватар пользователя (идентификатор файла)
  • role — роль пользователя
  • status — статус пользователя
  • phone — телефонный номер. Содержит следующие поля:
    • phone — непосредственно номер
    • type — тип номера. Возможные значения:
      • work — рабочий
      • personal — личный
      • internal — внутренний номер АТС
  • group — группа пользователя. Содержит следующие поля:
    • type — тип группы. Возможные значения:
      • admin — администраторы
      • manager — менеджеры
      • chat_operator — операторы
      • trainee — стажёры
      • custom — пользовательская
    • title — имя пользовательской группы (для type = custom)

get /v1/zcrm/contacts/identify

Идентифицирует контакт (клиента, сотрудника, лида, пользователя) по номеру телефона

Параметры

  • phone — телефонный номер

Ответ

Ответ будет зависеть от типа найденного контакта (клиент, сотрудник, лид, пользователь).

Клиент

(Пример 1) 

                                    Пример 1:
{
  "contact_type": "customer",
  "id": 3486,
  "name": "Good Company",
  "status": "company",
  "type": "client",
  "phone": {
    "phone": "+74951270777",
    "type": "work"
  },
  "responsible": {
    "id": 234,
    "name": "Иван Петров",
    "ext_num": "100"
  }
}

Где:

  • contact_type — тип контакта:
    • customer — клиент
  • id — идентификатор клиента
  • name — имя клиента
  • status — статус клиента. Возможные значения:
    • individual — физ. лицо
    • company — компания
  • type — тип клиента. Возможные значения:
    • potential — потенциальный клиент
    • client — клиент
    • reseller — реселлер
    • partner — партнёр
  • phone — телефонный номер. Содержит следующие поля:
    • phone — непосредственно номер
    • type — тип номера. Возможные значения:
      • work — рабочий
      • personal — личный
  • responsible — ответственный пользователь. Содержит следующие поля:
    • id — идентификатор пользователя
    • name — имя пользователя
    • ext_num — внутренний номер АТС пользователя

Сотрудник клиента

(Пример 2) 

                                    Пример 2:
{
  "contact_type": "employee",
  "id": 8,
  "name": "Петр Семенов",
  "phone": {
    "phone": "+74951270778",
    "type": "work"
  },
  "position": {
    "position": "manager",
    "title": ""
  },
  "customer": {
    "id": 3486,
    "name": "Good Company"
  },
  "responsible": {
    "id": 234,
    "name": "Иван Петров",
    "ext_num": "100"
  }
}

Где:

  • contact_type — тип контакта:
    • employee — сотрудник
  • id — идентификатор сотрудника
  • name — имя сотрудника
  • phone — телефонный номер. Содержит следующие поля:
    • phone — непосредственно номер
    • type — тип номера. Возможные значения:
      • work — рабочий
      • personal — личный
  • position — должность сотрудника. Содержит следующие поля:
    • position — значение должности. Возможные значения:
      • ceo — ген. директор
      • director — директор
      • manager — менеджер
      • sales_manager — менеджер по продажам
      • hr — HR
      • support — поддержка
      • custom — произвольная
    • title — наименование произвольной должности (для position = custom)
  • customer — клиент, к которому прикреплён сотрудник. Содержит следующие поля:
    • id — идентификатор клиента
    • name — имя клиента
  • responsible — пользователь, ответственный за родительского клиента. Содержит следующие поля:
    • id — идентификатор пользователя
    • name — имя пользователя
    • ext_num — внутренний номер АТС пользователя

Лид

(Пример 3) 

                                    Пример 3:
{
  "contact_type": "lead",
  "id": 3486,
  "name": "Good Company",
  "phone": {
    "phone": "+74951270777",
    "type": "work"
  },
  "responsible": {
    "id": 234,
    "name": "Иван Петров",
    "ext_num": "100"
  }
}

Где:

  • contact_type — тип контакта:
    • lead — лид
  • id — идентификатор лида
  • name — имя лида
  • phone — телефонный номер. Содержит следующие поля:
    • phone — непосредственно номер
    • type — тип номера. Возможные значения:
      • work — рабочий
      • personal — личный
  • responsible — ответственный пользователь. Содержит следующие поля:
    • id — идентификатор пользователя
    • name — имя пользователя
    • ext_num — внутренний номер АТС пользователя

Пользователь

(Пример 4) 

                                    Пример 4:
{
  "contact_type": "user",
  "id": 234,
  "name": "Иван Петров",
  "avatar": 2457,
  "role": "",
  "status": "",
  "phone": {
    "phone": "100",
    "type": "internal"
  },
  "group": {
    "type": "admin",
    "title": ""
  }
}

Где:

  • contact_type — тип контакта:
    • user — пользователь
  • id — идентификатор пользователя
  • name — имя пользователя
  • avatar — аватар пользователя (идентификатор файла)
  • role — роль пользователя
  • status — статус пользователя
  • phone — телефонный номер. Содержит следующие поля:
    • phone — непосредственно номер
    • type — тип номера. Возможные значения:
      • work — рабочий
      • personal — личный
      • internal — внутренний номер АТС
  • group — группа пользователя. Содержит следующие поля:
    • type — тип группы. Возможные значения:
      • admin — администраторы
      • manager — менеджеры
      • chat_operator — операторы
      • trainee — стажёры
      • custom — пользовательская
    • title — имя пользовательской группы (для type = custom)

Сделки

get /v1/zcrm/deals

Возвращает список сделок

Параметры

  • search (необязательный) — строка поиска. Поиск сделок осуществляется по названию.

  • filter (необязательный) — фильтр сделок. Структура фильтра:

(Пример 1) 

                                    Пример 1:
{
  "currency": "RUB",
  "responsible_user": 20,
  "status": "new"
}

Где:

  • currency — валюта сделки. Трёхбуквенный код ISO 4217: RUB и т.д.
  • responsible_user — ответственный (идентификатор пользователя)

  • status — статус сделки. Допустимые значения:

    • new — новая сделка
    • in_progress — в работе
    • decision — принимают решение
    • payment — ожидается оплата
    • success — сделка успешна
    • canceled — сделка отменена

    Любой из параметров фильтра может быть опущен, т.е. не является обязательным.

  • sort (необязательный) — сортировка сделок. Структура параметра:

(Пример 2) 

                                    Пример 2:
{
  "attr": "name",
  "desc": 0
}

Где:

  • attr — поле сортировки. Допустимые значения:
    • title — название сделки
    • budget — бюджет сделки
    • status — статус сделки
    • created_at — дата создания сделки
  • desc — направление сортировки. Допустимые значения:
    • 0 — по возрастанию
    • 1 — по убыванию

  • take (для постраничного вывода) — сколько сделок вернуть (по умолчанию 20)

  • skip (для постраничного вывода) — сколько сделок пропустить (по умолчанию 0)

Ответ

(Пример 3) 

                                    Пример 3:
{
  "totalCount": 82,
  "deals": [
    {
      "id": 83,
      "title": "Good deal",
      "budget": 990.00,
      "currency": "RUB",
      "status": "new",
      "responsible_user": 20,
      "created_at": "2021-10-05 12:40:10",
      "created_by": 20,
      "customer_id": 65,
      "customer_is_lead": 0,
      "customer_name": "Good company",
      "customer_responsible_user": 20
    }
  ]
}

Где:

  • totalCount — общее кол-во сделок (с учётом строки поиска и фильтра)
  • deals — массив сделок (с учётом постраничного вывода). Каждый элемент массива содержит следующие параметры:
    • id — идентификатор сделки
    • title — название сделки
    • budget — бюджет сделки
    • currency — валюта сделки. Трёхбуквенный код ISO 4217: RUB и т.д.
    • status — статус сделки. Возможные значения:
      • new — новая сделка
      • in_progress — в работе
      • decision — принимают решение
      • payment — ожидается оплата
      • success — сделка успешна
      • canceled — сделка отменена
    • responsible_user — ответственный (идентификатор пользователя)
    • created_at — дата и время создания сделки (в формате YYYY-MM-DD HH:mm:ss)
    • created_by — кем была создана (идентификатор пользователя)
    • customer_id — идентификатор клиента, связанного со сделкой
    • customer_is_lead — флаг, показывающий, является ли клиент лидом
    • customer_name — имя клиента, связанного со сделкой
    • customer_responsible_user — ответственный по клиенту (идентификатор пользователя)

get /v1/zcrm/deals/<deal_id>

Возвращает сделку по её ID

Параметры адреса

  • deal_id — идентификатор сделки

Ответ

                                    {
  "id": 83,
  "title": "Good deal",
  "budget": 990.00,
  "currency": "RUB",
  "status": "new",
  "responsible_user": 20,
  "created_at": "2021-10-05 12:40:10",
  "created_by": 20,
  "customer_id": 65,
  "customer_is_lead": 0,
  "customer_name": "Good company",
  "customer_responsible_user": 20
}

Где:

  • id — идентификатор сделки
  • title — название сделки
  • budget — бюджет сделки
  • currency — валюта сделки. Трёхбуквенный код ISO 4217: RUB и т.д.
  • status — статус сделки. Возможные значения:
    • new — новая сделка
    • in_progress — в работе
    • decision — принимают решение
    • payment — ожидается оплата
    • success — сделка успешна
    • canceled — сделка отменена
  • responsible_user — ответственный (идентификатор пользователя)
  • created_at — дата и время создания сделки (в формате YYYY-MM-DD HH:mm:ss)
  • created_by — кем была создана (идентификатор пользователя)
  • customer_id — идентификатор клиента, связанного со сделкой
  • customer_is_lead — флаг, показывающий, является ли клиент лидом
  • customer_name — имя клиента, связанного со сделкой
  • customer_responsible_user — ответственный по клиенту (идентификатор пользователя)

post /v1/zcrm/deals

Создаёт новую сделку с указанными данными

Параметры

  • deal — данные новой сделки. Структура сделки:

(Пример 1) 

                                    Пример 1:
{
  "title": "Good deal",
  "budget": 990.00,
  "currency": "RUB",
  "status": "new",
  "responsible_user": 20,
  "customer_id": 65
}

Где:

  • title — название сделки
  • budget — бюджет сделки
  • currency — валюта сделки. Трёхбуквенный код ISO 4217: RUB и т.д.
  • status — статус сделки. Допустимые значения:
    • new — новая сделка
    • in_progress — в работе
    • decision — принимают решение
    • payment — ожидается оплата
    • success — сделка успешна
    • canceled — сделка отменена
  • responsible_user — ответственный (идентификатор пользователя)
  • customer_id — идентификатор клиента, связанного со сделкой

Ответ

(Пример 2) 

                                    Пример 2:
{
  "id": 83
}

Где:

  • id — идентификатор созданной сделки

put /v1/zcrm/deals/<deal_id>

Обновляет существующую сделку с указанным ID

Параметры адреса

  • deal_id — идентификатор сделки

Параметры

  • deal — новые данные сделки. Структура сделки:

                                    {
  "title": "Good deal",
  "budget": 990.00,
  "currency": "RUB",
  "status": "new",
  "responsible_user": 20
}

Где:

  • title — название сделки
  • budget — бюджет сделки
  • currency — валюта сделки. Трёхбуквенный код ISO 4217: RUB и т.д.
  • status — статус сделки. Допустимые значения:
    • new — новая сделка
    • in_progress — в работе
    • decision — принимают решение
    • payment — ожидается оплата
    • success — сделка успешна
    • canceled — сделка отменена
  • responsible_user — ответственный (идентификатор пользователя)

delete /v1/zcrm/deals/<deal_id>

Удаляет сделку по её ID

Параметры адреса

  • deal_id — идентификатор сделки

Лента сделки

get /v1/zcrm/deals/<deal_id>/feed

Возвращает записи в ленте сделки

Параметры адреса

  • deal_id — идентификатор сделки

Ответ

                                    {
  "totalCount": 17,
  "items": [
    {
      "id": 37825,
      "type": "note",
      "content": "Call to the client",
      "time": "2020-06-08 06:55:02",
      "user_id": 20,
      "user_name": "Иван Петров",
      "attached_files": [
        {
          "file_id": 576,
          "original_filename": "document.doc"
        }
      ]
    }
  ]
}

Где:

  • totalCount — общее кол-во записей
  • items — массив записей. Каждая запись содержит следующие атрибуты:
    • id — идентификатор записи
    • type — тип записи. Возможные значения:
      • event — событие
      • note — текстовая заметка
    • content — содержимое записи. Если тип записи — заметка, этот атрибут содержит текстовое содержание заметки. Если тип записи — событие, этот атрибут содержит идентификатор события, например:
      • DEAL_CREATED — событие создания сделки
      • DEAL_STATUS_CHANGED: success — событие изменения статуса сделки: сделка успешна
    • time — время записи в формате YYYY-MM-DD hh:mm:ss
    • user_id — идентификатор пользователя, создавшего запись
    • user_name — имя пользователя, создавшего запись
    • attached_files — массив прикреплённых к заметке файлов (если тип записи — заметка). Каждый элемент массива содержит следующие атрибуты:
      • file_id — идентификатор файла
      • original_filename — оригинальное имя файла

post /v1/zcrm/deals/<deal_id>/feed

Добавляет текстовую заметку в ленту сделки с возможностью прикрепления файлов

Параметры адреса

  • deal_id — идентификатор сделки

Параметры

  • content — текстовое содержание заметки
  • files — массив прикрепляемых файлов

Ответ

                                    {
  "id": 37825,
  "type": "note",
  "content": "Call to the client",
  "time": "2020-06-08 06:55:02",
  "user_id": 20,
  "user_name": "Иван Петров",
  "attached_files": [
    {
      "file_id": 576,
      "original_filename": "document.doc"
    }
  ]
}

Где:

  • id — идентификатор записи
  • type — тип записи. В данном случае равен:
    • note — текстовая заметка
  • content — текстовое содержание заметки
  • time — время записи в формате YYYY-MM-DD hh:mm:ss
  • user_id — идентификатор пользователя, создавшего запись
  • user_name — имя пользователя, создавшего запись
  • attached_files — массив прикреплённых к заметке файлов (если тип записи — заметка). Каждый элемент массива содержит следующие атрибуты:
    • file_id — идентификатор файла
    • original_filename — оригинальное имя файла

put /v1/zcrm/deals/<deal_id>/feed/<i_id>

Обновляет содержимое существующей текстовой заметки по её ID

Параметры адреса

  • deal_id — идентификатор сделки
  • i_id — идентификатор заметки

Параметры

  • content — новый текст заметки

delete /v1/zcrm/deals/<deal_id>/feed/<i_id>

Удаляет заметку в ленте сделки по её ID

Параметры адреса

  • deal_id — идентификатор сделки
  • i_id — идентификатор заметки

Задачи

get /v1/zcrm/events

Возвращает список задач

Параметры

  • search (необязательный) — строка поиска. Поиск осуществляется комбинированно по:
    • названию задач
    • описанию задач
    • комментарию к завершённым задачам
  • filter (необязательный) — фильтр задач. Структура фильтра:

(Пример 1) 

                                    Пример 1:
{
    "responsible": 456,
    "createdBy": 456,
    "start": "2020-06-03 02:56:00",
    "end": "2020-06-12 02:56:00",
    "completed": 1
}

Где:

  • responsible — ответственный (идентификатор пользователя)
  • createdBy — создал (идентификатор пользователя)
  • start — показать задачи, начинающиеся после указанного времени (в формате YYYY-MM-DD hh:mm:ss)
  • end — показать задачи, заканчивающиеся до указанного времени (в формате YYYY-MM-DD hh:mm:ss)
  • completed — установите в 1, чтобы показать в том числе завершённые задачи
  • sort (необязательный) — сортировка задач. Структура параметра:

(Пример 2) 

                                    Пример 2:
{
    "attr": "start",
    "desc": 0
}

Где:

  • attr — поле сортировки. Допустимые значения:
    • responsible — ответственный пользователь
    • title — название задачи
    • start — время начала задачи
    • end — время окончания задачи
  • desc — направление сортировки. Допустимые значения:
    • 0 — по возрастанию
    • 1 — по убыванию

Ответ

(Пример 3) 

                                    Пример 3:
{
  "totalCount": 4,
  "events": [
    {
      "id": 40,
      "type": "task",
      "title": "Create text for Good Company",
      "description": "",
      "start": "2020-05-26 09:00:00",
      "end": "2020-05-26 12:30:00",
      "allDay": false,
      "created_by": 234,
      "responsible_user": 234,
      "phone": "",
      "call_done": 0,
      "completed": 0,
      "completed_comment": "",
      "members": [234, 235],
      "customers": [
        {
          "id": 3486,
          "name": "Good Company",
          "status": "company",
          "type": "client",
          "lead_source": "manual",
          "lead_status": "not_processed",
          "contact_type": "customer"
        }
      ]
    }
  ]
}

Где:

  • totalCount — общее кол-во задач
  • events — массив задач. Каждая задача содержит следующие атрибуты:
    • id — идентификатор задачи
    • type — тип задачи. Возможные значения:
      • task — задача
      • call — звонок
    • title — название задачи
    • description — описание задачи (в формате Quill Delta)
    • start — дата и время начала задачи (в формате YYYY-MM-DD hh:mm:ss)
    • end — дата и время окончания задачи (в формате YYYY-MM-DD hh:mm:ss)
    • allDay — задача на весь день (true или false) — дата определяется параметром start
    • created_by — идентификатор пользователя, создавшего задачу
    • responsible_user — идентификатор пользователя, ответственного за задачу
    • phone — номер телефона для звонка (если тип задачи — звонок)
    • call_done — указывает, был ли осуществлён звонок
    • completed — указывает, что задача помечена как завершённая
    • completed_comment — комментарий к завершённой задаче
    • members — массив участников задачи (только идентификаторы пользователей)
    • customers — массив клиентов и лидов, прикреплённых к задаче. Каждый элемент массива содержит следующие поля:
      • id — идентификатор клиента / лида
      • name — имя клиента / лида
      • status — статус клиента. Возможные значения:
        • individual — физ. лицо
        • company — компания
      • type — тип клиента. Возможные значения:
        • potential — потенциальный клиент
        • client — клиент
        • reseller — реселлер
        • partner — партнёр
      • lead_source — источник лида. Возможные значения:
        • manual — вручную
        • call_incoming — входящий звонок
        • call_outgoing — исходящий звонок
        • form — форма
      • lead_status — статус лида. Возможные значения:
        • not_processed — не обработан
        • in_progress — в обработке
        • finished — завершён
      • contact_type — тип контакта. Возможные значения:
        • customer — клиент
        • lead — лид

get /v1/zcrm/events/<event_id>

Возвращает задачу по её ID

Ответ

                                    {
  "id": 40,
  "type": "task",
  "title": "Create text for Good Company",
  "description": "",
  "start": "2020-05-26 09:00:00",
  "end": "2020-05-26 12:30:00",
  "allDay": false,
  "created_by": 234,
  "responsible_user": 234,
  "phone": "",
  "call_done": 0,
  "completed": 0,
  "completed_comment": "",
  "members": [234, 235],
  "customers": [
    {
      "id": 3486,
      "name": "Good Company",
      "status": "company",
      "type": "client",
      "lead_source": "manual",
      "lead_status": "not_processed",
      "contact_type": "customer"
    }
  ]
}

Где:

  • id — идентификатор задачи
  • type — тип задачи. Возможные значения:
    • task — задача
    • call — звонок
  • title — название задачи
  • description — описание задачи (в формате Quill Delta)
  • start — дата и время начала задачи (в формате YYYY-MM-DD hh:mm:ss)
  • end — дата и время окончания задачи (в формате YYYY-MM-DD hh:mm:ss)
  • allDay — задача на весь день (true или false)
  • created_by — идентификатор пользователя, создавшего задачу
  • responsible_user — идентификатор пользователя, ответственного за задачу
  • phone — номер телефона для звонка (если тип задачи — звонок)
  • call_done — указывает, был ли осуществлён звонок
  • completed — указывает, что задача помечена как завершённая
  • completed_comment — комментарий к завершённой задаче
  • members — массив участников задачи (только идентификаторы пользователей)
  • customers — массив клиентов и лидов, прикреплённых к задаче. Каждый элемент массива содержит следующие поля:
    • id — идентификатор клиента / лида
    • name — имя клиента / лида
    • status — статус клиента. Возможные значения:
      • individual — физ. лицо
      • company — компания
    • type — тип клиента. Возможные значения:
      • potential — потенциальный клиент
      • client — клиент
      • reseller — реселлер
      • partner — партнёр
    • lead_source — источник лида. Возможные значения:
      • manual — вручную
      • call_incoming — входящий звонок
      • call_outgoing — исходящий звонок
      • form — форма
    • lead_status — статус лида. Возможные значения:
      • not_processed — не обработан
      • in_progress — в обработке
      • finished — завершён
    • contact_type — тип контакта. Возможные значения:
      • customer — клиент
      • lead — лид

post /v1/zcrm/events

Создаёт новую задачу с указанными данными

Параметры

  • event — данные новой задачи. Структура:

(Пример 1) 

                                    Пример 1:
{
    "type": "task",
    "title": "Create text for Good Company",
    "description": "",
    "start": "2020-05-26 09:00:00",
    "end": "2020-05-26 12:30:00",
    "allDay": false,
    "responsible_user": 234,
    "phone": "",
    "members": [234, 235],
    "customers": [3486, 3487]
}

Где:

  • type — тип задачи. Допустимые значения:
    • task — задача
    • call — звонок
  • title — название задачи
  • description — описание задачи (в формате Quill Delta)
  • start — дата и время начала задачи (в формате YYYY-MM-DD hh:mm:ss)
  • end — дата и время окончания задачи (в формате YYYY-MM-DD hh:mm:ss)
  • allDay — задача на весь день (true или false)
  • responsible_user — идентификатор пользователя, ответственного за задачу
  • phone — номер телефона для звонка (если тип задачи — звонок)
  • members — массив участников задачи (только идентификаторы пользователей)
  • customers — массив прикреплённых клиентов и лидов (только идентификаторы клиентов и лидов)

Ответ

(Пример 2) 

                                    Пример 2:
{
  "id": 7216
}

Где:

  • id — идентификатор созданной задачи

put /v1/zcrm/events/<event_id>

Обновляет существующую задачу с указанным ID

Параметры

  • event — новые данные задачи. Структура:

                                    {
    "title": "Create text for Good Company",
    "description": "",
    "start": "2020-05-26 09:00:00",
    "end": "2020-05-26 12:30:00",
    "allDay": false,
    "created_by": 234,
    "responsible_user": 234,
    "phone": "",
    "members": [234, 235],
    "customers": [3486, 3487]
}

Где:

  • title — название задачи
  • description — описание задачи (в формате Quill Delta)
  • start — дата и время начала задачи (в формате YYYY-MM-DD hh:mm:ss)
  • end — дата и время окончания задачи (в формате YYYY-MM-DD hh:mm:ss)
  • allDay — задача на весь день (true или false)
  • responsible_user — идентификатор пользователя, ответственного за задачу
  • phone — номер телефона для звонка (если тип задачи — звонок)
  • members — массив участников задачи (только идентификаторы пользователей)
  • customers — массив прикреплённых клиентов и лидов (только идентификаторы клиентов и лидов)

post /v1/zcrm/events/<event_id>/close

Завершает (закрывает) задачу

Параметры

  • comment (необязательный) — комментарий

delete /v1/zcrm/events/<event_id>

Удаляет задачу по её ID

Звонки

get /v1/zcrm/calls

Возвращает список звонков

Параметры

  • search (необязательный) — строка поиска. Поиск осуществляется комбинированно по:
    • номерам телефонов
    • именам контактов (клиентов, сотрудников, лидов или пользователей)
  • filter (необязательный) — фильтр звонков. Структура фильтра:
  • take (для постраничного вывода) — сколько звонков вернуть (по умолчанию 20)
  • skip (для постраничного вывода) — сколько звонков пропустить (по умолчанию 0)

(Пример 1) 

                                    Пример 1:
{
    "user": 23,
    "type": "incoming",
    "status": "answer",
    "dateFrom": "2020-06-03 14:56:00",
    "dateTo": "2020-06-26 14:56:00"
}

Где:

  • user — пользователь (идентификатор)
  • type — тип звонка. Допустимые значения:
    • incoming — входящий звонок
    • outgoing — исходящий звонок
  • status — статус звонка. Допустимые значения:
    • answer — успешный звонок
    • noanswer — без ответа
    • cancel — отменён
    • busy — занято
    • call failed — не удался
  • dateFrom — показать только звонки, совершённые после указанного времени (формат: YYYY-MM-DD hh:mm:ss)

  • dateTo — показать только звонки, совершённые до указанного времени (формат: YYYY-MM-DD hh:mm:ss)

    Любой из параметров фильтра может быть опущен, т.е. не является обязательным.

  • sort (необязательный) — сортировка звонков. Структура параметра:

(Пример 2) 

                                    Пример 2:
{
    "attr": "time",
    "desc": 0
}

Где:

  • attr — поле сортировки. Допустимые значения:
    • phone — номер телефона
    • status — статус звонка
    • duration — длительность звонка
    • time — время звонка
  • desc — направление сортировки. Допустимые значения:
    • 0 — по возрастанию
    • 1 — по убыванию

Ответ

(Пример 3) 

                                    Пример 3:
{
  "totalCount": 233,
  "calls": [
    {
      "id": 127,
      "type": "outgoing",
      "status": "answer",
      "phone": "+74951270777",
      "user_id": 179,
      "time": "2019-07-31 17:58:40",
      "duration": 9,
      "pbx_call_id": "out_807ghh1h7f09fa7a188dbf8a6998b1c9ghg4ij06",
      "record": 1,
      "record_url_till": "2020-07-24 20:08:10",
      "contact_type": "customer",
      "contact_name": "Good Company",
      "contact_customer_id": 3486,
      "contact_employee_id": null,
      "employee_customer_id": null,
      "contact_user_id": null,
      "is_lead": 1,
      "record_urls": [
        {
          "url": "https ://api.novofon.com/v1/pbx/record/download/[...]/[...]/[...].mp3"
        }
      ]
    }
  ]
}

Где:

  • totalCount — общее кол-во звонков (с учётом строки поиска и фильтра)
  • calls — массив звонков (с учётом постраничного вывода). Каждый элемент массива содержит следующие параметры:
    • id — идентификатор звонка
    • type — тип звонка. Возможные значения:
      • incoming — входящий звонок
      • outgoing — исходящий звонок
    • status — статус звонка. Возможные значения:
      • answer — успешный звонок
      • noanswer — без ответа
      • cancel — отменён
      • busy — занято
      • failed — не удался
    • phone — телефонный номер
    • user_id — пользователь, инициировавший или принявший звонок
    • time — время звонка в формате YYYY-MM-DD hh:mm:ss
    • duration — длительность звонка в секундах
    • pbx_call_id — идентификатор звонка в АТС
    • record — включена ли запись звонка
    • record_url_till — время, до которого ссылка на запись разговора будет работать
    • contact_type — тип контакта. Возможные значения:
      • customer — клиент или лид (см. параметр is_lead)
      • employee — сотрудник клиента
      • user — пользователь
    • contact_name — имя контакта
    • contact_customer_id — идентификатор клиента или лида (если звонок связан с клиентом)
    • contact_employee_id — идентификатор сотрудника (если звонок связан с сотрудником)
    • employee_customer_id — идентификатор родительского клиента (если звонок связан с сотрудником)
    • contact_user_id — идентификатор пользователя (если звонок связан с пользователем)
    • is_lead — показывает, связан ли звонок с лидом
    • record_urls — массив записей разговора (может отсутствовать, т.к. должен быть специально запрошен). Каждый элемент массива — объект, содержащий след. поле:
      • url — ссылка на запись разговора

Файлы

get /v1/zcrm/files/<file_id>

Отдаёт файл по его ID

Система уведомлений о звонках - webhook


Система Novofon может отправлять информацию о каждом звонке в виртуальной АТС и направлять звонок на нужный внутренний номер в зависимости от ответа. Для этого необходимо создать открытую для всеобщего доступа ссылку, которая будет принимать POST-запросы с информацией из системы Novofon.

NOTIFY_START

начало входящего звонка в АТС

Параметры, которые отправляются на ссылку для уведомлений:

  • event – событие (NOTIFY_START)
  • call_start – время начала звонка;
  • pbx_call_id – id звонка;
  • caller_id – номер звонящего;
  • called_did – номер, на который позвонили.

Составление проверочной подписи для уведомления о входящих звонках, пример на PHP:

                                    $signatureTest = base64_encode(hash_hmac('sha1', 
        $_POST['caller_id'] . $_POST['called_did'] . 
        $_POST['call_start'], API_SECRET));

Для запросов NOTIFY_START и NOTIFY_IVR можно «на лету» изменять сценарий работы по текущему звонку. Для этого отправьте в ответ на вебхук один из следующих вариантов:

1. Перевести звонок:

(Пример 1) 

                                    Пример 1:
{
    "redirect": ID,
    "return_timeout": TIMEOUT (необязательное)
}

Где:

  • redirect - id сценария редиректа (в формате 0-1, где 0 - номер голосового меню, 1 - номер сценария); или в формате 1, где 1 - номер сценария(номер голосового меню в этом случае 0); или меню АТС в формате 0-main, где 0 - это id меню; или внутренний номер АТС (трехзначный номер); или "blacklist" - в этом случае звонок будет отклонен с сигналом занято;
  • return_timeout - Значение в секундах. Возможные значения:
    • 0, звонок не вернется на меню;
    • >= 3 - продолжительность звонка внутреннего номер, прежде чем звонок вернется на меню;
  • rewrite_forward_number - переадресация на номер телефона. Необязательный параметр, доступен для использования только совместно с параметром redirect. Необходим для замены "на лету" номера телефона переадресации, который указан в настройках внутреннего номера АТС.

2. Завершить звонок:

(Пример 2) 

                                    Пример 2:
{
    "hangup": 1
}

3. Задать имя входящего номера

Вы можете задать имя звонящего номера (SIP поле CallerName) и оно отразится в приложении. Таким образом удобно передать имя звонящего, если его номер есть в вашей системе.

(Пример 3) 

                                    Пример 3:
{
    "caller_name": NAME
}

Где:

  • caller_name - имя номера.

В каждом из следующих вариантов ниже (номера 4-7) может присутствовать ответ от абонента в виде цифр. Параметры ввода цифр:

(Пример 4) 

                                    Пример 4:
{
    "wait_dtmf": {
        "timeout": TIMEOUT,
        "attempts": ATTEMPTS,
        "maxdigits": MAXDIGITS,
        "name": NAME,
        "default": DEFAULT,
    }
}

Где:

  • timeout - время ожидания ввода цифр в секундах;
  • attempts - количество попыток набора цифры от абонента;
  • maxdigits - максимальное количество цифр, ввода которых дожидаться;
  • name - имя, которое будет возвращено в ответе;
  • default - действие, если не было набрано ни одной цифры. Возможные значения:
    • id сценария редиректа (в формате 0-1, где 0 - номер голосового меню, 1 - номер сценария);
    • меню АТС в формате 0-main, где 0 - это id меню;
    • внутренний номер АТС (трехзначный номер);
    • hangup - закончить звонок.

4. Воспроизвести файл:

(Пример 5) 

                                    Пример 5:
{
    "ivr_play": "ID"
}

Где:

  • ivr_play – значение из колонки ID в списке загруженных/начитанных файлов для нужного файла.

5. Воспроизвести популярную фразу:

(Пример 6) 

                                    Пример 6:
{
    "ivr_saypopular": 1,
    "language": "ru"
}

Где:

  • ivr_saypopular – номер фразы из списка;

Списки популярных фраз:

  • Здравствуйте
  • Добрый день
  • Переадресация
  • Звонок с сайта
  • Добро пожаловать
  • Тестовое сообщение
  • Оставайтесь на линии
  • Вы позвонили в нерабочее время
  • Сейчас все менеджеры заняты, вам ответит первый освободившийся оператор.
  • Наберите внутренний номер абонента
  • Наберите внутренний номер сотрудника
  • Наберите добавочный номер
  • Пожалуйста ожидайте
  • Наберите внутренний номер или дождитесь ответа оператора
  • Пожалуйста оставьте сообщение
  • Оставьте ваше сообщение после сигнала
  • Перезвоните пожалуйста в рабочее время
  • Благодарим за обращение в нашу компанию.
  • Спасибо за звонок.
  • Ожидайте ответа оператора
  • Ваш звонок очень важен для нас
  • Разговор записывается
  • В данный момент нас нет в офисе
  • Мы перезвоним вам при первой возможности
  • Сегодня у нас выходной.

6. Воспроизвести цифры:

(Пример 7) 

                                    Пример 7:
{
    "ivr_saydigits": "12",
    "language": "ru"
}

7. Воспроизвести число (в соответствии с правилами сложных числительных):

(Пример 8) 

                                    Пример 8:
{
    "ivr_saynumber": "123",
    "language": "ru"
}

Где:

  • language может принимать одно из значений: ru, en, es, pl;

Если были указаны ivr_saydigits или ivr_saynumber, в следующем событии NOTIFY_IVR будет добавлен параметр: "ivr_saydigits": "COMPLETE" или "ivr_saynumber": "COMPLETE"

В следующем событии NOTIFY_IVR будет дополнительно указан параметр:

(Пример 9) 

                                    Пример 9:
{
    "wait_dtmf": {
        "name": NAME,
        "digits": DIGITS,
        "default_behaviour": "1"
    }
}

Где:

  • name - имя, указанное в предыдущем ответе;
  • digits - цифры, введенные абонентом;
  • default_behaviour - указано, если абонент ничего не нажал и сработало поведение по умолчанию;

NOTIFY_INTERNAL

начало входящего звонка на внутренний номер АТС

Параметры, которые отправляются на ссылку для уведомлений:

  • event – событие (NOTIFY_INTERNAL)
  • call_start – время начала звонка;
  • pbx_call_id – id звонка;
  • caller_id – номер звонящего;
  • called_did – номер, на который позвонили;
  • internal – (опциональный) внутренний номер.
  • transfer_from – (опциональный) инициатор трансфера, внутренний номер.
  • transfer_type – (опциональный) тип трансфера.

Составление проверочной подписи для уведомления о входящих звонках, пример на PHP:

                                    $signatureTest = base64_encode(hash_hmac('sha1', 
        $_POST['caller_id'] . $_POST['called_did'] . 
        $_POST['call_start'], API_SECRET));

NOTIFY_ANSWER

ответ при звонке на внутренний или на внешний номер

Параметры, которые отправляются на ссылку для уведомлений:

  • event – событие (NOTIFY_ANSWER)
  • caller_id – номер звонящего;
  • destination – номер, на который позвонили;
  • call_start – время начала звонка;
  • pbx_call_id – id звонка;
  • internal – (опциональный) внутренний номер.
  • transfer_from – (опциональный) инициатор трансфера, внутренний номер.
  • transfer_type – (опциональный) тип трансфера.

Составление проверочной подписи для уведомления о входящих звонках, пример на PHP:

                                    $signatureTest = base64_encode(hash_hmac('sha1', 
        $_POST['caller_id'] . $_POST['destination'] . 
        $_POST['call_start'], API_SECRET));

NOTIFY_END

конец входящего звонка на внутренний номер АТС

Параметры, которые отправляются на ссылку для уведомлений:

  • event – событие (NOTIFY_END);
  • call_start – время начала звонка;
  • pbx_call_id – id звонка;
  • caller_id – номер звонящего;
  • called_did – номер, на который позвонили;
  • internal – (опциональный) внутренний номер;
  • duration – длительность в секундах;
  • disposition – состояние звонка:
    • answered – разговор,
    • busy – занято,
    • cancel - отменен,
    • no answer - без ответа,
    • failed - не удался,
    • no money - нет средств, превышен лимит,
    • unallocated number - номер не существует,
    • no limit - превышен лимит,
    • no day limit - превышен дневной лимит,
    • line limit - превышен лимит линий,
    • no money, no limit - превышен лимит;
  • last_internal – внутренний номер, последний участник звонка (после трансфера или перехвата);
  • status_code – код статуса звонка Q.931;
  • is_recorded – 1 - есть запись звонка, 0 - нет записи;
  • call_id_with_rec – id звонка с записью (рекомендуем загружать файл записи не ранее чем через 40 секунд после уведомления т.к. для сохранения файла записи нужно время).

Составление проверочной подписи для уведомления о входящих звонках, пример на PHP:

                                    $signatureTest = base64_encode(hash_hmac('sha1', 
        $_POST['caller_id'] . $_POST['called_did'] . 
        $_POST['call_start'], API_SECRET));

NOTIFY_OUT_START

начало исходящего звонка с АТС

Параметры, которые отправляются на ссылку для уведомлений:

  • event – событие (NOTIFY_OUT_START);
  • call_start – время начала звонка;
  • pbx_call_id – id звонка;
  • destination – номер, на который позвонили;
  • caller_id – номер, настроенный на внутреннем номере АТС или установленный в правилах набора по направлениям. Если номер не установлен, то передается 0;
  • internal – (опциональный) внутренний номер.

Составление проверочной подписи для уведомления о входящих звонках, пример на PHP:

                                    $signatureTest = base64_encode(hash_hmac('sha1', 
        $_POST['internal'] . $_POST['destination'] . 
        $_POST['call_start'], API_SECRET));

NOTIFY_OUT_END

конец исходящего звонка с АТС

Параметры, которые отправляются на ссылку для уведомлений:

  • event – событие (NOTIFY_OUT_END)
  • call_start – время начала звонка;
  • pbx_call_id – id звонка;
  • caller_id – номер, настроенный на внутреннем номере АТС или установленный в правилах набора по направлениям. Если номер не установлен, то передается 0;
  • destination – номер, на который позвонили;
  • internal – (опциональный) внутренний номер;
  • duration – длительность в секундах;
  • disposition – состояние звонка:
    • answered – разговор,
    • busy – занято,
    • cancel - отменен,
    • no answer - без ответа,
    • failed - не удался,
    • no money - нет средств, превышен лимит,
    • unallocated number - номер не существует,
    • no limit - превышен лимит,
    • no day limit - превышен дневной лимит,
    • line limit - превышен лимит линий,
    • no money, no limit - превышен лимит;
  • status_code – код статуса звонка Q.931;
  • is_recorded – 1 - есть запись звонка, 0 - нет записи;
  • call_id_with_rec – id звонка с записью (рекомендуем загружать файл записи не ранее чем через 40 секунд после уведомления т.к. для сохранения файла записи нужно время).

Составление проверочной подписи для уведомления о входящих звонках, пример на PHP:

                                    $signatureTest = base64_encode(hash_hmac('sha1', 
        $_POST['internal'] . $_POST['destination'] . 
        $_POST['call_start'], API_SECRET));

NOTIFY_RECORD

запись звонка готова для скачивания

Параметры, которые отправляются на ссылку для уведомлений:

  • event – событие(NOTIFY_RECORD);
  • call_id_with_rec – уникальный id звонка с записью разговора;
  • pbx_call_id – постоянный ID внешнего звонка в АТС (не меняется при прохождении сценариев, голосового меню, transfer и т.д., отображается в статистике и уведомлениях).

Составление проверочной подписи для уведомления о входящих звонках, пример на PHP:

                                    $signatureTest = base64_encode(hash_hmac('sha1', 
        $_POST['pbx_call_id'] . $_POST['call_id_with_rec'], API_SECRET));

NOTIFY_IVR

ответ абонента на заданное действие

Параметры, которые отправляются на ссылку для уведомлений:

  • event – событие (NOTIFY_IVR);
  • call_start – время начала звонка;
  • pbx_call_id – id звонка;
  • caller_id – номер звонящего;
  • called_did – номер, на который позвонили.

Составление проверочной подписи для уведомления о входящих звонках, пример на PHP:

                                    $signatureTest = base64_encode(hash_hmac('sha1', 
        $_POST['caller_id'] . $_POST['called_did'] . 
        $_POST['call_start'], API_SECRET));

Возможные отправляемые ответы аналогичны ответам запросов NOTIFY_START

Пример на PHP: 

                                    <?php if (isset($_GET['zd_echo'])) exit($_GET['zd_echo']); ?>

Для увеличения безопасности, рекомендуем разрешить доступ к вашей ссылке только с IP 185.45.152.42.

Также, если Вы выпустили ключи для доступа к API, в каждом запросе на Вашу ссылку будет приходить дополнительный заголовок "Signature", по которому также сможете сверять целостность, а также подлинность данных.

Другие уведомления


Параметр "result" в этих уведомлениях задан в JSON формате. Вы можете получить его в XML формате, указав в ссылке параметр format=xml.

NUMBER_LOOKUP

отчет о проверке номеров

Параметры, которые отправляются на ссылку для уведомлений:

  • event – событие (NUMBER_LOOKUP);
  • success – флаг успешности проверки;
  • description – текстовое описание статуса завершения проверки;
  • result – массив;
    • number – проверяемый номер;
    • mcc – мобильный код страны;
    • mnc – код мобильной сети;
    • ported – признак переноса к другому оператору;
    • roaming – признак нахождения в роуминге;
    • error – статус ошибки;
    • errorDescription – текстовое описание ошибки;
    • mccName – название страны;
    • mncName – название оператора;

Составление проверочной подписи:

$signatureTest = base64_encode(hash_hmac('sha1', $_POST['result'], API_SECRET));

CALL_TRACKING

информацию о звонках на номера, подключенные к коллтрекингу

Отправляется раз в 8 минут, при наличии новых звонков.

Параметры, которые отправляются на ссылку для уведомлений:

  • event – событие (CALL_TRACKING)
  • result - массив
    • tracker - ID трекера (можно узнать на странице установки кода);
    • start - время начала звонка;
    • duration - длительность звонка в секундах;
    • caller_id - номер звонящего;
    • caller_did - номер, на который позвонили;
    • source - название источника посетителя;
    • country - (опционально) страна, из которой был совершен звонок;
    • ga_id - (опционально, если в настройках указан Id Google Analytics) id посетителя в Google Analytics;
    • metrika_id - (опционально, еcли в настройках указан Id Yandex.Metrika) id посетителя в Yandex.Metrika;
    • url - адрес страницы, с которой был звонок;
    • utm_source, utm_medium, utm_campaign, utm_term, utm_content - (опционально, если при переходе на сайт были указаны utm метки) utm метки, по которым посетитель перешел на сайт в последний раз;
    • first_utm - (опционально, если при первом переходе на сайт были указаны utm метки, отличные от тех, по которым произведен переход в последний раз) массив с utm метками указанными выше, по которым посетитель перешел на сайт в первый раз;
    • pbx_call_id - id звонка (кроме Toll Free).

Составление проверочной подписи:

$signatureTest = base64_encode(hash_hmac('sha1', $_POST['result'], API_SECRET));

SMS

информацию о входящих SMS

Параметры, которые отправляются на ссылку для уведомлений:

  • event – событие (SMS)
  • result – массив;
    • caller_id – номер отправителя;
    • caller_did – номер получателя;
    • text – текст сообщения.

Составление проверочной подписи:

$signatureTest = base64_encode(hash_hmac('sha1', $_POST['result'], API_SECRET));

SPEECH_RECOGNITION

результат распознавания голоса

Параметры, которые отправляются на ссылку для уведомлений:

  • event – событие (SPEECH_RECOGNITION)
  • lang – язык;
  • call_id – уникальный id звонка, этот id указан в названии файла с записью разговора;
  • pbx_call_id – постоянный ID внешнего звонка в АТС;
  • voicemail – опционально, если запись является сообщением на голосовую почту;
  • result:
    • words - массив:
      • result - список слов (массив):
        • s - время начала слова
        • e - время окончания слова
        • w - слово
      • channel - номер канала
    • phrases - массив:
      • result - фраза
      • channel - номер канала

Задать ссылку по которой уведомлять, а также включить/выключить каждый вид уведомлений вы можете в разделе API личного кабинета.

Для того, чтобы система приняла ссылку, необходимо добавить проверочный код вначале скрипта.