Документация для разработчиков по интеграции 3CX и 1С

Документация для разработчиков по интеграции 3CX и 1С

Документация актуальна для серверного расширения TCPServer.dll из модуля интеграции версии 3.2.0

Интеграция 1С (или другой программы) с 3CX Phone System обеспечивается следующими компонентами:

• client_3cxTo1c.dll - внешняя компонента по технологии COM для 1С:Предприятие, регистрируется как DLL библиотека Windows, (только 1С 32 bit)
• client_3cxTo1c_n.dll - внешняя компонента по технологии  NativeAPI для 1С:Предприятие 8 (только 1С 32 bit)
• client_3cxTo1c_n64.dll - внешняя компонента по технологии  NativeAPI для 1С:Предприятие 8, для 1С 64 bit (отсутствует в бесплатной версии)
• client_3cx.dll - универсальная библиотека, поддерживающая Windows COM интерфейс и доступная в любом языке программирования, регистрируется как DLL библиотека Windows (только 32 битные программы)
• 3CXLinkClient.dll - .NET библиотека, все предыдущие библиотеки работают через неё. 

Компонента подключается следующим образом:

Для 1С 8.X (только толстый клиент)

ПодключитьВнешнююКомпоненту(”AddIn.3cxTo1cIntegrator”);
Компонента3СХ = Новый(”AddIn.3cxTo1cIntegrator”);

Для 1С 8.X по стандарту NativeAPI

ПодключитьВнешнююКомпоненту(ПутьКФайлу_ client_3cxTo1c_n.dll ,”Lib”,AddInType.Native);
Компонента3СХ = Новый(”AddIn.Lib.3cxTo1cIntegrator”);

Компонента по технологии NativeAPI может подключаться также другими способами и использоваться в тонком и Web клиентах (см. документацию к 1С).

Для 1С 8.X по стандарту Windows COM Interface

Компонента3СХ=ПолучитьCOMОбъект(””,”client_3cx.Client”);
 

После создания объекта Компонента3СХ можно подключиться к серверу:

Компонента3СХ.Подключиться(Хост,Порт,ВнутрПорт,ИнтервалПереподключения);

В дальнейшем используются методы полученного объекта Компонента3СХ, например вызов инициируется так:

Результат = Компонента3СХ.Вызвать(ВнутрНомер,НомерКуда,ТелефонноеУстройство);

Все подаваемые таким образом команды сразу возвращают строковые значения — результат передачи команды на сервер. Это или <<OK>>, или <<Ошибка>> текст ошибки.

Для получения информации о событиях, происходящих на сервере 3СХ, необходимо определить обработчик внешнего события.

Процедура ОбработкаВнешнегоСобытия(Источник, Событие, Данные) 
  Если Источник = ”3cxTo1c” Тогда
    Сообщить(Данные); 
      //дальнейшая обработка ….. 
  КонецЕсли;
КонецПроцедуры;

Например, при звонке из софтфона 3CXPhone с номера 100 на номер «эхо» (*777) этот код выдаст примерно такие строки:

Событие=’Дозвон’;Дата=’2018.10.17 20:04:12.870′;Идентификатор=’23’;НомерОткуда=’100′;НомерКуда=’*777′; 
Событие=’Звонок’;Дата=’2018.10.17 20:04:13.226′;Идентификатор=’23’;НомерОткуда=’100′;НомерКуда=’*777′;
Событие=’Соединение’;Дата=’2018.10.17 20:04:13.388′;Идентификатор=’23’;Номер=’100′; 
Событие=’НачалоРазговора’;Дата=’2018.10.17 20:04:13.388′;Идентификатор=’23’;ИнициаторРазговора=’100′; 
Событие=’Соединение’;Дата=’2018.10.17 20:04:13.389′;Идентификатор=’23’;Номер=’*777′; 
Событие=’Отсоединение’;Дата=’2018.10.17 20:04:14.703′;Идентификатор=’23’;Номер=’100′;ДлительностьРазговора=’1.324′; 
Событие=’Отсоединение’;Дата=’2018.10.17 20:04:14.747′;Идентификатор=’23’;Номер=’*777′;ДлительностьРазговора=’1.358′; 
Событие=’КонецРазговора’;Дата=’2018.10.17 20:04:14.747′;Идентификатор=’23’;ДлительностьРазговора=’1.359′;

Альтернативой использованию внешних событий является опрос компоненты по таймеру:

Пока Компонента3СХ.ЕстьСообщения() Цикл
    Данные = Компонента3СХ.Сообщение(); 
    Сообщить(Данные); 
    //дальнейшая обработка …..
КонецЦикла;

Выбирать тот или иной режим можно методом Компонента3СХ.ВключитьСобытия(да\нет);

Поскольку в 1С нет возможности получить из внешней компоненты информацию сразу в несколько переменных, работу по обработке и анализу входящих данных приходится делать разработчику 1С. Пример такой обработки в прилагаемой демонстрационной конфигурации.

Методы модуля

Методы компоненты разделяются на

• собственные служебные команды и функции

• команды и функции для 3СХ Phone System

Все команды сразу возвращают строковые значения — результат передачи команды на сервер. Это или ”<OK>”, или ”<<Ошибка>> текст ошибки”. Рядом с названием метода указан его английский синоним.

Для библиотек client_3cx.dll и 3CXLinkClient.dll можно использовать только английские названия. Чтобы увидеть пространства имён и определения функций .NET сборки 3CXLinkClient.dll, можно воспользоваться контекстным меню "View in Object Browser" в  Visual Studio, они практически не отличаются от ниже перечисленных.

Если параметр метода имеет тип ”булево”, то можно также использовать значения ”Истина”\”Ложь”,”Да”\”Нет”,”True”\”False”,”Yes”\”No”,0\1.

Служебные команды

Подключиться \ Connect(строка Хост,число Порт,число ВнутрПорт, число ИнтервалПереподключения)
Инициирует подключение к серверу связи компоненты, находящемуся на компьютере Хост по порту Порт. Сама компонента для связи будет использовать порт с номером ВнутрПорт или случайный, если ВнутрПорт равен нулю. Если ИнтервалПереподключения больше нуля, то при обрывах связи компонента будет пытаться подключаться с заданной  в секундах периодичностью.

Отключиться \ Disconnect()
Отключает компоненту от сервера связи.

Подключен \ Connected()
Функция. Возвращает ”Истина”, если компонента подключена к серверу связи.

ОжиданиеПодкл \ WaitConnect()
Функция. Возвращает ”Истина”, если компонента находится в режиме ожидания подключения к серверу связи.

ВключитьСобытия \ UseEvents(булево Включить)
Управляет режимом получения событий для компоненты 1С. Если Включить = ”Истина”, то будут слаться внешние события в 1С, иначе для получения событий необходимо по таймеру опрашивать функции ЕстьСообщения() и Сообщение().

Плюсы и минусы режимов

• Внешние события

  • + Быстрый отзыв в конфигурации 1С. Стандартность подхода.

  • — Возможность потери событий при длительных расчетах. Не работают в режиме сервера.

• Функции сообщений

  • + События не теряются при подвисаниях. Работают в любых режимах.

  • — Небольшая задержка между отправкой и получением событий.

ЕстьСообщения \ HasMessages()
Функция. Возвращает «Истина», если появились непрочитанные сообщения от сервера связи. Работает в режиме ”ВключитьСобытия(Ложь);”.

Сообщение \ Message()
Функция. Возвращает следующее в очереди непрочитанное сообщение от сервера связи. Работает в режиме ”ВключитьСобытия(Ложь);”.

ЖдатьСообщение \ WaitMessage(число Таймаут)
Функция. Ждёт сообщение с сервера максимум Таймаут миллисекунд, если оно не поступит, возвращает пустую строку

Заснуть \ Sleep(число Таймаут)
 Делает паузу в выполнении кода на Таймаут миллисекунд

Версия \ Version()
Функция. Возвращает номер версии компоненты.

Версия3CX \ Version3CX()
Функция. Возвращает номер версии 3CX Phone System, с которой работает сервер связи.

Фильтрация \ SetFilter(строка ТипНомера,строка Фильтр)
Для каждого типа номеров ТипНомера (”внутренний”, ”внешний”, и т.д., соответствует значению, возвращаемому функцией ‘Номер(nn,”тип”);‘ устанавливаются условия фильтрации Фильтр. Каждое условие отделяется точкой с запятой, и представляет собой или точное значение, или маску с символами ‘*’ и ‘?’ Маски аналогичны применяющимся в Windows для выбора файлов. Например, ‘Фильтрация(”внутренний”,”100;2??;4*”);‘. Фильтрация применяется к разговору в целом, то есть, как только в разговоре встретится удовлетворяющий любому из условий номер, все события этого разговора будут переданы клиенту. Для нового клиента по умолчанию фильтрация отсутствует, то есть доступны все события.

Команды для 3CX

Вызвать \ MakeCall(строка ВнутрНомер, строка Номер, строка ТелефонноеУстройство)
Инициирует вызов от внутреннего абонента ВнутрНомер на номер Номер, используя предпочтительное ТелефонноеУстройство.

"ТелефонноеУстройство" - это строка, идентифицирующая с какого телефона будет вызов, это может быть:
1. "3cx", "3cxphone", "soft", "softphone" - вызов с софтфона
2. "ip", "ipphone", "!3cxphone" - вызов с IP телефона
3. IP адрес - вызов с IP телефона с таким адресом
4. Название модели телефона - ищется по подстроке нужная модель (например "Fanvil")
4. Любой телефон кроме определённой модели - перед строкой ставится восклицательный знак (например "!Fanvil")
5. "makecall", пустая строка - идёт вызов на все подключённые телефоны через  "MakeCall" - дозвон будет идти с телефона, где сняли трубку. При этом сначала идет дозвон на ВнутрНомер, и, если абонент поднял трубку, дальнейший дозвон на Номер. Если телефонное устройство не может быть идентифицировано, 3CX самостоятельно выбирает устройство, с которого будет идти вызов, и способ инициации этого вызова.
 

Отсоединить \ DropCall(число ID_Разговора, строка Номер)
Отсоединяет абонента Номер от разговора ID_Разговора.

Перевести \ DivertCall(число ID_Разговора, строка Номер, строка НаНомер, булево ГолПочта)
Переводит вызов в разговоре ID_Разговора с внутреннего абонента Номер к номеру НаНомер. Будет инициирован дозвон от номера Номер на номер НаНомер. Если ГолПочта = ”Истина”, то перевод будет производиться на голосовую почту номера НаНомер.

Заменить \ TransferCall(число ID_Разговора, строка Номер, строка НаНомер)
Заменяет в установившемся разговоре ID_Разговора внутреннего абонента Номер на номер НаНомер.

Перенаправление \ PickupCall(строка Номер, строка НаНомер)
Включает перенаправление всех вызовов к абоненту Номер на номер НаНомер. Перенаправление будет срабатывать, если абонент в момент вызова занят или недоступен.

Записать \ RecordCall(число ID_Разговора, строка Номер, булево ДаНет)
Начинает или прекращает (”да”\”нет”) запись разговора ID_Разговора. Внутренний абонент Номер выступает как ”инициатор” записи. Запись ведется в каталоге на сервере, см. в консоли 3CX ”Settings - Parameters - CALLRECORDSROOT”.

Прослушивание \ Listen(число ID_Разговора, строка Номер)
Присоединяет к разговору ID_Разговора Номер в режиме прослушивания.

Подсказка \ Whisper(число ID_Разговора, строка Номер, строка НомерДляПодсказки)
Присоединяет к разговору ID_Разговора Номер в режиме прослушивания. Его ни слышит никто, кроме НомерДляПодсказки.  

Внедрение \ BargeIn(число ID_Разговора, строка Номер)
Присоединяет к разговору ID_Разговора Номер в обычном режиме. 

Номер \ NumberProp(строка Номер, строка Свойство)
Функция. Возвращает свойство с названием Свойство для абонента с номером Номер, или текст ошибки. Возможные свойства:

• тип – тип номера (внутренний, внешний, шлюз, факс, меню, парковка, очередь, группа, конференция, неизвестно).

• в_сети – находится ли номер в сети. Возвращает да\нет для внутренних номеров, неизвестно для внешних, с которыми нет соединения.

• разговоры – количество разговоров, в которых участвует абонент. Возвращает число для номеров в сети, или -1 для номеров с которыми нет соединения (неизвестно).

• доступен – Может ли абонент принять вызов. Возвращает да\нет для внутренних номеров, неизвестно для внешних.

• фамилия, имя, email – Возвращают информацию о пользователе номера для внутренних номеров, иначе пустую строку.

• все – Будет возвращена строка вида «тип=’внутренний’;в_сети=’да’;…..» или описание ошибки.

СостояниеНомера \ NumberState(число ID_Разговора, строка Номер)
Функция. Возвращает состояние номера относительно разговора ID_Разговора. Возможные значения: «присоединён», «дозвон», «на удержании», «звонок», «неопределено» или описание ошибки.

РазговорСуществует \ CallExists(число ID_Разговора)
Функция. Возвращает "да", если разговор ID_Разговора еще существует или "нет", если он завершен или его не было.

АбонентВРазговоре \ isNumberInCall(число ID_Разговора, строка Номер)
Функция. Возвращает "да", если номер участвует в разговоре ID_Разговора, или "нет".

СписокНомеров \ NumberList()
Функция. Возвращает строку – список телефонов всех внутренних абонентов, специальных номеров и внешних абонентов, подключенных на данный момент. Номера разделены “&”. . Если в строке встречается символ “&” , он будет заменен на “$amp”.

ЧленыГруппы \ GroupMembers(строка НомерГруппы)
Функция. Возвращает список всех номеров в очереди или группе дозвона с номером НомерГруппы, разделитель "&".

ФайлЗаписи \ GetRecFile(число  ID_Разговора, строка БлижайшаяДата)
Функция. Возвращает путь к файлу на сервере с записью разговора, пустую строку если подходящего файла нет, или текст с ошибкой. Так как идентификаторы разговора могут повторяться, выбирается ближайший к указанной дате +/- один час. Дата допускается в формате «гггг.мм.дд чч:мм:сс».
Внимание! В версиях 3CX PhoneSystem до 14, может пройти до минуты с момента окончания разговора, прежде чем информация о файле с записью появится в базе данных.

ЗагрузитьФайл \ DownloadFile(строка ИмяФайлаНаСервере, строка ИмяФайлаНаКлиенте)
Функция. Инициирует асинхронную загрузку файла с сервера на клиент. Возвращает идентификатор загрузки или строку с описанием ошибки. После инициации загрузки могут генерироваться события «СтатусЗагрузки», «КонецЗагрузки», «ОшибкаЗагрузки» (см. ниже).  Возможна загрузка нескольких файлов одновременно. С целью безопасности, разрешены загрузки только из папки для записи звонков 3CX.

ОтменитьЗагрузку \ CancelDownload(строка ИдентификаторЗагрузки)
Функция. Прекращает загрузку файла по идентификатору. Возвращает «<<OK>>» или строку с описанием ошибки.

ЗахватитьРазговор \ CaptureCall(число ID_Разговора, булево ДаНет)
Функция. Позволяет все события, генерируемые этим разговором, направлять исключительно клиенту, вызвавшему функцию, или отменить это поведение. Может быть полезно в конфигурациях с очередями дозвона.

ПередатьСообщение \ CustomMessage(строка Текст)
Функция. Передаёт произвольное текстовое сообщение всем остальным клиентам, что позволяет организовывать между ними взаимодействие.

Список возможных возвращаемых ошибок:

”<<Ошибка>> Нет соединения с сервером"
”<<Ошибка>> Вероятно неверный лицензионный ключ или сбой в передаче данных!”

”<<Ошибка>> Нет доступа к 3CX Phone System”
”<<Ошибка>> Нет доступа к базе звонков 3CX Phone System”
”<<Ошибка>> Несоответствие интерфейсов — Сервер: xxxx Клиент: xxxx”
”<<Ошибка>> Ответ от сервера не получен”
”<<Ошибка>> Неизвестное свойство ‘хххх’”
”<<Ошибка>> Нет свойств с возможностью записи”
”<<Ошибка>> Неизвестный метод ‘хххх’”
”<<Ошибка>> Недостаточно параметров для запроса ‘хххх’, надо хххх”
”<<Ошибка>> Неверный аргумент запроса”
”<<Ошибка>> Ожидается целое число”
”<<Ошибка>> Ожидается логическое значение”
”<<Ошибка>> Неверный идентификатор разговора: ‘хххх’”
”<<Ошибка>> Неизвестный номер абонента: ‘хххх’”
”<<Ошибка>> Абонент ‘хххх’ не является внутренним для 3CX Phone System”
”<<Ошибка>> Абонент ‘хххх’ не участвует в разговоре №хххх”
”<<Ошибка>> Абонент ‘хххх’ не присоединен к разговору №:хххх”
”<<Ошибка>> Абонент ‘хххх’ уже присоединен к разговору №:хххх”
”<<Ошибка>> Абонент ‘хххх’ недоступен или занят”
”<<Ошибка>> Неверный номер для разговора”
”<<Ошибка>> Параметр ‘xxxx’ не найден”
”<<Ошибка>> Загрузка этого файла уже начата”
”<<Ошибка>> Невозможно создать файл”
”<<Ошибка>> Недопустимое расположение файла”
"<<Ошибка>> Захват разговора c id={0} уже произведен"
<<Ошибка>> Отменить захват разговора c id={0} может только инициатор захвата

Кроме указанных, возможны и другие сообщения об ошибках, сгенерированные сервером 3CX, либо операционной системой.

События модуля

Дозвон — Вызывается, когда внутренний абонент НомерОткуда начинает дозвон на НомерКуда:
Событие=’Дозвон’;Дата=’2018.11.12 11:00:27.453′;Идентификатор=’12’;НомерОткуда=’100′;НомерКуда=’102′;

Звонок — Вызывается, когда внутренний абонент НомерКуда получает вызов от НомерОткуда (когда у него зазвонил телефон):
Событие=’Звонок’;Дата=’2018.11.23 11:00:27.453′;Идентификатор=’12’;НомерОткуда=’100′;НомерКуда=’102′;

Соединение — Вызывается, когда абонент Номер присоединяется к разговору ID_Разговора (дозванивается до абонента или сам снимает трубку):
Событие=’Соединение’;Дата=’2018.11.23 11:00:27.453′;Идентификатор=’12’;Номер=’100′;

Отсоединение — Вызывается, когда абонент Номер отсоединяется от разговора ID_Разговора (вешает трубку, принудительно отключается, или обрывается связь):
Событие=’Отсоединение’;Дата=’2018.11.23 11:00:27.453′;Идентификатор=’12’;Номер=’100′;ДлительностьРазговора=’7.06′;

НетСоединения — Вызывается, когда при звонке от НомерОткуда к НомерКуда соединения так и не происходит (НомерКуда не берет трубку, или НомерОткуда прекращает дозвон):
Событие=’НетСоединения’;Дата=’2018.11.23 11:00:27.453′;Идентификатор=’12’;НомерОткуда=’100′;НомерКуда=’102′;

НачалоРазговора — Вызывается, когда к разговору присоединился первый абонент (когда собственно разговор между абонентами и начался):
Событие=’НачалоРазговора’;Дата=’2018.11.23 11:00:27.453′;Идентификатор=’12’;ИнициаторРазговора=’100′;

КонецРазговора — Вызывается, когда от разговора отсоединился последний абонент:
Событие=’КонецРазговора’;Дата=’2018.11.23 11:00:27.453′;Идентификатор=’12’;ДлительностьРазговора=’8.06′;

СтатусЗагрузки — Вызывается 2 раза в секунду в процессе загрузки файла,что может использоваться для индикации:
Событие=’СтатусЗагрузки’;Дата=’2018.12.21 12:00:14.892′;Идентификатор=0;Загружено=16384;Размер=983932;

КонецЗагрузки — Информирует об окончании загрузки:
Событие=’КонецЗагрузки’;Дата=’2018.12.21 12:07:12.242′;Идентификатор=2;

ОшибкаЗагрузки — Вызывается, если в процессе копирования возникли неполадки:
Событие=’ОшибкаЗагрузки’;Дата=’2018.12.21 12:14:02.473′;Идентификатор=5;Сообщение='<<Ошибка>> Недопустимое расположение файла’;

Примечания

Для всех событий присутствуют поля Идентификатор и Дата. При инициализации любого разговора, еще до его начала, сервер 3СХ присваивает ему свой номер. Номера идут по порядку, начиная с 0 при старте сервиса 3СХ, потому номер глобально не уникален. Дата и время возникновения события указываются с точностью до миллисекунд, и передаётся в формате гггг.мм.дд чч:мн:ск.мил, независимо от региональных установок.У событий Дозвон,Звонок,Соединение может также присутствовать поле Шлюз, также у всех событий кроме НачалоРазговора и КонецРазговора могут присутствовать дополнительные поля, передаваемые 3СХ, например:

Событие=’Звонок’;Дата=’2013.11.12 11:00:27.453′;Идентификатор=’12’;НомерОткуда=’0989876766′;НомерКуда=’102′;Шлюз=’10002′;ringgroup=’400′;

Поле ДлительностьРазговора указывается в секундах с дробной частью, отделённой точкой. При создании разговора командой Вызвать, события первоначального дозвона на номер, с которого будет происходить вызов, не передаются. События дозвона и соединения со шлюзами не показываются.