Навігація по API

Вступ

В API доступні всі основні функції для роботи з:

  • Телефонія і віртуальні номери
  • АТС та ZCRM
  • SMS та HLR-запити
  • Колтрекінг
  • Розпізнавання мови
Посилання на API https://api.zadarma.com
Версія API: v1
Фінальне посилання на метод: https://api.zadarma.com/v1/METHOD/
Скачайте готові класи PHP, C#, Python для роботи з API на нашому GitHub.
Приклади роботи з API:
Інтеграція власної CRM і телефонії Zadarma
Безкінечний динамічний IVR
Створення ліда в ZCRM з форми на сайті

Авторизація

Кожен запит, який потребує авторизації, супроводжується додатковим заголовком, виду:

"Authorization: ключ_користувача: підпис"

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

Підпис складається за наступним алгоритмом:

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

Готовий клас PHP для роботи з API, можете скачати на GitHub.

Формати відповіді: 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 запитів в хвилину, на методи статистики - 10 запитів в хвилину.

У разі блокування, метод віддає відповідь з 429 заголовком "You exceeded the rate limit".

Відповідь складається з обов'язкового ключа "status" (success или error). Далі, в залежності від методу, віддаються свої ключі з інформацією, яка запитується.

У разі помилки, віддається додатковий ключ "message" з описом помилки.

Також, усі відповіді супроводжуються відповідними HTTP-заголовками.

Методи

get /v1/info/balance/

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

баланс користувача

get /v1/info/price/

                                        {
    "status":"success",
    "info":{
    "prefix":"4420",
        "description":"United Kingdom, London",
        "price":"0.009",
        "currency":"USD",
    }
}
                                    

вартість дзвінка з урахуванням поточного тарифу користувача

Параметри:

  • 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":USD,
        "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 – кількість використаних секунд тарифу на стаціонарні телефони;
  • tariff_id_for_next_period – ID тарифу користувача на наступний період;
  • tariff_for_next_period – найменування тарифу користувача на наступний період.

get /v1/request/callback/

                                        {
    "status":"success", 
    "from":442037691880, 
    "to":442037691881, 
    "time":1435573082
}
                                    

callback

Параметри:

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

post /v1/sms/send/

                                        {
    "status":"success",
    "messages":1,
    "cost":0.24,
    "currency":"USD"
}
                                    

відправка SMS

Параметри:

  • number – номер телефону, куди відправляти SMS (можна перерахувати кілька через кому);
  • message – повідомлення (стандартні обмеження за довжиною SMS, у разі перевищення ліміту - розбивається на кілька SMS);
  • caller_id – (опціональний) номер телефону, від кого буде відправлена SMS (можна відправляти тільки зі списку підтверджених номерів користувача).

Зверніть увагу:відправка SMS можлива тільки за межі РФ.

post /v1/info/number_lookup/

                                        Response 1:
{ "status":"success", "info":{ "mcc":"250", "mnc":"01", "mccName":"Russia", "mncName":"Mobile TeleSystems", "ported":false, "roaming":false, "errorDescription":"No Error" } }
                                        Response 2:
{ "status":"success" }
                                        Response 3:
{ "success":true, "description":"Success", "result": [ { "mcc":"250", "mnc":"01", "ported":false, "roaming":false, "errorDescription":"No Error", "mccName":"Russia", "mncName":"Mobile TeleSystems", "number":"791234567890", }, ... ] }

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

Параметри:

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

Якщо numbers містить 1 номер, результат буде повернений одразу, якщо вказано список номерів, результат буде відправлений за адресою, вказаною на сторінці актуалізації контактів, або відправлений на email, якщо адреса не задана.

Зверніть увагу: налаштування даного методу здійснюються на сторінці актуалізації номерів в особистому кабінеті.

Приклад відповіді для 1 номеру:

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

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

SIP

get /v1/sip/

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

список SIP-номерів користувача

де

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

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

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

online-статус SIP-номерів користувача

put /v1/sip/callerid/

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

зміна CallerID

Параметри:

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

get /v1/sip/redirection/

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

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

Параметри:

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

де

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

put /v1/sip/redirection/

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

включення / вимикання переадресації за номером SIP

Параметри:

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

put /v1/sip/redirection/

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

зміна параметрів переадресації

Параметри:

  • id – SIP id;
  • type – тип переадресації: phone – на телефон;
  • number – номер телефону.

Статистика

get /v1/statistics/

                                        Response 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":442037691880, "to":442037691881, "description":"United Kingdom, London", "disposition":"busy", "billseconds":0, "cost":0.1950, "billcost":0.0000, "currency":"USD" }, … ] }
                                        Response 2:
{ "status":"success", "start":"2015-06-01 00:00:00", "end":"2015-06-29 14:03:57", "stats":[ { "cost":38.094, "currency":"USD", "seconds":9785 } ] }

отримання загальної статистики

Параметри:

  • 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) - кількість рядків, які необхідно пропустити у вибірці перед початком запиту (використовується для пагінації спільно з параметром limit, за замовчуванням дорівнює 0);
  • type (опціонально - не враховується при заданому параметрі cost_only) - обмеження на кількість виведених рядків (використовується для пагінації спільно з параметром skip, максимальне значення 1000, за замовчуванням 1000).

Максимальный период отримання статистики - місяць. У разі перевищення ліміту в запиті - період автоматично скорочується до 30 днів. Якщо не вказано дату початку вибірки, вибирається початок поточного місяця. Якщо не вказано дату кінця вибірки - вибірка обмежується поточною датою і часом. Максимальна кількість виведених рядків для одного запиту - 1000. Для пагінації використовуйте параметри skip і limit.

?type=cost_only: (Response 2)

де

  • start – дата початку відображення статистики;
  • end – дата завершення відображення статистики;
  • id – id дзвінка;
  • sip – SIP-номер;
  • callstart – час початку дзвінка;
  • description – опис напрямку дзвінка;
  • disposition – стан дзвінка:
    • 'answered' – розмова,
    • 'busy' – зайнято,
    • 'cancel' - скасовано,
    • 'no answer' - без відповіді,
    • '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"
        },
        …
    ]
}
                                    

статистика за АТС

Параметри:

  • 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' - без відповіді,
    • '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"
                }
            ]
        },
        ...
    ]
}
                                    

статистика за віджетом зворотнього дзвінка

json_0 xml_0

Параметри:

  • 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/pbx/internal/

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

відображення внутрішніх номерів АТС

де

  • pbx_id – id ATC користувача;
  • numbers – список внутрішніх номерів.

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

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

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

де

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

put /v1/pbx/internal/recording/

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

увімкнення запису розмов на внутрішньому номері АТС

Параметри:

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

get /v1/pbx/record/request/

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

запит на файл запису розмови

Параметри:

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

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

Приклад відповіді коли зазначено тільки call_id, посилання тільки одне:

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

Параметри:

  • link – посилання на файл розмови;
  • lifetime_till – до якого часу посилання буде працювати.

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/speech_recognition/

                                        {        
    "status":"success",
    "lang":"en-EN",
    "recognitionStatus":"in progress",
    "otherLangs":["es-ES"],
    "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 – унiкальний id дзвiнка, цей id вказано в назві файлу із записом розмови (унікальний для кожного запису в статистиці);
  • lang - мова розпізнавання (не обов'язково);
  • return - результат, що повертається. Варіанти: words - слова, phrases - фрази. (не обов'язково. за замовчуванням phrases);
  • alternatives - чи повертати альтернативні варіанти. Варіанти: 0 - нi, 1 - так. (не обов'язково. за замовчуванням 0).

де

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

put /v1/speech_recognition/

                                        {
    "status":"success"
}
                                    

запуск розпізнавання

Параметри:

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

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

get /v1/direct_numbers/

                                        {
    "status":"success",
    "info": [
        {
            "number":"442037691880",
            "status":"on",
            "country":"Great Britain",
            "description":"London",
            "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":USD,
            "channels":2,
            "autorenew":"true",
            "is_on_test":"false",
            "type":"common"
        },
    ...
    ]
}
                                    

інформація про віртуальні номери користувача

Параметри:

Залежно від типу номеру набір полів може відрізнятися! Опис полів:

  • number – куплений віртуальний номер користувача;
  • status – статус номеру;
  • 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 (віртуальний номер), inum (безкоштовний міжнародний номер), rufree (безкоштовний московський номер), revenue (безкоштовний московський номер 495).

get /v1/direct_numbers/number/

                                        {
    "status": "success",
    "info": {
    "number": "35924913550",
        "status": "on",
        "country": "Bulgaria",
        "description": "Sofia",
        "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": "USD",
        "channels": "2",
        "autorenew": "true",
        "receive_sms": null,
        "is_on_test": "false"
    }
}
                                    

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

Параметри

  • type - може мати одне з 3-х значень:
    • 'revenue' - Безкоштовний московський номер 495;
    • 'inum' - Безкоштовний міжнародний номер;
    • 'common' - Звичайний номер, всі інші;
  • number - номер.

get /v1/direct_numbers/autoprolongation/

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

статус автоподовження (NB! inum не входить в цей список)

Параметри

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

put /v1/direct_numbers/autoprolongation/

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

змінити статус автоподовження (NB! inum не входить в цей список)

Параметри:

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

get /v1/direct_numbers/countries/

                                        {
    "status": "success",
    "info": [
        {
            "countryCode": "61",
            "countryCodeIso": "AU",
            "name": "Australia"
        },
        ...
    ]
}
                                    

список країн, в яких можна замовити номер

Параметри:

  • language - опціонально, якщо не задано видасть на мові особистого кабінету.

get /v1/direct_numbers/country/

                                        {
    "status": "success",
    "info": [
        {
            "id": "3753",
            "countryCode": "49",
            "areaCode": "800",
            "name": "Номер 800 (Toll-free)",
            "connect_fee": 0,
            "monthly_fee": 15,
            "currency": "USD",
            "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": "49",
            "areaCode": "821",
            "name": "Аугсбург",
            "connect_fee": 3,
            "monthly_fee": 3,
            "currency": "USD",
            "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).

put /v1/direct_numbers/set_caller_name/

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

встановлення caller name

Параметри

  • type - може мати одне з 2-х значень:
    • 'revenue' - Безкоштовний московський номер 495;
    • 'common' - Звичайний номер, всі інші;
  • number - номер;
  • caller_name - для того щоб прибрати - просто передати порожнє поле.

put /v1/direct_numbers/set_sip_id/

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

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

Параметри

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

Методи ZCRM

Клієнти

get /v1/zcrm/customers

Повертає список клієнтів

Параметри

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

Відповідь 1

Відповідь 1:
{ "status": "company", "type": "client", "country": "GB", "city": "London", "label": 12, "employees_count": "50", "responsible": 20 }

де:

  • status — статус клієнта. Допустимі значення:
    • individual — фіз. особа
    • company — компанія
  • type — тип клієнта. Допустимі значення:
    • potential — потенційний клієнт
    • client — клієнт
    • reseller — реселлер
    • partner — партнер
  • country — країна клієнта. Код з двох літер (RU, US і т.і.)
  • city — місто клієнта (рядок)
  • label — тег (ідентифікатор)
  • 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": "GB", "city": "London", "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": "+44123456789" } ], "contacts": [ { "type": "email_work", "value": "good_company@example.com" } ], "labels": [ { "id": 12, "label": "Best clients" } ] } ] }

де:

  • 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 — значення тега

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": "GB", "city": "London", "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": "+44123456789" } ], "contacts": [ { "type": "email_work", "value": "good_company@example.com" } ], "labels": [ { "id": 12, "label": "Best clients" } ], "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 — значення тега
  • 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": "GB", "city": "London", "address": "", "zip": "", "website": "", "lead_source": "manual", "phones": [ { "type": "work", "phone": "+44123456789" } ], "contacts": [ { "type": "email_work", "value": "good_company@example.com" } ], "labels": [ { "id": 12 }, { "id": 13 } ], "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 — ідентифікатор існуючого тега
  • 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": "GB", "city": "London", "address": "", "zip": "", "website": "", "lead_source": "manual", "phones": [ { "type": "work", "phone": "+44123456789" } ], "contacts": [ { "type": "email_work", "value": "good_company@example.com" } ], "labels": [ { "id": 12 }, { "id": 13 } ], "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 — ідентифікатор існуючого тега
  • custom_properties — масив додаткових властивостей. Кожен елемент повинен містити:
    • id — ідентифікатор додаткової властивості або:
    • key — унікальне ім'я додаткової властивості
    • value — значення додаткової властивості

delete /v1/zcrm/customers/<c_id>

Видаляє клієнта за його ID

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

  • c_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": "John Beam", "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": "John Beam", "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": "Steven Knight", "position": "manager", "position_title": "", "comment": "", "phones": [ { "type": "work", "phone": "+44123456789" } ], "contacts": [ { "type": "email_work", "value": "s.knight@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": "Steven Knight", "position": "manager", "position_title": "", "comment": "", "phones": [ { "type": "work", "phone": "+44123456789" } ], "contacts": [ { "type": "email_work", "value": "s.knight@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": "Steven Knight", "position": "manager", "position_title": "", "comment": "", "phones": [ { "type": "work", "phone": "+44123456789" } ], "contacts": [ { "type": "email_work", "value": "s.knight@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": "Steven Knight", "position": "manager", "position_title": "", "comment": "", "phones": [ { "type": "work", "phone": "+44123456789" } ], "contacts": [ { "type": "email_work", "value": "john@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/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>

Завершує (закриває) завдання

Параметри

  • comment (необов'язково) — коментар

delete /v1/zcrm/events/<event_id>

Видаляє завдання за його ID

Ліди

get /v1/zcrm/leads

Повертає список лідів

Параметри

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

Відповідь 1

Відповідь 1:
{ "source": "call_incoming", "responsible": 32, "label": 12, "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 — тег (ідентифікатор)
  • 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": "GB", "city": "London", "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": "+44123456789" } ], "contacts": [ { "type": "email_work", "value": "good_company@example.com" } ], "labels": [ { "id": 22, "label": "Best clients" } ] } ] }

де:

  • 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 — значення тега

get /v1/zcrm/leads/<lead_id>

Повертає лід за його ID

Відповідь

Відповідь

Відповідь:
{ "id": 3486, "name": "Good Company", "responsible_user_id": 234, "employees_count": "50", "comment": "", "country": "GB", "city": "London", "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": "+44123456789" } ], "contacts": [ { "type": "email_work", "value": "good_company@example.com" } ], "labels": [ { "id": 22, "label": "Лучшие клиенты" } ], "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 — значення тега

post /v1/zcrm/leads

Створює новий лід із зазначеними даними

Параметри

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

Відповідь 1

Відповідь 1:
{ "name": "Good Company", "responsible_user_id": 234, "employees_count": "50", "comment": "", "country": "GB", "city": "London", "address": "", "zip": "", "website": "", "lead_source": "manual", "lead_status": "in_progress", "phones": [ { "type": "work", "phone": "+44123456789" } ], "contacts": [ { "type": "email_work", "value": "good_company@example.com" } ], "labels": [ { "id": 22 }, { "id": 23 } ], "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 — ідентифікатор існуючого тега
  • 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": "GB", "city": "London", "address": "", "zip": "", "website": "", "lead_source": "manual", "lead_status": "in_progress", "phones": [ { "type": "work", "phone": "+44123456789" } ], "contacts": [ { "type": "email_work", "value": "good_company@example.com" } ], "labels": [ { "id": 22 }, { "id": 23 } ], "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 — ідентифікатор існуючого тега
  • 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": "John Beam", "group_id": 653, "is_superadmin": 1, "enabled": 1, "created_at": "2020-04-27 01:01:31", "avatar": 2457, "role": "", "status": "", "language": "en", "color": "220", "color_hex": "5678BD", "internal_number": "100", "timezone": "Europe/London", "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": "John Beam", "group_id": 653, "is_superadmin": 1, "enabled": 1, "created_at": "2020-04-27 01:01:31", "avatar": 2457, "role": "", "status": "", "language": "en", "color": "220", "color_hex": "5678BD", "internal_number": "100", "timezone": "Europe/London", "first_day": 1, "device": "webphone", "phone_widget_location": "right", "phones": [ { "phone": "+44123456789", "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/calls

Повертає список дзвінків

Параметри

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

Відповідь 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 — зайнято
    • 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 — за зменшенням
  • take (для посторінкового виведення) - скільки дзвінків повернути (за замовчуванням 20)
  • skip (для посторінкового виведення) - скільки дзвінків пропустити (за замовчуванням 0)

Відповідь

Відповідь 3

Відповідь 3:
{ "totalCount": 233, "calls": [ { "id": 127, "type": "outgoing", "status": "answer", "phone": "+44123456789", "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.zadarma.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 — ідентифікатор дзвінка в АТС Zadarma
    • 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/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": "+44123456789", "type": "work" }, "responsible": { "id": 234, "name": "John Beam", "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": "Michael Simpson", "phone": { "phone": "+44123456789", "type": "work" }, "position": { "position": "manager", "title": "" }, "customer": { "id": 3486, "name": "Good Company" }, "responsible": { "id": 234, "name": "John Beam", "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": "+44123456789", "type": "work" }, "responsible": { "id": 234, "name": "John Beam", "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": "John Beam", "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": "+44123456789", "type": "work" }, "responsible": { "id": 234, "name": "John Beam", "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": "Michael Simpson", "phone": { "phone": "+44123456789", "type": "work" }, "position": { "position": "manager", "title": "" }, "customer": { "id": 3486, "name": "Good Company" }, "responsible": { "id": 234, "name": "John Beam", "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": "+44123456789", "type": "work" }, "responsible": { "id": 234, "name": "John Beam", "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": "John Beam", "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/files/<file_id>

Віддає файл за його ID

Інформація про вхідні дзвінки

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

Доступні методи

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:
{ "ivr_play": "ID" }

де,

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

Відтворити популярну фразу:

Відповідь 2

Відповідь 2:
{ "ivr_saypopular": 1, "language": "en" }

де,

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

Відтворити цифри:

Відповідь 3

Відповідь 3:
{ "ivr_saydigits": "12", "language": "en" }

Відтворити число (відповідно до правил складних числівників):

Відповідь 4

Відповідь 4:
{ "ivr_saynumber": "123", "language": "en" }

де,

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

Якщо були вказані ivr_saydigits або ivr_saynumber, в наступній події NOTIFY_IVR буде додано параметр: "ivr_saydigits": "COMPLETE" або "ivr_saynumber": "COMPLETE"

У кожному із зазначених запитів вище може бути присутнім запит введення цифр від абонента:

Відповідь 5

Відповідь 5:
{ "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 - закінчити дзвінок.

У наступній події NOTIFY_IVR буде додатково вказано параметр:

Відповідь 6

Відповідь 6:
{ "wait_dtmf": { "name": NAME, "digits": DIGITS, "default_behaviour": "1" } }

де,

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

Перевести дзвінок:

Відповідь 7

Відповідь 7:
{ "redirect": ID, "return_timeout": TIMEOUT (необязательное) }

де,

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

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

Завершити дзвінок:

Відповідь 8

Відповідь 8:
{ "hangup": 1 }

У кожній з відповідей можна додатково вказати:

Задати ім'я для імені вхідного номеру:

Відповідь 9

Відповідь 9:
{ "caller_name": NAME }

де,

  • caller_name - ім'я номеру.

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

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

NOTIFY_INTERNAL

початок вхідного дзвінка на внутрішній номер АТС

Параметри, які відправляються на посилання для повідомлень:

  • event – подія (NOTIFY_INTERNAL)
  • call_start – час початку дзвінка;
  • pbx_call_id – id дзвінка;
  • caller_id – вхідний номер;
  • called_did – номер, на який подзвонили;
  • internal – (опціональний) внутрішній номер.

Складання перевірочного підписи для сповіщення про вхідні дзвінки, приклад на 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 – (опціональний) внутрішній номер.

Складання перевірочного підписи для сповіщення про вхідні дзвінки, приклад на 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' - перевищено ліміт;
  • 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;
  • caller_id – вхідний номер;
  • 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' - перевищено ліміт;
  • last_internal – внутрішній номер, останній учасник дзвінка (після трансферу або перехоплення);
  • 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

SPEECH_RECOGNITION

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

Параметри, які відправляються на посилання для повідомлень:

  • event – подiя (SPEECH_RECOGNITION)
  • lang – мова;
  • result:
    • words - масив:
      • result - список слiв (масив):
        • s - час початку слова
        • e - час скiнчення слова
        • w - слово
      • channel - номер каналу
    • phrases - масив:
      • result - фраза
      • channel - номер каналу

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

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

Приклад на PHP:

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

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

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

Приклад скрипта можливо подивитися на нашому репозиторії наGitHub.

Інші повідомлення

Параметр "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

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

Відправляється раз на 15 хвилин, при наявності нових дзвінків.

Параметри, які відправляються на посилання для повідомлень:

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

Складання перевірочного підпису:

$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));