Наша компания предлагает REST API для 3CX собственной разработки (за ценами обращайтесь по телефону или e-mail). Особенность нашего предложения в том, что набор http-запросов, логика, а также формат ответов могут составляться индивидуально под задачу клиента.
Непосредственно сама компания 3СХ предоставляет программное API, которое работает только на сервере, на котором установлена АТС 3CX. Программное API от 3CX достаточно обширное, и с его помощью можно решать очень широкий круг задач. Наша компания разработала веб-службу, которая запускается на сервере, где установлена 3CX. Эта служба получает http-запросы, отрабатывает их с использованием программного API 3СХ и в формате json предоставляет ответы на полученные http-запросы.
Мы включили в базовую версию нашего REST API наиболее востребованные запросы к 3CX. Но конкретные задачи клиентов могут требовать реализации более специфичных запросов к 3CX. Мы готовы по заявке клиента разработать и внедрить REST API, решающее индивидуальные задачи компании, использующей 3CX.
Вы можете прямо сейчас протестировать команды предлагаемого REST API. Для этого воспользуйтесь демо-ключом qRQi5xQj8SvI и описанием запросов, приведенным ниже. URL запроса: https://demo-pbx.3cx.ru/webapi/qRQi5xQj8SvI/. Для тестирования доступны только команды, которые получают информацию с АТС 3CX. Команды, которые изменяют те или иные параметры в предлагаемом тесте недоступны.
Список GET-запросов для 3CX v20
Получить текущее количество вызовов, проходящих через АТС
pbx.calls.get
Получить подробную информацию обо всех текущих активных соединениях
pbx.ac.get
ответ:
count – суммарное количество активных соединений (вызовов, проходящих через АТС)
AConnByCallID – список активных соединений:
callID – ID звонка
direction – направление вызова. Возможные значения:
-
- FromExternal – звонок пришел с внешней линии, но пока еще никуда не распределен
- FromInternal – звонок пришел c внутреннего номера, но пока еще никуда не распределен
- Inbound – звонок с внешней линии на внутренний номер
- Outbound – звонок с внутреннего номера на внешнюю линию
- External – звонок с внешней линии на внешнюю линию
- Internal - звонок с внутреннего номера на внутренний
did – для звонка с внешней линии название DID-правила, если таковое есть
AConnList – список составляющих звеньев звонка (см. описание программного API 3CX, ActiveConnection Interface)
Получить подробную информацию обо всех текущих звонках. Информация, по сути, близка той, которую предоставляет предыдущая команда pbx.calls.get?key={секретный ключ}, только информация предоставляется несколько в ином срезе и логике.
pbx.callsinfo.get
ответ:
count – суммарное количество звонков
callsInfo – список звонков, проходящих через АТС в данный момент
callID – ID звонка
state – состояние звонка: Unknown, Initiating, Routing, Talking, Transferring, Rerouting
startedAt – время начала звонка
answeredAt – время начала разговора (может быть равно null)
did – для звонка с внешней линии название DID-правила, если таковое есть
owner – информация о владельце звонка. Соответствует данным из класса OMCallCollector.ActiveConnectionFields
talkTo – информация с кем разговаривает владелец звонка (если разговаривает), список. Соответствует данным из класса OMCallCollector.ActiveConnectionFields
routingTo – информация на кого направляется вызов (если направляется), список. Соответствует данным из класса OMCallCollector.ActiveConnectionFields
Описание класса OMCallCollector.ActiveConnectionFields смотрите в документации по API 3CX. Также там смотрите описание свойства PhoneSystem.CallStorage, которое является первичным источником всей информации, предоставляемой для реализации данной команды. В архиве с документацией вы найдете примеры на C#, использующие данные сущности.
Получить список всех добавочных номеров пользователей
all.ext.get
Получить список всех зарегистрированных добавочных номеров пользователей
all.registered.get
Получить список всех групп вызова
all.group.get
Получить список всех очередей вызова
all.queue.get
Получить список всех IVR
all.ivr.get
Получить список всех внешних линий (тракнов)
all.line.get
Получить список всех групп добавочных номеров
all.extgroup.get
Получить информационные поля добавочного номера пользователя
ext.info.get?num={номер добавочного}
Получить статусы добавочного номера пользователя
ext.state.get?num={номер добавочного}
ответ:
num - добавочный номер пользователя
registered - зарегистрирован или нет данный добавочный на АТС
status - Free - абонент не находится в разговоре, Busy - абонент в разговоре или ему поступает звонк или совершает звонок
fwdName - текущий статус переадресации
qGlobalStatus - глобальный статус входа/выхода из всех очередей
qStatus - статусы входа/выхода из конкретных очередей (num - номер очереди, status - статус)
Получить статусы всех добавочных номеров
statuses.get
Возвращает в json статусы всех добавончных номеров: статус передаресации, глобальный статус входа/выхода из очередей, стаутс входа/выхода из каждой отдельно взятой очереди, в которой добавочный числится агентом.
Получить список всех операторов очереди
queue.members.get?num={номер очереди}
Получить список всех менеджеров очереди
queue.managers.get?num={номер очереди}
Получить список всех свободных операторов очереди
queue.free.get?num={номер очереди}
Получить список всех операторов очереди, которые находятся в разговоре
queue.talk.get?num={номер очереди}
Узнать есть ли хотя бы одни свободный оператор очереди, готовый принять звонок
queue.isfree.get?num={номер очереди}
Получить список всех операторов группы вызова
group.members.get?num={номер группы вызова}
Получить список всех свободных операторов группы вызова
group.free.get?num={номер группы вызова}
Получить список членов группы добавочных номеров
extgroup.members.get?name={имя группы добавочных номеров}
Получить список физических устройств, зарегистрированных на добавочном номере
ext.devices.get?num={номер добавочного}
ответ:
userAgent – название устройства (не уникальное поле, т.к. может быть несколько устройств под одним названием)
contact – уникальная информация, идентифицирующая устройство
Совершить звонок
makecall?first={номер первого плеча вызова}&second={номер второго плеча вызова}&contact={идентификатор устройства – необязательный параметр}
Параметр first всегда должен указывать на внутренний добавочный номер. Он не может быть равен внешнему номеру (в отличии от параметра second).
Если параметр contact не указан, то вызов MakeCall придет на все устройства, зарегистрированные на добавочном first. Если указан, то будет найдено первое устройство, соответствующее contact. Получить список физических устройств можно с помощью команды ext.devices.get. Соответствие ищется не по полному совпадению, а достаточно, чтоб значение параметра contact содержалось в идентификаторе устройства.
Если first указывает на IVR или скрипт CFD, то сервис начнет работу не в момент выполнения команды makecall, а когда произойдет соединение с абонентом second.
Если будет указан необязательный параметр contact, то first должен указывать на внутренний номер пользователя АТС и вызов произойдет согласно исходящему правилу для такого внутреннего номера. Если contact не указать, то будет использоваться (если таковое есть) универсальное исходящее правило, которое работает по префиксу и не учитывает пользователей или группы пользователей. В этом случае правила, основанные на пользователях или группах пользователей, будут проигнорированы.
ответ: результат выполнения команды
Вмешаться в разговор
bargein?internal={внутреннее плечо разговора, к которому надо подключиться}&external={внешнее плечо разговора, к которому надо подключиться }&num={добавочный, который должен подключиться}
В качестве external можно указать не полный внешний номер, а только несколько его последних цифр. Команда ищет соответствие по совпадению окончания номера с external.
Если параметр contact не указан, то вызов BargeIn придет на все устройства, зарегистрированные на добавочном num. Если указан, то будет найдено первое устройство, соответствующее contact. Получить список физических устройств можно с помощью команды ext.devices.get. Соответствие ищется не по полному совпадению, а достаточно, чтоб значение параметра contact содержалось в идентификаторе устройства.
ответ: результат выполнения команды
Слепой трансфер звонка
transfer?num={номер добавочного}&contact={идентификатор устройства}dest={на какой номер делать трансфер}
На добавочном номере num просматриваются все устройства с активными вызовами. Если у устройства контактная информация, идентифицирующая его (см. ответ на команду ext.devices.get), содержит параметр contact (именно содержит, а не обязательно полностью совпадает), то для трансфера звонка будет выбрано такое устройство. Предполагается, что на выбранном устройстве только один активный вызов (если их несколько, то будет выбран первый из списка). Этот вызов переводится на номер dest.
ответ: результат выполнения команды
Соединение двух активных вызовов между собой (завершение сопроводительного трансфера)
join?num={на каком добавочном номере соединить два вызова}
На добавочном num анализируются все активные соединения. Если их число не равно 2, команда не выполняется. Если на добавочном ровно два активных соединения (в общем случае, оба соединения не обязательно должны быть на одном устройстве), то они соединяются между собой, а добавочный num исключается из соединения.
ответ: результат выполнения команды
Завершение звонка
drop?num={номер добавочного}&contact={идентификатор устройства}
На добавочном номере num просматриваются все устройства с активными вызовами. Если у устройства контактная информация, идентифицирующая его (см. ответ на команду ext.devices.get), содержит параметр contact (именно содержит, а не обязательно полностью совпадает), то для завершения звонка будет выбрано такое устройство. На выбранном устройстве для добавочного num завершаются все активные звонки.
ответ: результат выполнения команды
У добавочного номера пользователя сменить статус переадресации
ext.fwd.set?num={номер добавочного}&status={название статуса переадресации на английском}&message={сообщение для статуса – необязательный параметр}
ответ: успешно/неуспешно завершилось выполнение команды, команда завершается неуспехом, если переданы некорректные данные (добавочный номер пользователя и/или название статуса)
У добавочного номера пользователя установить опцию глобального входа/выхода из всех очередей
ext.queueglobal.set?num={номер добавочного}&log={on/off}
ответ: успешно/неуспешно завершилось выполнение команды
Если за глобальный вход/выход из очередей отвечают статусы переадресации, то результат будет false – вход/выход из очередей не произойдет. В этом случае используйте смену статуса переадресации.
Ввести/вывести оператора очереди в конкретную очередь
ext.queue.set?num={номер добавочного}&queue={номер очереди}&log={on/off}
ответ: успешно/неуспешно завершилось выполнение команды. Команда завершается неуспехом, если переданы некорректные данные (добавочный номер пользователя и/или номер очереди)
Задать опции добавочного номера пользователя
ext.options.set?num={номер добавочного}&enabled={on/off}&external={on/off} &recording={off/external/all}
При использовании команды можно использовать не все 3-и опции, а только одну или две по выбору.
Значение опций:
enabled – включен или выключен добавочный номер
external – разрешены ли звонки на внешние номера
recording – режим записи разговоров (выключено/только внешние вызовы/все вызовы)
Получить список ID контактов из адресной книги 3CX, удовлетворяющих запросу.
contact.find?num={номер телефона}&min_len={длина для сравнения – необязательный}
Сравниваются последние цифры телефонного номера согласно значению min_len:
> длины num – только точное совпадение (в т.ч. и когда параметр не указан)
== длине num или 0 – окончание телефона в базе контактов должно совпадать с num
< длины num – самый длинный совпадающий конец номера >= min_len
Получить поля контакта из адресной книги 3CX (имя, фамилия, организация, почта, телефоны).
contact.get?id={id контакта}
В адресной книге 3CX по id контакта задать его данные (все поля, кроме id, необязательные).
contact.update?id={обязательный параметр}&firstname={}&lastname={}&company={}&crmcontactdata={}&tag={}&phone={}&data0={}&data1={}&data2={}&data3={}&data4={}&data5={}&data6={}&data7={}&data8={}&data9={}
Соответствие параметров запроса полям в контакте:
phone: Mobile
data0: Mobile2
data1: Home
data2: Home2
data3: Business
data4: Business2
data5: Email
data6: Other
data7: Businessfax
data8: Homefax
data9: Pager
Создать новый контакт в адресной книге 3CX.
contact.new
Возвращает id созданного контакта. В качестве необязательных параметров можно передать необязательные поля из команды contact.update.
Удалить контакт из адресной книги 3CX.
contact.del?id={id контакта}
Задать опции (поля) пользователя (добавочного номера). Все поля, кроме num, необязательные.
ext.update?num={обязательный параметр}&firstname={}&lastname={}&email={}&mobile={}&authid={}&authpass={}&callerid={}& enabled={0/1}&deliveraudio={0/1}&recordcalls={0/1/2}&sipid={}&reinvite={0/1}&replaces={0/1}&vmemail={0/1/2/3}&vmenabled={0/1}&vmpin={}&vmplaycallerid={0/1}&vmplaydatetime={0/1/2}&internal={0/1}&noanswertimeout={}
Комментарии к параметрам запроса:
callerid: исходящий Caller ID
enabled: включен или отключен добавочный номер
deliveraudio: проксировать аудиопоток через АТС
recordcalls: 0 – не записывать звонки, 1 – записывать только внешние, 2 – записывать все
reinvite: поддерживает метод Re-Invite
replaces: поддерживает заголовок 'Replaces'
vmemail: опция голосовой почты: 0 – без уведомления, 1 – текстовое e-mail уведомление, 2 – отправить голосовое сообщение как вложение, 3 – отправить голосовое сообщение как вложение и удалить из ящика
vmenabled: включена или выключена голосовая почта
vmplaycallerid: голосовая почта: воспроизвести Caller ID
vmplaydatetime: 0 – не воспроизводить дату и время, 1 – воспроизводить в формате AM/PM, 2 – воспроизводить в 24-х часовом формате
internal: 0 – разрешены все звонки, 1 – разрешены только внутренние звонки
Создать новый добавочный номер (пользователя).
ext.new?num={добавочный номер}
В качестве необязательных параметров можно передать необязательные поля из команды ext.update.
Удалить добавочный номер (пользователя).
ext.del?num={добавочный номер}
Задать членов группы вызова.
group.members.set?num={номер группы вызова}&members={через запятую список членов группы вызова}
Задать агентов очереди вызова.
queue.agents.set?num={номер очереди}&agents={через запятую список агентов очереди}
Задать менеджеров очереди вызова.
queue.managers.set?num={номер очереди}&managers={через запятую список менеджеров очереди}
Отредактировать группу добавочных номеров
extgroup.members.set?name={имя группы}&nums={через запятую без пробелов список заданий}
Варианты заданий:
-* – удалить всех членов группы, которые были в нее включены до выполнения настоящей команды
+{добавочный}@{ID роли} – включить в группу добавочный номер с ролью (набором прав) ID. Если опустить @{ID роли} или использовать несуществующий ID, то будет использована роль с ID 0.
-{добавочный} – исключить добавочный из группы
{добавочный}@{ID роли} – существующему члену группы назначить роль (набор прав).
*@{ID роли} – всем членам группы назначить роль (права) ID. Под «всеми членами группы» имеются в виду добавочные номера, которые были включены в нее до выполнения настоящей команды. Т.е. данное задание не распространяется на добавочные номера, которые указаны в команде на добавление.
Список ролей (ID – название роли):
0 – users
1 – receptionists
2 – group_admins
3 – managers
4 – group_owners
5 – system_admins
6 – system_owners
Т.к. нельзя в списке заданий вначале добавить новый экстеншен, а затем удалить тот же самый экстеншен, то во избежание ошибки выполнения вначале надо давать задания на удаление членов группы, а уже затем на их добавление.
Если по какой-то причине указанный добавочный нельзя добавить, исключить или отредактировать, то такое задание игнорируется. Например, добавить уже включенный в группу экстеншен или несуществующий экстеншен или удалить/отредактировать экстеншен, который не включен в группу. В силу этого реальный список добавленных, удаленных и отредактированных экстеншенов может отличаться от списка заданий. Для контроля результата команда на выходе в json выдает список реально добавленных, исключенных и отредактированных экстеншенов.
Получить название роли конкретного члена группы добавочных номеров
extgroup.member.role?name={имя группы}&num={добавочный номер, являющийся членом группы}
Создать новую группу добавочных номеров
extgroup.new?name={имя создаваемой группы}
Возвращает false, если такая группа уже существует, и true, если группа создана.
Удалить группу добавочных номеров
extgroup.del?name={имя удаляемой группы}
Получить список членов группы добавочных номеров
extgroup.members.get?name={имя группы добавочных номеров}&role={0/1}
Параметр role – необязательный. По умолчанию равен 0. Если 1, то в ответе к добавочному номеру через знак @ добавляется ID роли этого добавочного номера.
Получить список всех исходящих правил
outboundrules.get
выдает список всех исходящих правил с указанием уникального индекса каждого правила – его приоритета. Также сообщает общее количество правил, минимальный и максимальный приоритет.
Отредактировать исходящее правило
outboundrule.set?rulename|rulepriority={имя_правила_или_его_приоритет}& name=…&priority=…&prefix=…&numberlength=…&groups=…&ranges=…&numberofroutes=…&routes=…
Команда имеет только один обязательный параметр – rulename или rulepriority, в котором задается либо имя правила, либо приоритет правила, которое мы собираемся отредактировать. Остальные параметры необязательные (описаны ниже). Если не задан необязательный параметр, то правило сохраняет предыдущее значение параметра.
name – новое имя правила
priority – в этом параметре кроме нового значения уникального приоритета можно прописать либо tobegining, либо toend. В этом случае правило будет помещено либо в начало, либо в конец списка правил. Конкретное значение приоритета высчитывается автоматически, чтоб обеспечить попадание правила в нужное место.
prefix – новый префикс правила
numberlength – новое значение длины номера для которого работает правило
groups – через запятую без пробелов название групп добавочных, для которых будет работать правило
ranges – через запятую список диапазонов добавочных номеров, для которых будет работать правило
numberofroutes – в документации параметр описан как: Specifies number of routes available for this outbound rule. If new number of routes is less then current then routes with index [new number, current number) will be removed from the array. На практике не удалось выяснить, на что в конечном счете влияет этот параметр. На практике его задание ни на что не оказывало влияние.
routes – через запятую список маршрутов исходящего правила. Поддерживается до 5-ти маршрутов. Для каждого маршрута необходимо через точку (.) задать 4-е параметра. Если будет задано больше или меньше параметров маршрута, то такой маршрут будет проигнорирован и вместо него будет использоваться маршрут, который был в изначальном правиле. Т.е. если вы хотите задать маршрут, то в его определении должно быть три точки, между которыми указываются значения 4-х параметров:
- первый параметр – название транка. Если его не задать, то будет использоваться транк из изначального правила. Внимание! Название транка не должно содержать одну или несколько точек или запятых, т.к. они используются, как разделители. Вы должны избегать таких названий.
- второй параметр – количество цифр, которые надо убрать из начала номера, перед тем как набор передать в транк. Если не задать, то будет использоваться значение параметра из изначального правила
- третий параметр – набор цифр, которые надо подставить в начало номера, перед тем как набор передать в транк
- четвертый параметр – исходящий CallerID
Создать новое исходящее правило
outboundrule.new?name=…&priority=…&prefix=…&numberlength=…&groups=…&ranges=…&numberofroutes=…&routes=…
Команда имеет два обязательных параметра – name и priority. Остальные параметры задаются по желанию. Описание параметров см. в команде outboundrule.set.
Переместить исходящее правило выше указанного правила
outboundrule.before?rulename|rulepriority={имя_перемещаемого_правила_или_его_приоритет}&beforename|beforepriority={имя_правила_или_его_приоритет_перед_которым_поместить_перемещаемое_правило}
Также, как и в случае с outboundrule.set надо задать либо имя правила, либо его приоритет. Причем, к примеру, для перемещаемого правила можно задать приоритет, а для before-правила можно задать имя. Т.е. возможны любые сочетания. При перемещении целевого правила, у before-правила и у всех, что идут за ним, а также у целевого правила, будет изменен приоритет. Это необходимо для вставки целевого правила в нужное место.
Переместить исходящее правило ниже указанного правила
outboundrule.after?rulename|rulepriority=…&aftername|afterpriority=…
Команда работает по аналогии с outboundrule.before. При перемещении целевого правила, у after-правила и у всех, что идут перед ним, а также у целевого правила, будет изменен приоритет. Это необходимо для вставки целевого правила в нужное место.
Удалить исходящее правило
outboundrule.del?rulename|rulepriority={имя_удаляемого_правила_или_его_приоритет
Получить настройки входящей маршрутизации для inbound-правила
inboundrule.get?linename={имя_SIP-транка}&rulename={имя_inbound-правила_для_транка_linename}
Команда возвращает следующие параметры:
officeHours_type – тип направления для рабочих часов. Возможны следующие варианты:
none
extension
voicemail
external
fax
routepoint – это обозначает голосовое приложение
officeHours_internal – добавочный номер (актуально для всех направлений, кроме external)
officeHours_external – внешний номер маршрутизации вызова (актуально только для направления external)
outOfOfficeHours_type – по аналогии выше, только для нерабочих часов
outOfOfficeHours_internal – по аналогии выше, только для нерабочих часов
outOfOfficeHours_external – по аналогии выше, только для нерабочих часов
Для того, чтоб полноценно пользоваться данной командой, делайте названия всех входящих правил уникальными (хотя 3СХ позволяет делать одинаковые имена для разных правил).
Задать настройки входящей маршрутизации для inbound-правила
inboundrule.set?linename={имя_SIP-транка}&rulename={имя_inbound-правила_для_транка_linename}
&officehours_type={…}
&officehours_internal={…}
&officehours_external={…}
&outofficehours_type={…}
&outofficehours_interna={…}
&outofficehours_external={…}
Описание параметров соответствует описанию выходных параметров команды inboundrule.get.
Задать опции очереди вызовов
queue.update?num=<номер очереди>
&announcementinterval=<число>
&announcequeueposition=<0 или 1>
&enableintro=<0 или 1 - determines whether an Intro Prompt is played>
&introfile=<название файла>
&mastertimeout=<число>
&name=<имя очереди>
&pollingstrategy=<число из таблицы>
&ringtimeout=<число>
&noanswerdest=<название направления в случае неответа (см. таблицу)>
&noanswerextension=<внутренний номер>
&noanswerexternal=<внешний номер>
Каждый параметр, кроме первого num, не обязательный.
Создать новую очередь
queue.new?num=<номер очереди>
Также можно использовать необязательные параметры из команды queue.update
Удалить очередь
queue.del?num=<номер очереди>
Перечитать параметры службы TCXWebAPI (все, кроме ini-параметров) (требуются права system):
csv.reread
Перезапустить CFD-скрипты (требуются права system):
cfd.reset?names={названия CFD-скриптов через запятую}
Если скрипт имеет добавочный номер, то надо указывать этот номер, а не название скрипта. Если номер не ассоциирован со скриптом, то надо указывать полное название, т.е. <название>.Main
Прочитать системный параметр (требуются права system):
parameter.get?name={название системного параметра}
Выдает полное описание системного параметра: имя, описание, значение, тип значения. На тип значения можно не обращать внимания, т.к. на данный момент у 3СХ все параметры имеют тип строка.
Удалить системные параметры (требуются права system):
parameter.del?names={названия системных параметров через запятую}
Список POST-запросов для 3CX v20
Установить системный параметр (требуются права system):
parameter.set
Если параметра с указанным именем нет, то он будет создан.
Пример POST-запроса:
Внимание! Название параметра надо писать на верхнем регистре.
Запрос в базу данных 3СХ ‘database_single’.
query
Body (JSON), пример: {"query":"select recording_url, cl_participants_id from recordings where recording_url like '101%';", "count":3}
count – максимальное количество строк в ответе. Если не задано или 0, то равно 100.