/ViberEnterprise

Библиотека интеграции 1С:Предприятие и Viber

Primary Language1C EnterpriseMIT LicenseMIT

ViberEnterprise теперь часть Открытого пакета интеграций
https://github.com/Bayselonarrend/OpenIntegrations

1CViber

ViberEnterprise

Библиотека интеграции 1С и Viber

В данной библиотеке реализованы базовые методы Viber REST API для управления ботами и каналами

Особенности:

  • Не нужно ничего устанавливать: создайте 2 пустых модуля в базе и скопируйте код из репозитория туда
  • Не нужно разбираться в документации Viber Bot API: методы уже выполняют конкретные действия, которые подойдут большинству пользователей, вроде ОтправитьТекстовоеСообщение() или ПолучитьДанныеПользователя()
  • Основная разработка с тестированием велись на режиме своместимости версии 8.3.6. Возможно, будет работать и на более ранних версиях.

Документация Viber REST API:

Для ботов: https://developers.viber.com/docs/api/rest-bot-api/

Для каналов: https://developers.viber.com/docs/tools/channels-post-api/

Для начала использования библиотеки достаточно пройти два простых шага:

Установка библиотеки
Библиотека представляет из себя всего два общих модуля
  • Инструменты - содержит вспомогательные методы, вроде отправки http запросов, чтения JSON и пр.
  • Действия - непосредственно сами методы работы с Viber

Эти модули необходимо добавить в свою конфигурацию (модули серверные). При переименовании модуля Инструменты необходимо будет провести рефакторинг в модуле Действия. Модуль же Действия можно переименовывать без изменений.

Если вы уже используете библиотеки VKEnterprise или TelegramEnterprise, то модуль Инструменты совместим и дублировать его не нужно, однако стоит проверить, не изменилось ли что-нибудь с выходами новых версий библиотек.

После установки можно вызывать нужные методы из модуля Действия

Получение необходимых данных

У Viber есть два REST API: для работы с каналами и для чат-ботов

Если вам необходимо управлять каналом:

  1. Зайдите в приложение Viber и создайте новый канал (кнопка с карандашем в рамке)
  2. После создания, перейдите в настройки канала -> "Для разработчиков", и скопируйте Токен

Если вам необходим чат-бот:

  1. Перейдите по ссылке https://partners.viber.com/account/create-bot-account
  2. Авторизуйтесь с вашим номером телефона, который привязан к Viber
  3. В меню создания бота заполните все необходимые поля
  4. Найти своего нового бота вы можете отсканировав QR на странице создания или в настройках (пункт чат-боты) в приложении Viber. Сейчас вы не можете написать своему боту, сначала необходимо выполнить действия из следующего раздела

Особенности Viber API по сравнению с API Телеграма и ВК

  1. Нельзя использовать бота и управлять каналом через API, если не установлен Webhook

    В отличии от Telegram и VK, которые позволяют самому забирать обновления с серверов, а писать и вовсе независимо от этого, Viber требует обязательного использования Webhook, т.е у вас должен быть сервер с внешним IP и действительный SSL сертификат. Если верить документации, Viber периодически будет стучать по адресу, указанному как WH и если он не получит ответ 200, то все перестанет работать. Это может быть обработано http-сервисом или любым другим обработчиком, при условии наличия SSL и доступности адреса извне. Если у вас есть такой адрес, то установить Webhook можно при помощий функции УстановитьWebhook(Знач Токен, Знач URL) данной библиотеки (см. далее). После установки, у чат бота в приложении Viber появится кнопка "Сообщение" для начала диалога, а в канал станет можно отправлять сообщения через REST Api.

  2. У Viber отсутствуют механизмы загрузки внешних файлов на их сервера

    Картинки, файлы и документы могут отправляться в Viber только в виде URL. Т.е. для этого тоже нужен сервер или, как минимум, сторонний сервис для публикации файлов. Но так как сервер уже в любом случае необходим для Webhook, отправляемые файлы можно временно сохранять в папку сайта веб-сервера. У IIS это папка wwwroot

Реализованные методы:

Все методы возвращают ответ от Viber как структуру

Для настройки и получения информации
Эти методы предназначены для стартовой настройки и получения различной информации

  • Установить Webhook | Метод: УстановитьWebhook()

    Параметр Тип Назначение
    Токен Строка Токен бота или канала
    URL Строка Ваш адрес, на который будт приходить оповещения о новых сообщениях

*Один и тот же URL можно использовать для нескольких ботов/каналов

  • Получить информацию о канале (в том числе и список участников) | Метод: ПолучитьИнформациюОКанале()

    Параметр Тип Назначение
    Токен Строка Токен канала

*ID не универсальные: не получится получить id участников канала и использовать их, например, для другого чат-бота

  • Получить информацию о пользователе | Метод: ПолучитьДанныеПользователя()

    Параметр Тип Назначение
    Токен Строка Токен канала/бота
    IDПользователя Строка ID пользователя

  • Получить статусы пользователей (online/offline) | Метод: ПолучитьОнлайнПользователей()

    Параметр Тип Назначение
    Токен Строка Токен канала/бота
    IDПользователей Строка / Массив строк (максимум 100) ID пользователя / Массив ID пользователей
Для отправки сообщений
Эти методы предназначены для отправки сообщений

  • Отправить текстовое сообщение | Метод: ОтправитьТекстовоеСообщение()

    Параметр Тип Назначение
    Токен Строка Токен канала/бота
    Текст Строка Текст сообщения
    IDПользователя Строка IDПользователя: для канала - администратора, для бота - получателя
    ОтправкаВКанал Булево Истина - отправка в канал, Ложь - через бота
    Клавиатура Структура См. СформироватьКлавиатуруИзМассиваКнопок()

  • Отправить картинку | Метод: ОтправитьКартинку()

    Параметр Тип Назначение
    Токен Строка Токен канала/бота
    URL Строка Адрес картинки
    IDПользователя Строка IDПользователя: для канала - администратора, для бота - получателя
    ОтправкаВКанал Булево Истина - отправка в канал, Ложь - через бота
    Описание Строка (необяз.) Аннотация к картинке

  • Отправить файл | Метод: ОтправитьФайл()

    Параметр Тип Назначение
    Токен Строка Токен канала/бота
    URL Строка Адрес картинки
    IDПользователя Строка IDПользователя: для канала - администратора, для бота - получателя
    ОтправкаВКанал Булево Истина - отправка в канал, Ложь - через бота
    Расширение Строка Расширение файла
    Размер Строка (необяз.) Размер отправляемого файла. Не рекомендуется оставлять пустым для больших файлов - автоматическое определение размера происходит путем скачивания файла из URL. Указывается в байтах

  • Отправить контакт | Метод: ОтправитьКонтакт()

    Параметр Тип Назначение
    Токен Строка Токен канала/бота
    ИмяКонтакта Строка Отображаемое имя
    НомерТелефона Строка Отображаемый номер телефона
    IDПользователя Строка IDПользователя: для канала - администратора, для бота - получателя
    ОтправкаВКанал Булево Истина - отправка в канал, Ложь - через бота

  • Отправить локацию на карте по широте и долготе | Метод: ОтправитьЛокацию()

    Параметр Тип Назначение
    Токен Строка Токен канала/бота
    Широта Строка Географическая широта
    Долгота Строка Географическая долгота
    IDПользователя Строка IDПользователя: для канала - администратора, для бота - получателя
    ОтправкаВКанал Булево Истина - отправка в канал, Ложь - через бота

  • Отправить ссылку на сайт | Метод: ОтправитьСсылку()

    Параметр Тип Назначение
    Токен Строка Токен канала/бота
    URL Строка Отображаемый URL
    IDПользователя Строка IDПользователя: для канала - администратора, для бота - получателя
    ОтправкаВКанал Булево Истина - отправка в канал, Ложь - через бота
Прочее
Прочие методы

  • Сформировать простую клавиатуру из массива строк | Метод: СформироватьКлавиатуруИзМассиваКнопок()

    Параметр Тип Назначение
    МассивКнопок Массив строк Массив строк названий кнопок
    ЦветКнопок Строка(необяз) HEX цвета для кнопок

В функции ВернутьСтандартныеПараметры можно установить аватар и имя для бота

В проекте используется механизм распаковки zip и gzip vbondarevsky/Connector

Copyright 2017-2023 Vladimir Bondarevskiy под Apache License, Version 2.0

https://github.com/vbondarevsky/Connector/

Остальной проект распространяется под лицензией MIT Модуль Инструменты данной библиотеки совместим с подобными модулями последних версий остальных библиотек в линейке

  • TelegramEnterprise - библиотека для интеграции с Telegram
  • VKEnterprise - библиотека для интеграции с ВКонтакте

Infostart

Статья на Инфостарте: https://infostart.ru/1c/articles/1987615/