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

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

Подключение модуля

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

  • client_3cxTo1c.dll — старая COM компонента, которая регистрируется как DLL библиотека Windows
  • client_3cxTo1c_n.dll — новая компонента, реализующая в 1С:Предприятие 8 и выше интерфейс NativeAPI
  • client_3cx.dll — универсальная компонента, поддерживающая Windows COM интерфейс и доступная в любом языке программирования

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

Для 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С 8.X по стандарту Windows COM Interface

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

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

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

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

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

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

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

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

Сообщить
(Данные);

//дальнейшая обработка …..

КонецЕсли;

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

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

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

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

  Сообщить(Данные);

  //дальнейшая обработка …..

КонецЦикла;

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

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

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

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

  • собственные служебные команды и функции
  • команды и функции для 3СХ Phone System

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

Для библиотеки client_3cx.dll можно использовать только английские названия.

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

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

Подключиться (Connect) (строка Хост,число Порт,число ВнутрПорт, число ИнтервалПереподключения)

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

Отключиться (Disconnect)()

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

Подключен (Connected)()

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

ОжиданиеПодкл (WaitConnect)()

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

ВключитьСобытия (UseEvents)(булево Включить)

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

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

  • Внешние события
    • + Быстрый отзыв в конфигурации 1С. Стандартность подхода.
    • — Возможность потери событий при длительных расчетах. Не работают в режиме сервера.
  • Функции сообщений
    • + События не теряются при подвисаниях. Работают в любых режимах.
    • — Небольшая задержка между отправкой и получением событий.

Для библиотеки client_3cx.dll доступен только режим функций сообщений.

ЕстьСообщения (HasMessages)()

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

Сообщение (Message)()

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

Версия (Version)()

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

Версия3CX (Version3CX)()

Функция. Возвращает номер версии 3CXPhoneSystem, с которой работает сервер связи.

Фильтрация (SetFilter)(строка ТипНомера,строка Фильтр)

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

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

Вызвать (MakeCall) (строка ВнутрНомер, строка Номер)

Инициирует вызов от внутреннего абонента ВнутрНомер на номер Номер. При этом сначала идет дозвон на ВнутрНомер, и, если абонент поднял трубку, идет дальнейший дозвон на Номер.

Совет: чтобы не снимать вручную трубку на софтфоне, в панели 3CX настройте код для пейджинга.

Настройка кода пейджинга в консоли 3CX.

Настройка кода пейджинга в консоли 3CX.

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

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

Отсоединяет абонента Номер от разговора ID_Разговора.

Перевести (DivertCall) (число ID_Разговора, строка Номер, строка НаНомер, булево ГолПочта)

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

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

Заменяет в установившемся разговоре ID_Разговора внутреннего абонента Номер на номер НаНомер.

Перенаправление (PickupCall) (строка Номер, строка НаНомер)

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

Записать (RecordCall) (число ID_Разговора, строка Номер, булево ДаНет)

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

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

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

Подсказка (Whisper) (число ID_Разговора, строка Номер, строка НомерДляПодсказки)

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

Номер (NumberProp) (строка Номер, строка Свойство)

Функция. Возвращает свойство с названием Свойство для абонента с номером Номер, или текст ошибки. Возможные свойства:
  • тип – тип номера (внутренний, внешний, шлюз, факс, меню, парковка, очередь, группа, конференция, неизвестно).
  • в_сети – находится ли номер в сети. Возвращает да\нет для внутренних номеров, неизвестно для внешних, с которыми нет соединения.
  • разговоры – количество разговоров, в которых участвует абонент. Возвращает число для номеров в сети, или -1 для номеров с которыми нет соединения (неизвестно).
  • доступен – Может ли абонент принять вызов. Возвращает да\нет для внутренних номеров, неизвестно для внешних.
  • фамилия, имя, email – Возвращают информацию о пользователе номера для внутренних номеров, иначе пустую строку.
  • все – Будет возвращена строка вида «тип=’внутренний’;в_сети=’да’;…..» или описание ошибки.

СостояниеНомера (NumberState) (число ID_Разговора, строка Номер)

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

СписокНомеров (NumberList)()

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

ФайлЗаписи (GetRecFile) (число  ID_Разговора, строка БлижайшаяДата)

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

ЗагрузитьФайл (DownloadFile) (строка ИмяФайлаНаСервере, строка ИмяФайлаНаКлиенте)

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

ОтменитьЗагрузку (CancelDownload) (строка ИдентификаторЗагрузки)

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

ЗахватитьРазговор (CaptureCall) (число ID_Разговора, булево ДаНет)

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

ПередатьСообщение (CustomMessage) (строка Текст)

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

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

”<<Ошибка>> Нет доступа к 3CX Phone System”
«<<Ошибка>> Нет доступа к базе звонков 3CX Phone System»
”<<Ошибка>> Неизвестное свойство ‘хххх’”

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

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

Дозвон — Вызывается, когда внутренний абонент НомерОткуда начинает дозвон на НомерКуда:

Событие=’Дозвон’;Дата=’2015.11.12 11:00:27.453′;Идентификатор=’12’;НомерОткуда=’100′;НомерКуда=’102′;

Звонок — Вызывается, когда внутренний абонент НомерКуда получает вызов от НомерОткуда (когда у него зазвонил телефон):

Событие=’Звонок’;Дата=’2015.11.23 11:00:27.453′;Идентификатор=’12’;НомерОткуда=’100′;НомерКуда=’102′;

Соединение — Вызывается, когда абонент Номер присоединяется к разговору ID_Разговора (дозванивается до абонента или сам снимает трубку):

Событие=’Соединение’;Дата=’2015.11.23 11:00:27.453′;Идентификатор=’12’;Номер=’100′;

Отсоединение — Вызывается, когда абонент Номер отсоединяется от разговора ID_Разговора (вешает трубку, принудительно отключается, или обрывается связь):

Событие=’Отсоединение’;Дата=’2015.11.23 11:00:27.453′;Идентификатор=’12’;Номер=’100′;ДлительностьРазговора=’7.06′;

НетСоединения — Вызывается, когда при звонке от НомерОткуда к НомерКуда соединения так и не происходит (НомерКуда не берет трубку, или НомерОткуда прекращает дозвон):

Событие=’НетСоединения’;Дата=’2013.11.23 11:00:27.453′;Идентификатор=’12’;НомерОткуда=’100′;НомерКуда=’102′;

НачалоРазговора — Вызывается, когда к разговору присоединился первый абонент (когда собственно разговор между абонентами и начался):

Событие=’НачалоРазговора’;Дата=’2015.11.23 11:00:27.453′;Идентификатор=’12’;ИнициаторРазговора=’100′;

КонецРазговора — Вызывается, когда от разговора отсоединился последний абонент:

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

СтатусЗагрузки — Вызывается 2 раза в секунду в процессе загрузки файла,что может использоваться для индикации:

Событие=’СтатусЗагрузки’;Дата=’2015.12.21 12:00:14.892′;Идентификатор=0;Загружено=16384;Размер=983932;

КонецЗагрузки — Информирует об окончании загрузки:

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

ОшибкаЗагрузки — Вызывается, если в процессе копирования возникли неполадки:

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

Примечания

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

Событие=’Звонок’;Дата=’2013.11.12 11:00:27.453′;Идентификатор=’12’;НомерОткуда=’0989876766′;НомерКуда=’102′;Шлюз=’10002′;ringgroup=’400′;
Поле ДлительностьРазговора указывается в секундах с дробной частью, отделённой точкой. При создании разговора командой Вызвать, события первоначального дозвона на номер, с которого будет происходить вызов, не передаются. События дозвона и соединения со шлюзами не показываются.