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

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

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

• 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 ,"Бібліотека",AddInType.Native);
Компонента3СХ = Новий("AddIn.Lib.3cxTo1cIntegrator");

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

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

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

Після створення об'єкта Компонента3СХ можна підключитися до сервера:

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

В подальшому використовуються методи отриманого об'єкта Компонента3СХ, наприклад виклик ініціюється так:

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

Все подаються таким чином команди відразу повертають рядкові значення — результат передачі команди на сервер. Це або <> або <<Помилка>> текст помилки.

Для отримання інформації про події, що відбуваються на сервері 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

Всі команди відразу повертають рядкові значення — результат передачі команди на сервер. Це або "", або "<<Помилка>> текст помилки". Поруч з назвою методу вказано англійська синонім.

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

Якщо параметр методу має тип "логічне", то можна також використовувати значення "Істина"\"Брехня","Так""Ні","True"\"False","Yes"\"No",0\1.

Службові команди

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

Відключитися \ Disconnect()
Відключає компоненту від сервера зв'язку.

Підключений \ Connected()
Функція. Повертає "True", якщо компонента підключена до сервера зв'язку.

ОжиданиеПодкл \ WaitConnect()
Функція. Повертає "True", якщо компонента знаходиться в режимі очікування підключення до сервера зв'язку.

ВключитьСобытия \ UseEvents(логічне Включити)
Управляє режимом отримання подій для компоненти 1С. Якщо Включити = "Істина", то будуть слаться зовнішні події в 1С, інакше для отримання подій необхідно по таймеру опитувати функції ЕстьСообщения() і Повідомлення().

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

• Зовнішні події

  • + Швидкий відгук в конфігурації 1С. Стандартність підходу.

  • — Можливість втрати подій при тривалих розрахунках. Не працюють в режимі сервера.

• Функції повідомлень

  • + Події не губляться при подвисаниях. Працюють в будь-яких режимах.

  • — Невелика затримка між відправленням і отриманням подій.

ЕстьСообщения \ HasMessages()
Функція. Повертає «True», якщо з'явилися непрочитані повідомлення від сервера зв'язку. Працює в режимі "ВключитьСобытия(Брехня);".

Повідомлення \ Message()
Функція. Повертає наступний в черзі непрочитане повідомлення від сервера зв'язку. Працює в режимі "ВключитьСобытия(Брехня);".

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

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

Версія \ Version()
Функція. Повертає номер версії компоненти.

Версия3СХ \ 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(рядок ИдентификаторЗагрузки)
Функція. Припиняє завантаження файлу з кодом. Повертає «<>» або рядок з описом помилки.

ЗахватитьРазговор \ 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';

Поле ДлительностьРазговора вказується в секундах з дробовою частиною, відокремленої крапкою. При створенні розмови командою Викликати, події первісного додзвонитися на номер, з якого буде відбуватися виклик, не передаються. Події дозвону і з'єднання зі шлюзами не показуються.