× Сокращения: Важные моменты Советы Параметры: Личные параметры Идентификатор Параметры звонка Параметры РК Примеры: Пример заказа звонка Отложенный звонок Поле site IVR IVR и utm-метки Метод API orderCall Данные пользователя Статистика по звонкам Форматы ответов: Успешный звонок Форматы ошибок Ответ в JSON Возможные статусы по звонку api.callkeeper.ru: Методы Создание виджета

Использование HTTPS REST API CallKeeper

CallKeeper API — возможность заказывать звонки посредством запросов к серверу CallKeeper в режиме REST-сервиса.

Сокращения:

Важные моменты:

Советы по использованию и возможности:

Описание всех возможных параметров для заказа звонка:

Примечание: отмеченные * поля являются обязательными.

Личные параметры:

Примечание: все нижеперечисленные ключи являются обязательными.

* unique — название компании, любая число-буквенная строка без спецсимволов

* apiak — ключ сгенерированный в ЛК во вкладке Профиль

* calls — массив параметров звонков

Идентификатор виджета в системе CallKeeper

Примечание: хотя бы один из двух параметров должен быть передан.

* whash — hash виджета, из которого будут взяты необходимые параметры для звонка, можно получить на странице редактирования виджета в ЛК

* walias — ключ для сопоставления внешнего сервиса с виджетом CallKeeper

Параметры звонка:

Примечание: для создания звонка обязательным является только client.

client — номер телефона клиента, на который поступит звонок

manager — номер телефона компании, на который поступит звонок, либо порядковый номер офиса, указанного в настройках виджета (важно: нумерация начинается с 0)

text_to_manager — произвольный текст, который будет проговариваться в начале каждого звонка

info_to_manager — дополнительный текст, который будет проговариваться только при нажатии кнопки на телефоне (указана в настройках виджета)

external_service_identifier — идентификатор внешнего сервиса

time_to_call — заказ отложенного звонка, передается желаемое время звонка в формате Timestamp

site — название сайта, которое будет отображено в информации о звонке.

utc — временная зона в формате IANA Time Zone Database(Europe/Moscow) или в формате ±hhmm("UTC+03:00")

notification — email для уведомлений о статусе звонка

ga_client_id — уникальный идентификатор пользователя для отправки в Google Analytics

tool_name — название инструмента с которого был заказан звонок

ip_client — ip адрес клиента

client_email — email клиента

calltouch_session_id — идентификатор сессии Calltouch. С помощью него Calltouch присвоит переданной заявке источник перехода на сайт посетителя, отправившего ее

comagic_session_id — уникальный идентификатор сессии звонка в Comagic

roistat_id — это уникальный номер посещения Roistat

current_page — страница с которой был заказан звонок

record_to_manager — заранее записанное сообщение, которое проговорится менеджеру

record_to_await — заранее записанное сообщение, которое проговорится менеджеру после инициации вызова в сторону клиента

office_name — наименование офиса из которого поступил звонок

opening_hours — время работы компании (время когда можно принимать звонки от клиентов).

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

Если время работы разное, указывается в формате 09001800100018000900200009001800090018000900180000000000

Если в какой-то из дней компания не работает, время работы для этого дня указывается 00000000

Параметры рекламной кампании:

utm_source — источник перехода по рекламе

utm_medium — тип трафика

utm_campaign — обозначение рекламной кампании

utm_content — содержание кампании

utm_term — условие поиска кампании

entry_point — адрес перехода пользователя

user_agent — название и версия Браузера и ОС клиента

utm_type — тип перехода

typein — прямой заход

referral — реферальный. Если необходимо передать сайт, с которого был переход, его следует указать в параметре utm_source

organic — поисковая выдача. Если необходимо передать название поисковой системы, с которой был переход, её следует указать в параметре utm_source.

При рекламном переходе utm_type определится автоматически в соответствии с переданными utm-метками.

Примеры запросов

Пример простого заказа звонка с дополнительными полями:

             $url_vars = http_build_query([
                'unique' => 'example_company',
                'apiak' => 'eb2cee1bc1b8d1b6e4282486af09e078',
                'whash' => '96d6ec6937c878c2ca1f889b9b9e865a',
                'utc' => 'Europe/Moscow',
                'opening_hours' => '09001800',
                'notification' => 'df@mail.ru',
                'ga_client_id' => 1526128712.1513128077,
                'tool_name' => 'Форма Узнать спецпредложение',
                'ip_client' => '74.44.210.123',
                'calls' =>
                    [
                        [
                            'client' => '79999999999',
                            'manager' => '79999999999',
                            'client_email' => 'test@mail.ru',
                            'calltouch_session_id' => 9449450,
                            'roistat_id' => 7492561,
                            'current_page' => "https://site.ru/page/widget.html",
                            'record_to_manager' => "https://site.ru/record/voice",
                            'office_name' => "My office",
                            'comagic_session_id' => 2154680201
                        ]
                    ]
            ]);

            $protocol = 'https://';
            $url = $protocol . 'api.callkeeper.ru/makeCalls?' . $url_vars;
            $curl = curl_init($url);
            curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
            $response = curl_exec($curl);
            curl_close($curl);
        

В этом примере указаны обязательные данные для успешного заказа звонка. Номера телефонов могу содержать дополнительные символы такие, как

«+( ) - _ »

но должны иметь необходимое количество цифровых знаков для звонка.

Номер клиента не может содержать добавочный номер!

Номер менеджера может быть передан с указанием добавочного номера через символ «^». Пример: (+74642512525^4342). Номер менеджера не является обязательным (в этом случае звонок пойдет на первый офис указанный в настройках виджета).

Пример отложенного звонка

В случае если есть необходимость запланировать звонок на какое-то конкретное время, достаточно передать параметр time_to_call в формате Unix time для каждого звонка.

            'calls' => [
                [
                    'client' => '79999999999',
                    'time_to_call' => '1479732377'
                ]
            ]
        

Единственное поле, которое должно присутствовать в массиве со звонком, это client. Остальные поля могут быть заполнены по желанию. В данном случае, поле time_to_call является обязательным для отложенного звонка.

Пример использование поля «site»:

В случае если есть необходимость добавить идентификатор сайта для звонка необходимо передать параметр site для каждого звонка. site - это строковый параметр, в котором желательно передавать название сайта или его адрес, в удобном для восприятия виде.

            'calls' => [
                [
                    'client' => '79999999999',
                    'site' => 'example.com'
                ]
            ]
        

Единственное поле, которое должно присутствовать в массиве со звонком, это client. Остальные поля могут быть заполнены по желанию.

Пример заказа звонка с использованием IVR

            $office_number = 0;
            $text_to_manager = 'Тестовый звонок с сайта';
            $info_to_manager = 'Данный звонок заказан через HTTPS REST API CallKeeper';

            $url_vars = http_build_query([
                'unique' => '32655e77c317dcbb1098c2cdae8e9b0a',
                'apiak' => 'eb2cee1bc1b8d1b6e4282486af09e078',
                'whash' => '96d6ec6937c878c2ca1f889b9b9e865a',
                'calls' => [
                    [
                        'client' => '79999999999',
                        'manager' => '79999999999^1231',
                        'text_to_manager' => $text_to_manager,
                        'info_to_manager' => $info_to_manager,
                        'external_service_identifier' => 'exampleID',
                    ],
                    [
                        'client' => '79999999944',
                        'manager' => $office_number,
                        'text_to_manager' => 'Звонок из другой формы',
                        'info_to_manager' => $info_to_manager,
                        'ext_id' => 'exampleID',
                        'time_to_call' => '1479726881',
                    ],
                    [
                        'client' => '79999999944',
                        'manager' => $office_number,
                    ]
                ]
            ]);

            $protocol = 'https://';
            $url = $protocol . 'api.callkeeper.ru/makeCalls?' . $url_vars;
            $response = file_get_contents($url);
        

В данном примере реализовано:

Примечание: Порядковый номер офиса считается от «0».

Пример построения запроса с IVR и utm-метками:

            $text_to_manager = 'Тестовый звонок с сайта';
            $info_to_manager = 'Данный звонок заказан через HTTPS REST API CallKeeper';
            $url_vars = [
                'unique' => 'example_company',
                'apiak' => '5b534347d4c480bee596c5d40ad4e82d',
                'whash' => '96d6ec6937c878c2ca1f889b9b9e865a',
                'calls' => [
                    [
                        'client' => '79999999999',
                        'manager' => 0,
                        'text_to_manager' => $text_to_manager,
                        'info_to_manager' => $info_to_manager,
                        'ext_id' => 'exampleID',
                        'utm' => [
                            'utm_source' => 'organic',
                            'utm_medium' => 'some_data',
                            'utm_campaign' => 'some_data',
                            'utm_content' => 'some_data',
                            'utm_term' => 'some_data',
                            'entry_point' => 'http://facebook.com',
                            'user_agent' => 'Mozilla/5.0 (Windows NT 10.0; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/52.0.2712.0 Safari/537.36'
                        ],
                    ],
                ],
            ];
            $protocol = 'https://';
            $url = $protocol . 'api.callkeeper.ru/makeCalls?';
            $curl = curl_init($url);
            curl_setopt_array($curl, [
                CURLOPT_RETURNTRANSFER => true,
                CURLOPT_POST => true,
                CURLOPT_POSTFIELDS => http_build_query($url_vars),
            ]);
            $response = curl_exec($curl);
            curl_close($curl);

        

В данном примере реализовано:

Метод API orderCall

Новый метод API orderCall позволяет заказать звонок с упрощенным форматом данных. Метод orderCall, в отличие от метода makeCalls, принимает параметры без вложенных массивов, таких как calls и utm, что упрощает составление запроса. Метод orderCall в автоматическом режиме определяет тип источника перехода и правильно его обрабатывает без передачи дополнительных параметров. Это избавляет пользователя, настраивающего интеграцию, от необходимости разбираться в том, что считается рекламным переходом (реферальным или поисковым). Вместо ключа utm_type используется ключ referrer, который содержит сведения об адресе сайта, с которого произошел переход посетителя (для удобства в ключ можно скопировать содержимое js-переменной document.referrer).

Пример запроса для передачи методом GET

    https://api.callkeeper.ru/orderCall?
    unique=any_string&apiak=XXXXXXXXXX&whash=xxxxxxxxxxxxxxx&
    utc=europe/moscow&opening_hours=10002000&notification=your@email.ru&
    tool_name=name&ga_client_id=1245784512.3256897854&ip_client=192.168.0.1&
    interval=5,10,15&client=71234567890&manager=0&
    text_to_manager=text_to_manager&info_to_manager=info_to_manager&
    external_service_identifier=123456&time_to_call=1522222222&
    site=callkeeper.ru&utm_source=utm_source&utm_medium=utm_medium&
    utm_campaign=utm_campaign&utm_content=utm_content&
    utm_term=utm_term&entry_point=my.site.ru/any/page/&
    user_agent=user_agent&referrer=yandex.ru&client_email=test@mail.ru&
    calltouch_session_id=9449450&roistat_id=7492561¤t_page=https://site.ru/page/widget.html&
    record_to_manager=https://site.ru/record/voice&office_name=My office
        

Пример PHP-кода для передачи методом POST

            $url_vars = [
                "unique" => "any_string",
                "apiak" => "XXXXXXXXXX",
                "whash" => "xxxxxxxxxxxxxxx",
                "utc" => "europe/moscow",
                "opening_hours" => "10002000",
                "notification" => "your@email.ru",
                "tool_name" => "name",
                "ga_client_id" => "1245784512.3256897854",
                "ip_client" => "192.168.0.1",
                "interval" => "5,10,15",
                "referrer" => "yandex.ru",
                "client" => "71234567890",
                "manager" => "1",
                "text_to_manager" => "text_to_manager",
                "info_to_manager" => "info_to_manager",
                "external_service_identifier" => "123456",
                "time_to_call" => "1522222222",
                "site" => "my.site.ru",
                "utm_source" => "utm_source",
                "utm_medium" => "utm_medium",
                "utm_campaign" => "utm_campaign",
                "utm_content" => "utm_content",
                "utm_term" => "utm_term",
                "entry_point" => "my.site.ru/any/page/",
                "user_agent" => "user_agent",
                "client_email" => "test@mail.ru",
                "calltouch_session_id" => 9449450,
                "roistat_id" => 7492561,
                "current_page" => "https://site.ru/page/widget.html",
                "record_to_manager" => "https://site.ru/record/voice",
                "office_name" => "My office",
                "comagic_session_id" => 2154680201
            ];

            $url = "https://api.callkeeper.ru/orderCall";

            $ch = curl_init();
            curl_setopt($ch, CURLOPT_URL, $url);
            curl_setopt($ch, CURLOPT_HEADER, false);
            curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
            curl_setopt($ch, CURLOPT_POST, true);
            curl_setopt($ch, CURLOPT_POSTFIELDS, $url_vars);
            curl_setopt($ch, CURLOPT_CONNECTTIMEOUT, 30);

            $response = curl_exec($ch);
            curl_close($ch);
        

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

Пример выгрузки данных пользователя:

Для получения информации по вашему пользователю достаточно передать параметр api_key:

Пример

Пример выгрузки статистики по звонкам:

Для получения статистики по звонкам достаточно передать в запросе такие параметры:

Пример выгрузки c указанными временными рамками:

Пример

Пример с указанием тайм зоны:

Пример

Пример с выгрузкой за все время:

Пример

Пример с выгрузкой только завершенных звонков:

Пример

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

Формат ответа при успешном заказе звонка:

[{"id":"123456","manager":"79999999999^_","client":"799999999998","status":"success"}]

Форматы ошибок при неудачном запросе:

{"status":"fail", "reason":"Key 'unique' is not defined!"} 400

{"status":"fail", "reason":"Key 'apiak' is not defined!"} 400

{"status":"fail", "reason":"Key 'whash' and 'walias' are not defined!"} 400

{"status":"fail", "reason":"Key 'calls' is not defined!"} 400

{"status":"fail", "reason":"Unauthorized host!"} 401

{"status":"fail", "reason":"Not the correct key api"} 403

{"status":"fail", "reason":"Mismatched request!"} 404

{"status":"fail", "reason":"Unknown request method!"} 405

{"status":"fail", "reason":"Wrong data type!"} 406

{"status":"fail", "reason":"Date is not array"} 406

{"status":"fail", "reason":"Not enough values"} 409

{"status":"fail", "reason":"Invalid manager or client phone number"} 409

{"status":"fail", "reason":"Phone not provided or invalid"} 409

{"status":"fail", "reason":"Unknown user"} 412

{"status":"fail", "reason":"Apiak or Hash shorter or longer then was required or not hexadecimal"} 417

{"status":"fail", "reason":"Wrong pair whash or walias and apiak!"} 424

{"status":"fail", "reason":"The widget is disabled"} 710

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

id — id звонка в системе CallKeeper

visit info — массив utm меток по звонку

current — массив utm меток по текущему визиту

current_add — массив дополнительной информации по текущему визиту

first — массив utm меток по первому визиту

first_add — массив дополнительной информации по первому визиту

session

pgs — количество просмотренных страниц (до совершения звонка)

cpg — страница откуда был совершен звонок

udata

vst — порядковый номер визита

uag — данные User Agent

status_code — код статуса звонка менеджеру SIP

status_reason — сообщение о статусе звонка менеджеру

status2_code — код статуса звонка клиенту SIP

status2_reason — сообщение о статусе звонка клиенту

ip — ip адрес клиента

country — код страны

city — название города

region — название региона

district — название округа

site — сайт

roistat_visit — уникальный номер посещения Roistat

ga_clientid — Google Analytics ID

ya_clientid — уникальный ID посетителя сайта для Яндекс.Метрики

phone1 — номер тел менеджера [добавочный]

phone2 — номер тел клиента

widget_hash — хеш виджета callkeeper

date — дата звонка по UTC

order_date — дата заказа звонка по UTC

duration_sec — длительность звонка в секундах

duration_min — округленная (тарифицируемая) длительность в минутах

duration2_sec — длительность после поднятия трубки клиентом в секундах

duration2_min — длительность после поднятия трубки клиентом в минутах (с округлением в большую сторону)

record_url — ссылка на запись разговора

attempt — номер попытки

a_type — тип соединения: 0 - неизвестно, 1 - соединение без SmartCall, 2 - аналоговый DTMF SmartCall, 3 - цифровой DTMF SmartCall, 4 - голосовой SmartCall, 5 - автоматически, после завершения заданного значения проговаривания IVR

playback_tick — количество проговариваний текста IVR до ответа от оператора

tags — теги звонка. Если у звонка их нет, вернет пробел

asr_attempts — количество попыток распознавания

source — источник перехода по рекламе

source_type — тип трафика

call_type_description - Тип звонка, как в выгрузке в колонке Тип звонка

Возможные статусы по звонку

status_code status2_code Описание в ЛК Полное описание
1 0 Звонок происходит прямо сейчас Звонок идёт в настоящий момент
2 0 Запланирован на Звонок запланирован
101 200 Клиенту поступило голосовое уведомление Клиенту поступило голосовое уведомление
101 480 Клиенту не поступило голосовое уведомление Клиенту не поступило голосовое уведомление
101 486 Клиенту не поступило голосовое уведомление Клиенту не поступило голосовое уведомление
200 0 Звонок клиенту не инициирован От менеджера пришёл отбой по трём причинам: менеджер не дождался ответа клиента/АТС отключила нас/или транзитный оператор оборвал связь
200 1 Оператор не дождался соединения Звонок прекратился до получения статуса от вызываемого клиента
200 200 Звонок прошел успешно Успешный звонок. Всё прошло хорошо
200 201 Режим заявок Режим заявок
200 400 Некорректный запрос Некорректный запрос, запрос не понятен серверу
200 401 Время регистрации истекло Время регистрации истекло
200 403 Клиент временно недоступен Оператор связи запрещает вызов
200 404 Неправильный номер клиента Номер клиента не существует
200 406 Клиент недоступен Клиент недоступен
200 408 Абонент не найден (клиент) Абонента не удалось найти за определённое время
200 410 Номер клиента не существует Номер клиента не существует
200 461 Оператор связи запрещает вызов Оператор связи запрещает вызов
200 480 Клиент временно недоступен Клиент недоступен
200 484 Неправильный номер клиента Неправильный номер клиента
200 486 Номер клиента занят Номер клиента занят
200 487 Клиент не взял трубку Клиент не взял трубку
200 491 Техническая ошибка телефонии Ошибка повторного обращения к тому же диалогу
200 500 Технические неполадки у оператора Технические неполадки на стороне оператора связи
200 502 Технические неполадки у оператора Технические неполадки на стороне оператора связи
200 503 Технические неполадки у оператора Технические неполадки на стороне оператора связи
200 504 Технические неполадки у оператора Технические неполадки на стороне оператора связи
200 600 Номер клиента занят Номер клиента занят
200 603 Клиент временно недоступен Оператор связи запрещает вызов
200 604 Вызываемого пользователя не существует Вызываемого пользователя не существует
200 708 Менеджер отменил вызов Менеджер, который принимал звонок, отменил его без возможности для повторных соединений
200 717 Истекло время дозвона Звонок был автоматически отменен при достижении времени, ограничивающего соединение с клиентом
403 0 Оператор временно недоступен Оператор связи запрещает вызов
404 0 Оператор временно недоступен Номер менеджера не существует
408 0 Абонент не найден (менеджер) Абонента не удалось найти за определённое время
480 0 Оператор временно недоступен Менеджер недоступен
484 0 Ошибка оператора связи Ошибка оператора связи
486 0 Телефон оператора занят Номер менеджера занят
487 0 Оператор не взял трубку Менеджер не взял трубку
488 0 Не поддерживаются кодеки SIP Не поддерживаются кодеки SIP
491 0 Техническая ошибка телефонии Ошибка повторного обращения к тому же диалогу
500 0 Сервер не отвечает Технические неполадки на стороне оператора связи
502 0 Технические неполадки оператора связи: Технические неполадки на стороне оператора связи
503 0 Технические неполадки оператора связи: Технические неполадки на стороне оператора связи
504 0 Сервер недоступен: Сервер менеджера не доступен
603 0 Оператор временно недоступен Оператор связи запрещает вызов
604 0 Оператор временно недоступен Номер менеджера не существует
667 0 Блокировка по номеру телефона Блокировка по номеру телефона клиента
668 0 Блокировка по IP Блокировка по IP адресу клиента
701 0 Ненужный звонок Звонок отменен. Происходит при заказе звонка, когда цепочка уже удачно закончена
702 0 Отменённый звонок Звонок отменён по причине отсутствия возможного рабочего времени
703 0 Совпадающие номера Номер менеджера и номер клиента совпадают
704 0 Технически отменено Отменённый звонок по техническим причинам
705 0 Номер менеджера в блоке Номер менеджера находится в блэк-листе
707 0 Проблема оператора связи Неизвестная ошибка оператора связи
708 0 Отменён менеджером Отменен менеджером вручную
709 0 Некорректный номер Некорректный формат номера
710 0 Виджет отключен Виджет отключен
718 0 Недопустимый номер клиента Недопустимый номер клиента
720 0 Неизвестная ошибка оператора связи Неизвестная ошибка оператора связи
790 0 Test call Test call
811 0 Недостаточно минут на балансе Закончился баланс
812 0 Оплаченный период закончился Закончился период
813 0 Ненужный отложенный звонок Повторный заказ в течение часа
814 0 Превышена максимальная стоимость звонка Превышена максимальная стоимость звонка
815 0 Дублирующийся звонок Дублирующий звонок

Взаимодействие через именованные запросы

Методы

Для разных запросов существуют разные Методы, по которым можно обращаться к адресу https://api.callkeeper.ru:


Параметры для создания виджета:

Примечание: отмеченные * поля являются обязательными.

* apiak — ключ сгенерированный в ЛК во вкладке Профиль

* phone — телефон, на который будут идти заказанные звонки

name — название виджета

gmt — временная зона в формате IANA Time Zone Database(Europe/Moscow) или в формате ±hhmm("UTC+03:00")

phoneadd — добавочный для номера телефона, на который будут идти звонки

site — сайт, на котором будет размещен виджет

schedule — время работы компании (время когда можно принимать звонки от клиентов). Если каждый день компания работает в одни и те же часы, указывается в формате 09001800. Если время работы разное, указывается в формате 09001800100018000900200009001800090018000900180000000000. Если в какой—то из дней компания не работает, время работы для этого дня указывается 00000000

emails — массив email для уведомлений

Пример запроса