BitCall - автообзвон покупателей и голосовые рассылки вашим клиентам
   Автоматические звонки вашим клиентам

API

API нашего сервиса поддерживает 2 варианта автоматического звонка:

  • Голосовая СМС - c возможностью синтеза русской речи из текста в режиме реального времени (TTS) или использованием предварительно записанных голосовых файлов (формат: alaw или WAV PCM 16 bit 8 kHz)

  • Интерактивное голосовое меню (IVR), с возможнсотью взаимодействия с абонентом посредством нажатия клавиш или распознаванием русской речи (ASR)

Также присутствуют методы для партнеров, позволяющие работать с конечными клиентами.

 Отправка автоматических голосовых вызовов на телефоны абонентов может быть произведена через REST или SOAP сервисы, по защищенному протоколу HTTPS.
Для интеграции с нашей системой автообзвона Вы можете использовать наш PHP-клиент. Его исходники доступны в личном кабинете после регистрации.

Полное описание API автоматических звонков с примерами доступно в личном кабинете.

 

Пример отправки автоматического звонка через API с синтезом речи из текста (REST) .
Я
зык программирования - PHP.

<?php
$key='**** ваш KEY   *************'; 
// и создаем запрос на создание звонка
$request = new stdClass();
 
//Ключ пользователя
$request->Key = $key;
//Номер телефона отправителя
$request->CallerPhone = '7ХХХХХХХХХХ';
//Номер телефона абонента
$request->Phone = '7ХХХХХХХХХХ';
//Текст сообщения
$request->Text = 'Здравствуйте. Я телефонный голосовой компьютер компании бит кол. До свидания.';
 
var_dump(ExecuteRequest($request, '< URL для отправки звонка >'));
function ExecuteRequest($request, $url){
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $url);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_HEADER, false);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: application/json; charset=utf-8'));
    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($request));
    curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
    curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, false);
    $res = curl_exec($ch);
    curl_close($ch);
    $decoded = json_decode($res);
    return $decoded;
}
 
?>
 

Пример отправки автоматического звонка через API  с IVR, синтезом речи из текста и получением нажатой клавиши "1" (REST)
Язык программирования - PHP.

<?php
$key=' ваш KEY ';
// и создаем запрос на создание IVR-звонка
$request = new stdClass();
 
//Ключ пользователя
$request->Key = $key;
//Номер телефона отправителя
$request->CallerPhone = '7ХХХХХХХХХХ';
//Номер телефона абонента
$request->Phone = '7ХХХХХХХХХХ';
//Создаем голосовое меню
$request->Context = array();
 
//Создаем параметры голосового меню.
$ivrCallPrameter1 = new stdClass();
//Синтезировать текст "Нажмите один", ожидая нажатия клавиши
$ivrCallPrameter1->Operator = "Backgroundtext";
$ivrCallPrameter1->Parameters = array('Нажмите один');
$ivrCallPrameter2 = new stdClass();
 
//ожидать нажатия 15 секунд
$ivrCallPrameter2->Operator = "Waitexten";
$ivrCallPrameter2->Parameters = array(15);
$ivrCallPrameter3 = new stdClass();
 
//Обрабатываем нажатие 1
$ivrCallPrameter3->Operator = "Input";
$ivrCallPrameter3->Parameters = array(1);
$ivrCallPrameter4 = new stdClass();
//если нажата 1, то говорим текст "Вы нажали 1"
$ivrCallPrameter4->Operator = "Saytext";
$ivrCallPrameter4->Parameters = array("Вы нажали один");
$ivrCallPrameter5 = new stdClass();
 
//Завершаем звонок
$ivrCallPrameter5->Operator = "Disconnect";
//Добавляем параметры к запросу
$request->Context[] = $ivrCallPrameter1;
$request->Context[] = $ivrCallPrameter2;
$request->Context[] = $ivrCallPrameter3;
$request->Context[] = $ivrCallPrameter4;
$request->Context[] = $ivrCallPrameter5;
 
var_dump(ExecuteRequest($request, ' < URL для отправки звонка > '));
function ExecuteRequest($request, $url){
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $url);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_HEADER, false);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: application/json; charset=utf-8'));
    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($request));
    curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
    curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, false);
    $res = curl_exec($ch);
    curl_close($ch);
    $decoded = json_decode($res);
    return $decoded;
}
?>
 

Пример запроса на статус автоматического звонка через API (REST) .
Я
зык программирования - PHP.

<?php
$key='**** ваш KEY **********'; 
// и создаем запрос на статус
$request = new stdClass();
 
//Ключ пользователя
$request->Key = $key;
//Id звонка в системе BitCall, который был отдан Вам в ответ на запрос на совершение звонка
$request->Id = '******* Id звонка *******';
 
var_dump(ExecuteRequest($request, '< URL для получения статуса звонка >'));
function ExecuteRequest($request, $url){
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $url);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_HEADER, false);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: application/json; charset=utf-8'));
    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($request));
    curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
    curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, false);
    $res = curl_exec($ch);
    curl_close($ch);
    $decoded = json_decode($res);
    return $decoded;
}
 
?>
 

Краткое описание API.

Методы для клиентов

Методы звонков

Text — ставит звонок в очередь.
Входной параметр: TextCallRequest.
Выходной параметр: BaseCallResponse.
 
TextTask — создает задачу на обзвон.
Входной параметр: TextTaskRequest.
Выходной параметр: TaskResponse.
 
Status — ищет информацию по звонку.
Входной параметр: StatusRequest.
Выходной параметр: StatusResponse.
 
FastText — совершает звонок(метод не устанавливает звонок в очередь, а моментально отправляет на шлюз). 
Входной параметр: TextCallRequest.
Выходной параметр: BaseCallResponse.
 
Ivr — устанавливает голосовое меню в очередь.
Входной параметр: IvrCallRequest.
Выходной параметр: BaseCallResponse.
 
IvrTask — создает задачу на обзвон голосовым меню.
Url: https://rest.bitcall.ru/api/calls/ivrtask
Входной параметр: IvrTaskRequest.
Выходной параметр: TaskResponse.
 
FastIvr — совершает звонок типа "голосовое меню" (метод не устанавливает звонок в очередь, а моментально отправляет на шлюз). 
Входной параметр: IvrCallRequest.
Выходной параметр: BaseCallResponse.
 
Statistics — получает общую статистику по звонкам
Входной параметр: CallsStatRequest.
Выходной параметр: CallsStatResponse.
 
 
Методы для исходящих номеров
 
GetCallers — получает исходящие номера пользователя
Входной параметр: CallersRequest.
Выходной параметр: CallersResponse.
 
GetCaller — получает информацию по одному номеру
Входной параметр: CallersRequest.
Выходной параметр: CallersResponse.
 
Create — создает исходящий номер
Входной параметр: CallerSaveRequest.
Выходной параметр: SaveCallerResponse.
 
Delete — удаляет исходящий номер
Входной параметр: CallerRequest.
Выходной параметр: BaseResponse.
 
Call — совершает звонок на исходящий номер для его подтверждения
Входной параметр: CallerRequest.
Выходной параметр: CallerCallResponse.
 
Confirm — подтверждает исходящий номер
Входной параметр: CallerRequest.
Выходной параметр: ConfirmCallerCodeRequest.
 
 
Методы для обратных вызовов
 
Save — создает или обновляет обратный вызов
Входной параметр: SaveCallbackRequest.
Выходной параметр: CallbackResponse.
 
Get — получает информацию по обратному вызову
Входной параметр: CallbackRequest.
Выходной параметр: CallbackResponse.
 
RegenerateKey — пересоздает ключ для обратного вызова
Входной параметр: CallbackRequest.
Выходной параметр: CallbackResponse.
 
Delete — удаляет обратный вызов
Входной параметр: CallbackRequest.
Выходной параметр: BaseResponse.
 
Test — посылает тестовый запрос на url обратного вызова
Входной параметр: CallbackRequest.
Выходной параметр: TestCallbackResponse.
 
 
Методы для пользователя
 
GetInfo — получает информацию по пользователю
Входной параметр: UserInfoRequest.
Выходной параметр: UserInfoResponse.
 
 
Методы для аудио-файлов
 
AddFile — добавляет файл для пользователя
Входной параметр: AddFileRequest.
Выходной параметр: AudioFileResponse.
 
GetFiles — получает информацию о файлах
Входной параметр: GetFilesRequest.
Выходной параметр: GetAudioFilesResponse.
 
GetInfo — получает информацию о файле
Входной параметр: AudioFileRequest.
Выходной параметр: GetAudioFileResponse.
 
Delete — удаляет файл
Входной параметр: AudioFileRequest.
Выходной параметр: BaseResponse.
 

Методы для партнеров

GetChildren — получает дочерних пользователей.
Входной параметр: PartnerRequest.
Выходной параметр: PartnerChildrenResponse.
 
GetTarifs — получает тарифы, которые можно установить пользователям.
Входной параметр: PartnerRequest.
Выходной параметр: PartnerTarifsResponse.
 
GetRewards — получает информацию о вознаграждениях.
Входной параметр: PartnerRewardsRequest.
Выходной параметр: PartnerRewardsResponse.
 
CreateUser — создает пользователя и отправляет приглашение на e-mail.
Входной параметр: PartnerCreateUserRequest.
Выходной параметр: CreateUserResponse.

 

 

Структуры данных

Запросы

Тип Имя Назначение Ограничения Примечания Обязательный

 

TextCallRequest

Строка Key Секретный ключ, используется для авторизации      
Строка Id Идентификатор звонка в системе пользователя   Можно использовать вместе с идентификатором нашей системы  
Строка Phone Телефон абонента, на который поступит звонок      
Строка CallerPhone Телефон, который определится у абонента Только подтвержденные пользователем номера    
Строка Text Текст для генерации голоса      

 

TextTaskRequest

Строка Key Секретный ключ, используется для авторизации      
Строка CallerPhone Телефон, который определится у абонента Только подтвержденные пользователем номера    
Строка TaskName Имя задачи      
Дата в UTC SendDate Дата и время, в которые начнется отправка задачи на шлюз Следует отправлять даты исключительно в UTC Если не указана, отправка начнется сразу  
Коллекция TextTaskCall TaskCalls Звонки, которые следует совершить в рамках задачи см. описание соответствующего типа    
Число MaxRetries Повторить звонок, если не успешен Не более 10 По умолчанию 0 - только совершить звонок, не перезванивать  
Число RetryTime Время между повторами (в минутах)   По умолчанию (если указан MaxRetries) 5 минут  
Число WaitTime Сколько ожидать снятия трубки абонентом (в секундах) Не более 60 секунд По умолчанию (если указан MaxRetries) 45 секунд  

 

IvrTaskRequest

Строка Key Секретный ключ, используется для авторизации      
Строка CallerPhone Телефон, который определится у абонента Только подтвержденные пользователем номера    
Строка TaskName Имя задачи      
Дата в UTC SendDate Дата и время, в которые начнется отправка задачи на шлюз Следует отправлять даты исключительно в UTC Если не указана, отправка начнется сразу  
Коллекция IvrTaskCall TaskCalls Звонки, которые следует совершить в рамках задачи см. описание соответствующего типа    
Число MaxRetries Повторить звонок, если не успешен Не более 10 По умолчанию 0 - только совершить звонок, не перезванивать  
Число RetryTime Время между повторами (в минутах)   По умолчанию (если указан MaxRetries) 5 минут  
Число WaitTime Сколько ожидать снятия трубки абонентом (в секундах) Не более 60 секунд По умолчанию (если указан MaxRetries) 45 секунд  

 

TextTaskCall

Строка Id Идентификатор звонка в системе пользователя   Можно использовать вместе с идентификатором нашей системы  
Строка Phone Телефон абонента, на который поступит звонок      
Строка Text Текст для генерации голоса      

 

IvrTaskCall

Строка Id Идентификатор звонка в системе пользователя   Можно использовать вместе с идентификатором нашей системы  
Строка Phone Телефон абонента, на который поступит звонок      
Массив из IvrCallParameter Context Голосовое меню      

 

StatusRequest

Строка Key Секретный ключ, используется для авторизации      
Строка Id Идентификатор звонка   Если указан IsOtherSystemId=true, то используется идентификатор системы пользователя, иначе идентификатор Bitcall  
Булево IsOtherSystemId Использовать идентификатор внешней системы  

Если указано true, то используется идентификатор системы пользователя, иначе идентификатор Bitcall

Если указано false, но идентификатор не подходит под формат идентификаторов Bitcall, то Id будет восприниматься как идентификатор внешней системы

По умолчанию — false

 

 

IvrCallRequest

Строка Key Секретный ключ, используется для авторизации      
Строка Id Идентификатор звонка в системе пользователя   Можно использовать вместе с идентификатором нашей системы  
Строка Phone Телефон абонента, на который поступит звонок      
Строка CallerPhone Телефон, который определится у абонента Только подтвержденные пользователем номера    
Массив из IvrCallParameter Context Голосовое меню      

 

IvrCallParameter

IvrOperator Operator Действие, которое совершает голосовое меню      
Массив из строк Parameters Параметры, с которыми надо выполнить оператор (например, оператор "Ждать нажатия цифры" имеет один параметр — сколько секунд ждать)      

 

IvrOperator

Имя Назначение Параметры Примечания
Playback Воспроизвести файл Имя файла Файл должен быть на нашем сервере
Saytext Синтезировать русскую речь из текста и воспроизвести абоненту Текст для синтеза  
Saydigits Синтезировать цифры на русском языке (с другой интонацией) и воспроизвести абоненту Цифры для синтеза  
Background Воспроизводить файл и одновременно ожидать нажатия клавиши абонентом Имя файла Файл должен быть на нашем сервере
Backgroundtext Синтезировать русскую речь из текста, воспроизводить абоненту и одновременно ожидать нажатия клавиши абонентом Текст для синтеза  
Waitexten Ожидать нажатия клавиши абонентом Количество секунд ожидания нажатия Background (Backgroundtext) и Waitexten должны быть использованы в связке, между ними не должно быть других операторов
Input Обработка нажатия клавиши Клавиша (например 1, 2 и т.п.)  
Wait Не производить никаких действий Время, в течении которого бездействовать Допускается меньше 1 секунды, в формате: 0.5
Dial Соединить абонента с номером Два параметра. Первый — номер, с которым соединить абонента. Второй — фраза, которую синтезировать абоненту. Второй параметр необязателен.  
Disconnect Разрыв соединения нет  
Noinput Обработка, если абонент не нажал ни одной клавиши нет  
Nomatch Обработка, если абонент нажал клавишу, отсутствующую в обработке нет  

 

Ответы

Базовые структуры

Все ответы используют объект BaseResponse в качестве базовой структуры.

Тип Имя Назначение Примечания

 

BaseResponse

ResponseError Error Детализация ошибки, возникшей в процессе обработки запроса  
Булево HasError Если в процессе обработке запроса возникли ошибки —  true, иначе — false  

 

ResponseError

Перечисление ErrorCode ErrorCode Код ошибки  
Строка ErrorString Строковое представление ошибки  
Строка ErrorMessage Описание ошибки  
Строка ErrorId Идентификатор ошибки Не возвращается на ошибки валидации
 
Структуры ответов
Тип Имя Назначение Примечания

 

BaseCallResponse

Глобальный уникальный идентификатор (Guid) Id Идентификатор звонка в Bitcall  

 

StatusResponse

Глобальный уникальный идентификатор (Guid) Id Идентификатор звонка в Bitcall  
Перечисление GateStatus Status Текущий статус звонка  
Строка Digits Цифры, которые нажимал абонент (для IVR)  
32-битное целое (int) Duration Длительность звонка в секундах  
64-битное целое (long) Price Цена звонка в копейках  
Строка StatusString Строковое представление статуса  

 

TaskResponse

Перечисление BaseCallResponse CallResponses Состояние по каждому из переданных звонков. Состояния сохранения звонков возвращаются в том же порядке, в каком они были переданы
 

Полное описание API с примерами доступно в личном кабинете.

 

. @Mail.ru