Корзина
19 отзывов
Надежный продавец Prom.ua
Бесплатная АТС для бизнеса от 3CX и Google, 50 пользователейСкачать
+380679586868
+380443928676
УкраинаДнепропетровская областьДнепрул. Вернадского 24 / 4
Оставить отзывНаличие документов
Знак Наличие документов означает, что компания загрузила свидетельство о государственной регистрации для подтверждения своего юридического статуса компании или физического лица-предпринимателя.
  • Unified Ukraine
  • Документация для разработчиков по интеграции 3CX и 1С

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

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

Документация актуальна для версии модуля 2.9.2

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

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

Для 1С 7.X

ПодключитьВнешнююКомпоненту(”AddIn.3cxTo1cIntegrator”); 
Компонента3СХ = СоздатьОбъект(”AddIn.3cxTo1cIntegrator”);

Для 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С 7.X по стандарту Windows COM Interface
Компонента3СХ=СоздатьОбъект("client_3cx.Client");

Для 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(строка ВнутрНомер, строка Номер)
Инициирует вызов от внутреннего абонента ВнутрНомер на номер Номер. При этом сначала идет дозвон на ВнутрНомер, и, если оператор поднял трубку, идет дальнейший дозвон на Номер.
Совет: чтобы не снимать вручную трубку на софтфоне, в консоли 3CX настройте код для пейджинга:

после чего вместо Вызвать(”100”,”0671234567”); используйте Вызвать(”*9100”,”0671234567”);

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

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

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

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

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

Прослушивание \ Listen(число ID_Разговора, строка Номер)
Присоединяет к разговору ID_Разговора Номер в режиме прослушивания.  Для работы требуют 3СХ Call Center Module (в 11 и 12 версии уже встроен).

Подсказка \ Whisper(число ID_Разговора, строка Номер, строка НомерДляПодсказки)
Присоединяет к разговору ID_Разговора Номер в режиме прослушивания. Его ни слышит никто, кроме НомерДляПодсказки.   В 10 версии 3CX для работы требуют 3СХ Call Center Module.

Номер \ 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′;

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