innovaphone wiki - User contributions [en]

Reference14r1:Concept Contact Widgets

2024-02-22T12:10:28Z

Npa: /* Adding Agent to Widget */

[[Category:Concept|Conference]]

= Applies To =
* innovaphone PBX from version 14r1
* innovaphone Application Platform

= Requirements =
* innovaphone PBX
* innovaphone Application Platform
* Firmware Version 14r1
* One '''Port License''' is used by the app service to establish a VoIP registration at the PBX
* '''Video License''' (optional) is required to establish video connections [*]
* '''Widget License''' (optional) is required to remove any 'innovaphone' branding from the Widget UI

[*] '''UC License''' can also be used since it includes a '''Video License'''

= What is a Contact Widget? =
A Contact Widget (or Website Widget) is an element that can be added to a website. It offers to website visitors a way to get in contact with agents (e.g. help-desk). Website visitors can start chat sessions (asking questions, getting answers) or can start voice or even video calls.

An nice example for a "Sidebar Widget" can be viewed [https://www.innovaphone.com/de/ip-telefonie/innovaphone-pbx.html here]. 
When you have opened this website the Sidebar Widget comes slowly into view on the right side.

Example of a Business-Cards-Widget:

[[File:Cardset-widget.png]]

Example of a Sidebar-Widget:

[[File:Sidebar-Widget.png]]

= Overview =
[[File:Concept-widgets-overview.png|thumb|Overview]]
The central part of the new Widgets-Concept is the '''Contact-Widgets-App'''.
The Contact Widgets App is installed on the innovaphone Application Platform and it allows a PBX user to define Contact Widgets.

Contact Widgets can be integrated in a Website to offer easy ways to website users to contact '''Agents'''. Agents are PBX users meant to communicate with external clients. 
There are 2 fundamental types of Contact Widgets:
* '''Sidebar Widgets'''
* '''Business Cards Widgets'''

A Sidebar Widget appears one side of the website trying to take as less space as possible. The website visitor can expand the Sidebar Widget if interested. 
A Business Cards Widget appears as integrated part of the website content, offering one (or more) contacts in form of ordinary business cards.

= Configuration =
For non experienced technicians have a look at [[Howto14r1:Install_Contact_Widget_App#Installation]] and follow the installation steps mentioned in the how-to article.

Others:
* Download the 'Contact Widgets App' via App Store.
* Install the App on the App Platform Manager.
* Create an instance for the Widgets App on the Manager. We recommend to use no capital letters and no special characters (also not such as space).
* Create a new PBX Object with the PBX Manager Plugin. (*)
* Assign App to authorized (admin) users, which will be allowed to create/change/delete Contact Widgets.

Experts:
(*) You can also create the PBX Object manually: 
* Create a new object of type "App".
* Give it a "Long Name" ("Contact Widgets") and a Name ("widgets") same as the instance-name.
* Give it a password, same as the instance password.
* On the "App" tab configure URL to App Service on App Platform ("http://<ipaddress-or-dnsname>/<instance-name>/innovaphone-widgets").
* Activate option "Websocket"
* Grant access to APIs: "PbxSignal" (mandatory), "Admin" (optional) and "PbxApi" (mandatory)

= Using the Contact Widgets App =
Click on one of the buttons (depending on what type of widget you want to create):
* [+ Add new sidebar widget]
* [+ Add new business cards widget]
A new (empty) widget is displayed. You can give the widget a name by clicking the pen-symbol. The widget name helps to identify widgets as soon the number of widgets starts to grow. 
You can expand and collaps widgets by clicking the header of each widget.
[[Image:Widget-code-new-widget.png|thumb|New Widget]]

== Creating a new Widget ==

New Widget features and options

*You can add the main contact details for this widget
*Select the default language
*Set your prefered font settings
*Change the colour settings
*Change the margin settings
*z-index

[[Image:Widget-new-widget-features.png|thumb|Widget Features]]

== Adding Agent to Widget ==
You can add and remove Agents to a Widget. Agents can be contacted by external website visitors. 
New agents are added by clicking the [+] button inside the agents container.
[[File:Adding-new-agents.png|thumb|Adding agents]]
A dialog opens where you can define the agent. It all starts with the agent's 'SIP-ID'. That's the dialable PBX user address. You can use the search function to find a PBX user by name.

There are several (optional) attributes you can set for an agent, like 'Display name', 'Phone number', 'Email address' and 'Picture'. A picture can be placed by drag & drop or can be selected from local disk by clicking the placeholder rectangle.

Finally you can define the ways of communication the agent is available for:
* Voice-only calls
* Video calls (including voice)
* Chat
* Email

For a Business-Cards-Widget the order of agents could be relevant. You can change the order of agents in the Widgets-App by easy drag & drop using the mouse.

Each widget gets a unique ID (uuid) assigned on its initial creation. This uuid is used to identify the widget when it is integrated into a website.

In case of a sidebar widget, the agent's card will be displayed by default depending on its status(availability) unless you checked "Always show widget" under the sidebar settings.

In case of a business cards widget, the agent card will always be shown, but its availability is depending on its status.

The following settings are possible:
* Presence*: Display/availability of the card based on the presence status of the agent. Presence available (green), Presence unavailable, busy (red). Usage: Normal agent based on availability.
* Always online: Permanent display/availability of the card regardless of its presence or busy status. Usage: Multiple consecutive calls to the same destination, an agent with multiple line configuration, a group or waiting queue.
* Boolean*: Display of the card depending on the true status of a Boolean object. Usage: Agent, group or waiting queues based on boolean settings.
* Inactive: Agent card is permanently in the status unavailable (red). Usage: Showing the agent in a business cards widget, but limit the access to the agent for a longer period. (holiday, sick-leave or other reasons)
(* Important: Presence and boolean status are dependent on the visibility configured on all the monitored objects, eg. agent user objects and monitored boolean objects)

= Integrating Widgets into Website =
Now it is the website admin's turn to integrate the widget into the website. 
To do this, click the [Code] button in the Widgets App at that widget you want to include. A popup appears showing a handful of code lines (HTML and Javascript). 
[[File:Widget-code-popup.png|thumb|Code Popup]]
You can ''copy'' the code lines into clipboard by clicking the [Copy] button. 
You can ''paste'' the code lines from clipboard into your website code. 
There's also a [Download] button. When clicking this button a small HTML file is saved on your local computer. This HTML file can be opened in a browser to preview the widget and test the widget's functionality.

== Content-Security-Policy ==
If the website uses Content-Security-Policy (CSP) it could be necessary to add entries to config sections 'default-src' and 'img-src'.
* The Widget opens a secure websocket connection (wss:)
* The Widget loads images via Data-URL (data:).
* The Widget uses Mail-Links (mailto:).
* The Widget uses Tel-Links (tel:).
<meta
http-equiv="Content-Security-Policy" content="
default-src 'self' '''wss://*.innovaphone.com'''; child-src 'self' '''mailto:''' '''tel:'''; img-src '''data:'''"
/>

= After Integration =
Once your widget is live on the website you can still change and update the widget in the Widgets-App. You can update the list of agents or change any other attribute. As soon as you click the widget's [Save] button any open widget instance in a web browser will update immmediately. No need for the website administrator to update the code.

= Widget-API — Protocol between Website Widget and App Service =
Basically, this section does not matter. To create and use widgets, knowledge about the protocol is not required. 
All who are interested in technical details are welcome to read on.

== Loading the Widget ==

When a widget is loaded in the browser window of the website visitor, a websocket connection is opened to the app service on the innovaphone Application Platform. Once the websocket connection is established it goes like this:
<pre>
[1] {"mt":"Start","uuid":"fadc5da4cae94bfc9434d9957ea08ccb"}
[2] {"mt":"Session","name":"Visitenkarten","lang":"de","strings":{...}}
[3] {"mt":"Info","id":"atlantis","dn":"Atlantis","department":"","phonenumber":"","email":"","company":{},"presence":"online","media":["voice","video","email","chat"],"order":0}
[4] {"mt":"GetPicture","id":"atlantis"}
[5] {"mt":"Info","id":"columbia","dn":"Columbia","department":"","phonenumber":"","email":"","company":{},"presence":"offline","media":["voice","video","email","chat"],"order":1}
[6] {"mt":"GetPicture","id":"columbia"}
[7] {"mt":"IceConfig","stun":"stun.innovaphone.com","turn":"turn.innovaphone.com"}
[8] {"mt":"Picture","id":"atlantis","url":"data:image/jpeg;base64..."}
[9] {"mt":"Picture","id":"columbia","url":"data:image/jpeg;base64..."}
[10] {"mt":"Info","id":"atlantis","dn":"Atlantis","department":"","phonenumber":"","email":"","company":{},"presence":"offline","media":["voice","video","email","chat"],"order":0}
[11] {"mt":"Info","id":"atlantis","dn":"Atlantis","department":"","phonenumber":"","email":"","company":{},"presence":"online","media":["voice","video","email","chat"],"order":0}
</pre>

[1] The "Start" request is sent with the unique id of the widget. 
[2] The app service sends the "Session" response providing the widget's display-name and other parameters. 
[3]-[6] The app service sends "Info" messages for all configured agents. Each "Info" message triggers a "GetPicture" request to get a picture of the agent. 
[7] The app service sends "IceConfig" providing the STUN and TURN config required for media calls. 
[8]-[9] The app service sends "Picture" messages for all agents. 
[10]-[11] The presence of an agent may change over time. Presence updates are provided with "Info" messages.

== Initiating a call ==

<pre>
[1] {"mt":"CreateCall","dest":"atlantis","dn":"Mein Name"}
[2] {"mt":"Channels","cmd":"PROPOSAL","sdp":"..."}
[3] {"mt":"CallInfo","state":"alerting"}
[4] {"mt":"CallInfo","state":"connected","cmd":"SELECT","sdp":"..."}
[5] {"mt":"ClearCall"}
[6] {"mt":"CallInfo","state":"terminated"}
</pre>

[1] "CreatCall" message sets the target of the call ('dest') and the own display name ('dn'). 
[2] "Channels" message provides the media offer for this call. Complete SDP offer is provided. 
[3] "CallInfo" is received giving information about the call's current state. 
[4] Next "CallInfo" is received telling the call was answered and deliviering the remote side's media answer. 
[5] Web site user terminates the call. 
[6] The final "CallInfo" message is received. 

= Troubleshooting =
<big>If an issue can be reproduced</big>

'''*Web visitor in a browser.''' 
The myApps web uses the logging facilities provided by the browser it runs in (i.e. JavaScript function <code>console.log</code>). In most browser this is available as ''Console'' after pressing F12.

'''*The called agent working with myApps client.''' 
The myApps platform services provide more elaborate tracing mechanisms. See ''Troubleshooting'' in [[Reference14r1:Concept_myApps_platform_services#Troubleshooting|Concept myApps platform services]].

'''*Troubleshooting AP Services on the AP.''' 
Troubleshooting a specific App instance on the AP [[Course13:IT_Plus_-_Tools_for_Troubleshooting#App_Service_Logs|Course13:IT_Plus_-_Tools_for_Troubleshooting#App_Service_Logs]]

Go to the AP Manager and select the App instance from the Contact Widgets App.
Click on Diagnose and make sure that the box App is ticked.
[[File:AP-Diagnostics.png|thumb|none|AP-Diagnostics]]
Make sure that the logging of the App instance has been activated.
[[File:AP-DiagnosticsLogging.png|thumb|none|AP-Diagnostics-Logging]]
= Related Articles =
[[Howto14r1:Install_Contact_Widget_App|Howto14r1:Install_Contact_Widget_App]]

Reference14r1:Concept Contact Widgets

2024-02-22T12:09:28Z

Npa: /* Using the Contact Widgets App */

[[Category:Concept|Conference]]

= Applies To =
* innovaphone PBX from version 14r1
* innovaphone Application Platform

= Requirements =
* innovaphone PBX
* innovaphone Application Platform
* Firmware Version 14r1
* One '''Port License''' is used by the app service to establish a VoIP registration at the PBX
* '''Video License''' (optional) is required to establish video connections [*]
* '''Widget License''' (optional) is required to remove any 'innovaphone' branding from the Widget UI

[*] '''UC License''' can also be used since it includes a '''Video License'''

= What is a Contact Widget? =
A Contact Widget (or Website Widget) is an element that can be added to a website. It offers to website visitors a way to get in contact with agents (e.g. help-desk). Website visitors can start chat sessions (asking questions, getting answers) or can start voice or even video calls.

An nice example for a "Sidebar Widget" can be viewed [https://www.innovaphone.com/de/ip-telefonie/innovaphone-pbx.html here]. 
When you have opened this website the Sidebar Widget comes slowly into view on the right side.

Example of a Business-Cards-Widget:

[[File:Cardset-widget.png]]

Example of a Sidebar-Widget:

[[File:Sidebar-Widget.png]]

= Overview =
[[File:Concept-widgets-overview.png|thumb|Overview]]
The central part of the new Widgets-Concept is the '''Contact-Widgets-App'''.
The Contact Widgets App is installed on the innovaphone Application Platform and it allows a PBX user to define Contact Widgets.

Contact Widgets can be integrated in a Website to offer easy ways to website users to contact '''Agents'''. Agents are PBX users meant to communicate with external clients. 
There are 2 fundamental types of Contact Widgets:
* '''Sidebar Widgets'''
* '''Business Cards Widgets'''

A Sidebar Widget appears one side of the website trying to take as less space as possible. The website visitor can expand the Sidebar Widget if interested. 
A Business Cards Widget appears as integrated part of the website content, offering one (or more) contacts in form of ordinary business cards.

= Configuration =
For non experienced technicians have a look at [[Howto14r1:Install_Contact_Widget_App#Installation]] and follow the installation steps mentioned in the how-to article.

Others:
* Download the 'Contact Widgets App' via App Store.
* Install the App on the App Platform Manager.
* Create an instance for the Widgets App on the Manager. We recommend to use no capital letters and no special characters (also not such as space).
* Create a new PBX Object with the PBX Manager Plugin. (*)
* Assign App to authorized (admin) users, which will be allowed to create/change/delete Contact Widgets.

Experts:
(*) You can also create the PBX Object manually: 
* Create a new object of type "App".
* Give it a "Long Name" ("Contact Widgets") and a Name ("widgets") same as the instance-name.
* Give it a password, same as the instance password.
* On the "App" tab configure URL to App Service on App Platform ("http://<ipaddress-or-dnsname>/<instance-name>/innovaphone-widgets").
* Activate option "Websocket"
* Grant access to APIs: "PbxSignal" (mandatory), "Admin" (optional) and "PbxApi" (mandatory)

= Using the Contact Widgets App =
Click on one of the buttons (depending on what type of widget you want to create):
* [+ Add new sidebar widget]
* [+ Add new business cards widget]
A new (empty) widget is displayed. You can give the widget a name by clicking the pen-symbol. The widget name helps to identify widgets as soon the number of widgets starts to grow. 
You can expand and collaps widgets by clicking the header of each widget.
[[Image:Widget-code-new-widget.png|thumb|New Widget]]

== Creating a new Widget ==

New Widget features and options

*You can add the main contact details for this widget
*Select the default language
*Set your prefered font settings
*Change the colour settings
*Change the margin settings
*z-index

[[Image:Widget-new-widget-features.png|thumb|Widget Features]]

== Adding Agent to Widget ==
You can add and remove Agents to a Widget. Agents can be contacted by external website visitors. 
New agents are added by clicking the [+] button inside the agents container.
[[File:Adding-new-agents.png|thumb|Adding agents]]
A dialog opens where you can define the agent. It all starts with the agent's 'SIP-ID'. That's the dialable PBX user address. You can use the search function to find a PBX user by name.

There are several (optional) attributes you can set for an agent, like 'Display name', 'Phone number', 'Email address' and 'Picture'. A picture can be placed by drag & drop or can be selected from local disk by clicking the placeholder rectangle.

Finally you can define the ways of communication the agent is available for:
* Voice-only calls
* Video calls (including voice)
* Chat
* Email

For a Cardset-Widget the order of agents could be relevant. You can change the order of agents in the Widgets-App by easy drag & drop using the mouse.

Each widget gets a unique ID (uuid) assigned on its initial creation. This uuid is used to identify the widget when it is integrated into a website.

In case of a sidebar widget, the agent's card will be displayed by default depending on its status(availability) unless you checked "Always show widget" under the sidebar settings.

In case of a cardset widget, the agent card will always be shown, but its availability is depending on its status.

The following settings are possible:
* Presence*: Display/availability of the card based on the presence status of the agent. Presence available (green), Presence unavailable, busy (red). Usage: Normal agent based on availability.
* Always online: Permanent display/availability of the card regardless of its presence or busy status. Usage: Multiple consecutive calls to the same destination, an agent with multiple line configuration, a group or waiting queue.
* Boolean*: Display of the card depending on the true status of a Boolean object. Usage: Agent, group or waiting queues based on boolean settings.
* Inactive: Agent card is permanently in the status unavailable (red). Usage: Showing the agent in a cardset, but limit the access to the agent for a longer period. (holiday, sick-leave or other reasons)
(* Important: Presence and boolean status are dependent on the visibility configured on all the monitored objects, eg. agent user objects and monitored boolean objects)

= Integrating Widgets into Website =
Now it is the website admin's turn to integrate the widget into the website. 
To do this, click the [Code] button in the Widgets App at that widget you want to include. A popup appears showing a handful of code lines (HTML and Javascript). 
[[File:Widget-code-popup.png|thumb|Code Popup]]
You can ''copy'' the code lines into clipboard by clicking the [Copy] button. 
You can ''paste'' the code lines from clipboard into your website code. 
There's also a [Download] button. When clicking this button a small HTML file is saved on your local computer. This HTML file can be opened in a browser to preview the widget and test the widget's functionality.

== Content-Security-Policy ==
If the website uses Content-Security-Policy (CSP) it could be necessary to add entries to config sections 'default-src' and 'img-src'.
* The Widget opens a secure websocket connection (wss:)
* The Widget loads images via Data-URL (data:).
* The Widget uses Mail-Links (mailto:).
* The Widget uses Tel-Links (tel:).
<meta
http-equiv="Content-Security-Policy" content="
default-src 'self' '''wss://*.innovaphone.com'''; child-src 'self' '''mailto:''' '''tel:'''; img-src '''data:'''"
/>

= After Integration =
Once your widget is live on the website you can still change and update the widget in the Widgets-App. You can update the list of agents or change any other attribute. As soon as you click the widget's [Save] button any open widget instance in a web browser will update immmediately. No need for the website administrator to update the code.

= Widget-API — Protocol between Website Widget and App Service =
Basically, this section does not matter. To create and use widgets, knowledge about the protocol is not required. 
All who are interested in technical details are welcome to read on.

== Loading the Widget ==

When a widget is loaded in the browser window of the website visitor, a websocket connection is opened to the app service on the innovaphone Application Platform. Once the websocket connection is established it goes like this:
<pre>
[1] {"mt":"Start","uuid":"fadc5da4cae94bfc9434d9957ea08ccb"}
[2] {"mt":"Session","name":"Visitenkarten","lang":"de","strings":{...}}
[3] {"mt":"Info","id":"atlantis","dn":"Atlantis","department":"","phonenumber":"","email":"","company":{},"presence":"online","media":["voice","video","email","chat"],"order":0}
[4] {"mt":"GetPicture","id":"atlantis"}
[5] {"mt":"Info","id":"columbia","dn":"Columbia","department":"","phonenumber":"","email":"","company":{},"presence":"offline","media":["voice","video","email","chat"],"order":1}
[6] {"mt":"GetPicture","id":"columbia"}
[7] {"mt":"IceConfig","stun":"stun.innovaphone.com","turn":"turn.innovaphone.com"}
[8] {"mt":"Picture","id":"atlantis","url":"data:image/jpeg;base64..."}
[9] {"mt":"Picture","id":"columbia","url":"data:image/jpeg;base64..."}
[10] {"mt":"Info","id":"atlantis","dn":"Atlantis","department":"","phonenumber":"","email":"","company":{},"presence":"offline","media":["voice","video","email","chat"],"order":0}
[11] {"mt":"Info","id":"atlantis","dn":"Atlantis","department":"","phonenumber":"","email":"","company":{},"presence":"online","media":["voice","video","email","chat"],"order":0}
</pre>

[1] The "Start" request is sent with the unique id of the widget. 
[2] The app service sends the "Session" response providing the widget's display-name and other parameters. 
[3]-[6] The app service sends "Info" messages for all configured agents. Each "Info" message triggers a "GetPicture" request to get a picture of the agent. 
[7] The app service sends "IceConfig" providing the STUN and TURN config required for media calls. 
[8]-[9] The app service sends "Picture" messages for all agents. 
[10]-[11] The presence of an agent may change over time. Presence updates are provided with "Info" messages.

== Initiating a call ==

<pre>
[1] {"mt":"CreateCall","dest":"atlantis","dn":"Mein Name"}
[2] {"mt":"Channels","cmd":"PROPOSAL","sdp":"..."}
[3] {"mt":"CallInfo","state":"alerting"}
[4] {"mt":"CallInfo","state":"connected","cmd":"SELECT","sdp":"..."}
[5] {"mt":"ClearCall"}
[6] {"mt":"CallInfo","state":"terminated"}
</pre>

[1] "CreatCall" message sets the target of the call ('dest') and the own display name ('dn'). 
[2] "Channels" message provides the media offer for this call. Complete SDP offer is provided. 
[3] "CallInfo" is received giving information about the call's current state. 
[4] Next "CallInfo" is received telling the call was answered and deliviering the remote side's media answer. 
[5] Web site user terminates the call. 
[6] The final "CallInfo" message is received. 

= Troubleshooting =
<big>If an issue can be reproduced</big>

'''*Web visitor in a browser.''' 
The myApps web uses the logging facilities provided by the browser it runs in (i.e. JavaScript function <code>console.log</code>). In most browser this is available as ''Console'' after pressing F12.

'''*The called agent working with myApps client.''' 
The myApps platform services provide more elaborate tracing mechanisms. See ''Troubleshooting'' in [[Reference14r1:Concept_myApps_platform_services#Troubleshooting|Concept myApps platform services]].

'''*Troubleshooting AP Services on the AP.''' 
Troubleshooting a specific App instance on the AP [[Course13:IT_Plus_-_Tools_for_Troubleshooting#App_Service_Logs|Course13:IT_Plus_-_Tools_for_Troubleshooting#App_Service_Logs]]

Go to the AP Manager and select the App instance from the Contact Widgets App.
Click on Diagnose and make sure that the box App is ticked.
[[File:AP-Diagnostics.png|thumb|none|AP-Diagnostics]]
Make sure that the logging of the App instance has been activated.
[[File:AP-DiagnosticsLogging.png|thumb|none|AP-Diagnostics-Logging]]
= Related Articles =
[[Howto14r1:Install_Contact_Widget_App|Howto14r1:Install_Contact_Widget_App]]

Reference14r1:Concept Contact Widgets

2024-02-22T12:08:58Z

Npa: /* Overview */

[[Category:Concept|Conference]]

= Applies To =
* innovaphone PBX from version 14r1
* innovaphone Application Platform

= Requirements =
* innovaphone PBX
* innovaphone Application Platform
* Firmware Version 14r1
* One '''Port License''' is used by the app service to establish a VoIP registration at the PBX
* '''Video License''' (optional) is required to establish video connections [*]
* '''Widget License''' (optional) is required to remove any 'innovaphone' branding from the Widget UI

[*] '''UC License''' can also be used since it includes a '''Video License'''

= What is a Contact Widget? =
A Contact Widget (or Website Widget) is an element that can be added to a website. It offers to website visitors a way to get in contact with agents (e.g. help-desk). Website visitors can start chat sessions (asking questions, getting answers) or can start voice or even video calls.

An nice example for a "Sidebar Widget" can be viewed [https://www.innovaphone.com/de/ip-telefonie/innovaphone-pbx.html here]. 
When you have opened this website the Sidebar Widget comes slowly into view on the right side.

Example of a Business-Cards-Widget:

[[File:Cardset-widget.png]]

Example of a Sidebar-Widget:

[[File:Sidebar-Widget.png]]

= Overview =
[[File:Concept-widgets-overview.png|thumb|Overview]]
The central part of the new Widgets-Concept is the '''Contact-Widgets-App'''.
The Contact Widgets App is installed on the innovaphone Application Platform and it allows a PBX user to define Contact Widgets.

Contact Widgets can be integrated in a Website to offer easy ways to website users to contact '''Agents'''. Agents are PBX users meant to communicate with external clients. 
There are 2 fundamental types of Contact Widgets:
* '''Sidebar Widgets'''
* '''Business Cards Widgets'''

A Sidebar Widget appears one side of the website trying to take as less space as possible. The website visitor can expand the Sidebar Widget if interested. 
A Business Cards Widget appears as integrated part of the website content, offering one (or more) contacts in form of ordinary business cards.

= Configuration =
For non experienced technicians have a look at [[Howto14r1:Install_Contact_Widget_App#Installation]] and follow the installation steps mentioned in the how-to article.

Others:
* Download the 'Contact Widgets App' via App Store.
* Install the App on the App Platform Manager.
* Create an instance for the Widgets App on the Manager. We recommend to use no capital letters and no special characters (also not such as space).
* Create a new PBX Object with the PBX Manager Plugin. (*)
* Assign App to authorized (admin) users, which will be allowed to create/change/delete Contact Widgets.

Experts:
(*) You can also create the PBX Object manually: 
* Create a new object of type "App".
* Give it a "Long Name" ("Contact Widgets") and a Name ("widgets") same as the instance-name.
* Give it a password, same as the instance password.
* On the "App" tab configure URL to App Service on App Platform ("http://<ipaddress-or-dnsname>/<instance-name>/innovaphone-widgets").
* Activate option "Websocket"
* Grant access to APIs: "PbxSignal" (mandatory), "Admin" (optional) and "PbxApi" (mandatory)

= Using the Contact Widgets App =
Click on one of the buttons (depending on what type of widget you want to create):
* [+ Add new sidebar widget]
* [+ Add new cardset widget]
A new (empty) widget is displayed. You can give the widget a name by clicking the pen-symbol. The widget name helps to identify widgets as soon the number of widgets starts to grow. 
You can expand and collaps widgets by clicking the header of each widget.
[[Image:Widget-code-new-widget.png|thumb|New Widget]]

== Creating a new Widget ==

New Widget features and options

*You can add the main contact details for this widget
*Select the default language
*Set your prefered font settings
*Change the colour settings
*Change the margin settings
*z-index

[[Image:Widget-new-widget-features.png|thumb|Widget Features]]

== Adding Agent to Widget ==
You can add and remove Agents to a Widget. Agents can be contacted by external website visitors. 
New agents are added by clicking the [+] button inside the agents container.
[[File:Adding-new-agents.png|thumb|Adding agents]]
A dialog opens where you can define the agent. It all starts with the agent's 'SIP-ID'. That's the dialable PBX user address. You can use the search function to find a PBX user by name.

There are several (optional) attributes you can set for an agent, like 'Display name', 'Phone number', 'Email address' and 'Picture'. A picture can be placed by drag & drop or can be selected from local disk by clicking the placeholder rectangle.

Finally you can define the ways of communication the agent is available for:
* Voice-only calls
* Video calls (including voice)
* Chat
* Email

For a Cardset-Widget the order of agents could be relevant. You can change the order of agents in the Widgets-App by easy drag & drop using the mouse.

Each widget gets a unique ID (uuid) assigned on its initial creation. This uuid is used to identify the widget when it is integrated into a website.

In case of a sidebar widget, the agent's card will be displayed by default depending on its status(availability) unless you checked "Always show widget" under the sidebar settings.

In case of a cardset widget, the agent card will always be shown, but its availability is depending on its status.

The following settings are possible:
* Presence*: Display/availability of the card based on the presence status of the agent. Presence available (green), Presence unavailable, busy (red). Usage: Normal agent based on availability.
* Always online: Permanent display/availability of the card regardless of its presence or busy status. Usage: Multiple consecutive calls to the same destination, an agent with multiple line configuration, a group or waiting queue.
* Boolean*: Display of the card depending on the true status of a Boolean object. Usage: Agent, group or waiting queues based on boolean settings.
* Inactive: Agent card is permanently in the status unavailable (red). Usage: Showing the agent in a cardset, but limit the access to the agent for a longer period. (holiday, sick-leave or other reasons)
(* Important: Presence and boolean status are dependent on the visibility configured on all the monitored objects, eg. agent user objects and monitored boolean objects)

= Integrating Widgets into Website =
Now it is the website admin's turn to integrate the widget into the website. 
To do this, click the [Code] button in the Widgets App at that widget you want to include. A popup appears showing a handful of code lines (HTML and Javascript). 
[[File:Widget-code-popup.png|thumb|Code Popup]]
You can ''copy'' the code lines into clipboard by clicking the [Copy] button. 
You can ''paste'' the code lines from clipboard into your website code. 
There's also a [Download] button. When clicking this button a small HTML file is saved on your local computer. This HTML file can be opened in a browser to preview the widget and test the widget's functionality.

== Content-Security-Policy ==
If the website uses Content-Security-Policy (CSP) it could be necessary to add entries to config sections 'default-src' and 'img-src'.
* The Widget opens a secure websocket connection (wss:)
* The Widget loads images via Data-URL (data:).
* The Widget uses Mail-Links (mailto:).
* The Widget uses Tel-Links (tel:).
<meta
http-equiv="Content-Security-Policy" content="
default-src 'self' '''wss://*.innovaphone.com'''; child-src 'self' '''mailto:''' '''tel:'''; img-src '''data:'''"
/>

= After Integration =
Once your widget is live on the website you can still change and update the widget in the Widgets-App. You can update the list of agents or change any other attribute. As soon as you click the widget's [Save] button any open widget instance in a web browser will update immmediately. No need for the website administrator to update the code.

= Widget-API — Protocol between Website Widget and App Service =
Basically, this section does not matter. To create and use widgets, knowledge about the protocol is not required. 
All who are interested in technical details are welcome to read on.

== Loading the Widget ==

When a widget is loaded in the browser window of the website visitor, a websocket connection is opened to the app service on the innovaphone Application Platform. Once the websocket connection is established it goes like this:
<pre>
[1] {"mt":"Start","uuid":"fadc5da4cae94bfc9434d9957ea08ccb"}
[2] {"mt":"Session","name":"Visitenkarten","lang":"de","strings":{...}}
[3] {"mt":"Info","id":"atlantis","dn":"Atlantis","department":"","phonenumber":"","email":"","company":{},"presence":"online","media":["voice","video","email","chat"],"order":0}
[4] {"mt":"GetPicture","id":"atlantis"}
[5] {"mt":"Info","id":"columbia","dn":"Columbia","department":"","phonenumber":"","email":"","company":{},"presence":"offline","media":["voice","video","email","chat"],"order":1}
[6] {"mt":"GetPicture","id":"columbia"}
[7] {"mt":"IceConfig","stun":"stun.innovaphone.com","turn":"turn.innovaphone.com"}
[8] {"mt":"Picture","id":"atlantis","url":"data:image/jpeg;base64..."}
[9] {"mt":"Picture","id":"columbia","url":"data:image/jpeg;base64..."}
[10] {"mt":"Info","id":"atlantis","dn":"Atlantis","department":"","phonenumber":"","email":"","company":{},"presence":"offline","media":["voice","video","email","chat"],"order":0}
[11] {"mt":"Info","id":"atlantis","dn":"Atlantis","department":"","phonenumber":"","email":"","company":{},"presence":"online","media":["voice","video","email","chat"],"order":0}
</pre>

[1] The "Start" request is sent with the unique id of the widget. 
[2] The app service sends the "Session" response providing the widget's display-name and other parameters. 
[3]-[6] The app service sends "Info" messages for all configured agents. Each "Info" message triggers a "GetPicture" request to get a picture of the agent. 
[7] The app service sends "IceConfig" providing the STUN and TURN config required for media calls. 
[8]-[9] The app service sends "Picture" messages for all agents. 
[10]-[11] The presence of an agent may change over time. Presence updates are provided with "Info" messages.

== Initiating a call ==

<pre>
[1] {"mt":"CreateCall","dest":"atlantis","dn":"Mein Name"}
[2] {"mt":"Channels","cmd":"PROPOSAL","sdp":"..."}
[3] {"mt":"CallInfo","state":"alerting"}
[4] {"mt":"CallInfo","state":"connected","cmd":"SELECT","sdp":"..."}
[5] {"mt":"ClearCall"}
[6] {"mt":"CallInfo","state":"terminated"}
</pre>

[1] "CreatCall" message sets the target of the call ('dest') and the own display name ('dn'). 
[2] "Channels" message provides the media offer for this call. Complete SDP offer is provided. 
[3] "CallInfo" is received giving information about the call's current state. 
[4] Next "CallInfo" is received telling the call was answered and deliviering the remote side's media answer. 
[5] Web site user terminates the call. 
[6] The final "CallInfo" message is received. 

= Troubleshooting =
<big>If an issue can be reproduced</big>

'''*Web visitor in a browser.''' 
The myApps web uses the logging facilities provided by the browser it runs in (i.e. JavaScript function <code>console.log</code>). In most browser this is available as ''Console'' after pressing F12.

'''*The called agent working with myApps client.''' 
The myApps platform services provide more elaborate tracing mechanisms. See ''Troubleshooting'' in [[Reference14r1:Concept_myApps_platform_services#Troubleshooting|Concept myApps platform services]].

'''*Troubleshooting AP Services on the AP.''' 
Troubleshooting a specific App instance on the AP [[Course13:IT_Plus_-_Tools_for_Troubleshooting#App_Service_Logs|Course13:IT_Plus_-_Tools_for_Troubleshooting#App_Service_Logs]]

Go to the AP Manager and select the App instance from the Contact Widgets App.
Click on Diagnose and make sure that the box App is ticked.
[[File:AP-Diagnostics.png|thumb|none|AP-Diagnostics]]
Make sure that the logging of the App instance has been activated.
[[File:AP-DiagnosticsLogging.png|thumb|none|AP-Diagnostics-Logging]]
= Related Articles =
[[Howto14r1:Install_Contact_Widget_App|Howto14r1:Install_Contact_Widget_App]]

Reference14r1:Concept Contact Widgets

2024-02-22T12:08:24Z

Npa: /* What is a Contact Widget? */

[[Category:Concept|Conference]]

= Applies To =
* innovaphone PBX from version 14r1
* innovaphone Application Platform

= Requirements =
* innovaphone PBX
* innovaphone Application Platform
* Firmware Version 14r1
* One '''Port License''' is used by the app service to establish a VoIP registration at the PBX
* '''Video License''' (optional) is required to establish video connections [*]
* '''Widget License''' (optional) is required to remove any 'innovaphone' branding from the Widget UI

[*] '''UC License''' can also be used since it includes a '''Video License'''

= What is a Contact Widget? =
A Contact Widget (or Website Widget) is an element that can be added to a website. It offers to website visitors a way to get in contact with agents (e.g. help-desk). Website visitors can start chat sessions (asking questions, getting answers) or can start voice or even video calls.

An nice example for a "Sidebar Widget" can be viewed [https://www.innovaphone.com/de/ip-telefonie/innovaphone-pbx.html here]. 
When you have opened this website the Sidebar Widget comes slowly into view on the right side.

Example of a Business-Cards-Widget:

[[File:Cardset-widget.png]]

Example of a Sidebar-Widget:

[[File:Sidebar-Widget.png]]

= Overview =
[[File:Concept-widgets-overview.png|thumb|Overview]]
The central part of the new Widgets-Concept is the '''Contact-Widgets-App'''.
The Contact Widgets App is installed on the innovaphone Application Platform and it allows a PBX user to define Contact Widgets.

Contact Widgets can be integrated in a Website to offer easy ways to website users to contact '''Agents'''. Agents are PBX users meant to communicate with external clients. 
There are 2 fundamental types of Contact Widgets:
* '''Sidebar Widgets'''
* '''Cardset Widgets'''

A Sidebar Widget appears one side of the website trying to take as less space as possible. The website visitor can expand the Sidebar Widget if interested. 
A Cardset Widget appears as integrated part of the website content, offering one (or more) contacts in form of ordinary business cards.

= Configuration =
For non experienced technicians have a look at [[Howto14r1:Install_Contact_Widget_App#Installation]] and follow the installation steps mentioned in the how-to article.

Others:
* Download the 'Contact Widgets App' via App Store.
* Install the App on the App Platform Manager.
* Create an instance for the Widgets App on the Manager. We recommend to use no capital letters and no special characters (also not such as space).
* Create a new PBX Object with the PBX Manager Plugin. (*)
* Assign App to authorized (admin) users, which will be allowed to create/change/delete Contact Widgets.

Experts:
(*) You can also create the PBX Object manually: 
* Create a new object of type "App".
* Give it a "Long Name" ("Contact Widgets") and a Name ("widgets") same as the instance-name.
* Give it a password, same as the instance password.
* On the "App" tab configure URL to App Service on App Platform ("http://<ipaddress-or-dnsname>/<instance-name>/innovaphone-widgets").
* Activate option "Websocket"
* Grant access to APIs: "PbxSignal" (mandatory), "Admin" (optional) and "PbxApi" (mandatory)

= Using the Contact Widgets App =
Click on one of the buttons (depending on what type of widget you want to create):
* [+ Add new sidebar widget]
* [+ Add new cardset widget]
A new (empty) widget is displayed. You can give the widget a name by clicking the pen-symbol. The widget name helps to identify widgets as soon the number of widgets starts to grow. 
You can expand and collaps widgets by clicking the header of each widget.
[[Image:Widget-code-new-widget.png|thumb|New Widget]]

== Creating a new Widget ==

New Widget features and options

*You can add the main contact details for this widget
*Select the default language
*Set your prefered font settings
*Change the colour settings
*Change the margin settings
*z-index

[[Image:Widget-new-widget-features.png|thumb|Widget Features]]

== Adding Agent to Widget ==
You can add and remove Agents to a Widget. Agents can be contacted by external website visitors. 
New agents are added by clicking the [+] button inside the agents container.
[[File:Adding-new-agents.png|thumb|Adding agents]]
A dialog opens where you can define the agent. It all starts with the agent's 'SIP-ID'. That's the dialable PBX user address. You can use the search function to find a PBX user by name.

There are several (optional) attributes you can set for an agent, like 'Display name', 'Phone number', 'Email address' and 'Picture'. A picture can be placed by drag & drop or can be selected from local disk by clicking the placeholder rectangle.

Finally you can define the ways of communication the agent is available for:
* Voice-only calls
* Video calls (including voice)
* Chat
* Email

For a Cardset-Widget the order of agents could be relevant. You can change the order of agents in the Widgets-App by easy drag & drop using the mouse.

Each widget gets a unique ID (uuid) assigned on its initial creation. This uuid is used to identify the widget when it is integrated into a website.

In case of a sidebar widget, the agent's card will be displayed by default depending on its status(availability) unless you checked "Always show widget" under the sidebar settings.

In case of a cardset widget, the agent card will always be shown, but its availability is depending on its status.

The following settings are possible:
* Presence*: Display/availability of the card based on the presence status of the agent. Presence available (green), Presence unavailable, busy (red). Usage: Normal agent based on availability.
* Always online: Permanent display/availability of the card regardless of its presence or busy status. Usage: Multiple consecutive calls to the same destination, an agent with multiple line configuration, a group or waiting queue.
* Boolean*: Display of the card depending on the true status of a Boolean object. Usage: Agent, group or waiting queues based on boolean settings.
* Inactive: Agent card is permanently in the status unavailable (red). Usage: Showing the agent in a cardset, but limit the access to the agent for a longer period. (holiday, sick-leave or other reasons)
(* Important: Presence and boolean status are dependent on the visibility configured on all the monitored objects, eg. agent user objects and monitored boolean objects)

= Integrating Widgets into Website =
Now it is the website admin's turn to integrate the widget into the website. 
To do this, click the [Code] button in the Widgets App at that widget you want to include. A popup appears showing a handful of code lines (HTML and Javascript). 
[[File:Widget-code-popup.png|thumb|Code Popup]]
You can ''copy'' the code lines into clipboard by clicking the [Copy] button. 
You can ''paste'' the code lines from clipboard into your website code. 
There's also a [Download] button. When clicking this button a small HTML file is saved on your local computer. This HTML file can be opened in a browser to preview the widget and test the widget's functionality.

== Content-Security-Policy ==
If the website uses Content-Security-Policy (CSP) it could be necessary to add entries to config sections 'default-src' and 'img-src'.
* The Widget opens a secure websocket connection (wss:)
* The Widget loads images via Data-URL (data:).
* The Widget uses Mail-Links (mailto:).
* The Widget uses Tel-Links (tel:).
<meta
http-equiv="Content-Security-Policy" content="
default-src 'self' '''wss://*.innovaphone.com'''; child-src 'self' '''mailto:''' '''tel:'''; img-src '''data:'''"
/>

= After Integration =
Once your widget is live on the website you can still change and update the widget in the Widgets-App. You can update the list of agents or change any other attribute. As soon as you click the widget's [Save] button any open widget instance in a web browser will update immmediately. No need for the website administrator to update the code.

= Widget-API — Protocol between Website Widget and App Service =
Basically, this section does not matter. To create and use widgets, knowledge about the protocol is not required. 
All who are interested in technical details are welcome to read on.

== Loading the Widget ==

When a widget is loaded in the browser window of the website visitor, a websocket connection is opened to the app service on the innovaphone Application Platform. Once the websocket connection is established it goes like this:
<pre>
[1] {"mt":"Start","uuid":"fadc5da4cae94bfc9434d9957ea08ccb"}
[2] {"mt":"Session","name":"Visitenkarten","lang":"de","strings":{...}}
[3] {"mt":"Info","id":"atlantis","dn":"Atlantis","department":"","phonenumber":"","email":"","company":{},"presence":"online","media":["voice","video","email","chat"],"order":0}
[4] {"mt":"GetPicture","id":"atlantis"}
[5] {"mt":"Info","id":"columbia","dn":"Columbia","department":"","phonenumber":"","email":"","company":{},"presence":"offline","media":["voice","video","email","chat"],"order":1}
[6] {"mt":"GetPicture","id":"columbia"}
[7] {"mt":"IceConfig","stun":"stun.innovaphone.com","turn":"turn.innovaphone.com"}
[8] {"mt":"Picture","id":"atlantis","url":"data:image/jpeg;base64..."}
[9] {"mt":"Picture","id":"columbia","url":"data:image/jpeg;base64..."}
[10] {"mt":"Info","id":"atlantis","dn":"Atlantis","department":"","phonenumber":"","email":"","company":{},"presence":"offline","media":["voice","video","email","chat"],"order":0}
[11] {"mt":"Info","id":"atlantis","dn":"Atlantis","department":"","phonenumber":"","email":"","company":{},"presence":"online","media":["voice","video","email","chat"],"order":0}
</pre>

[1] The "Start" request is sent with the unique id of the widget. 
[2] The app service sends the "Session" response providing the widget's display-name and other parameters. 
[3]-[6] The app service sends "Info" messages for all configured agents. Each "Info" message triggers a "GetPicture" request to get a picture of the agent. 
[7] The app service sends "IceConfig" providing the STUN and TURN config required for media calls. 
[8]-[9] The app service sends "Picture" messages for all agents. 
[10]-[11] The presence of an agent may change over time. Presence updates are provided with "Info" messages.

== Initiating a call ==

<pre>
[1] {"mt":"CreateCall","dest":"atlantis","dn":"Mein Name"}
[2] {"mt":"Channels","cmd":"PROPOSAL","sdp":"..."}
[3] {"mt":"CallInfo","state":"alerting"}
[4] {"mt":"CallInfo","state":"connected","cmd":"SELECT","sdp":"..."}
[5] {"mt":"ClearCall"}
[6] {"mt":"CallInfo","state":"terminated"}
</pre>

[1] "CreatCall" message sets the target of the call ('dest') and the own display name ('dn'). 
[2] "Channels" message provides the media offer for this call. Complete SDP offer is provided. 
[3] "CallInfo" is received giving information about the call's current state. 
[4] Next "CallInfo" is received telling the call was answered and deliviering the remote side's media answer. 
[5] Web site user terminates the call. 
[6] The final "CallInfo" message is received. 

= Troubleshooting =
<big>If an issue can be reproduced</big>

'''*Web visitor in a browser.''' 
The myApps web uses the logging facilities provided by the browser it runs in (i.e. JavaScript function <code>console.log</code>). In most browser this is available as ''Console'' after pressing F12.

'''*The called agent working with myApps client.''' 
The myApps platform services provide more elaborate tracing mechanisms. See ''Troubleshooting'' in [[Reference14r1:Concept_myApps_platform_services#Troubleshooting|Concept myApps platform services]].

'''*Troubleshooting AP Services on the AP.''' 
Troubleshooting a specific App instance on the AP [[Course13:IT_Plus_-_Tools_for_Troubleshooting#App_Service_Logs|Course13:IT_Plus_-_Tools_for_Troubleshooting#App_Service_Logs]]

Go to the AP Manager and select the App instance from the Contact Widgets App.
Click on Diagnose and make sure that the box App is ticked.
[[File:AP-Diagnostics.png|thumb|none|AP-Diagnostics]]
Make sure that the logging of the App instance has been activated.
[[File:AP-DiagnosticsLogging.png|thumb|none|AP-Diagnostics-Logging]]
= Related Articles =
[[Howto14r1:Install_Contact_Widget_App|Howto14r1:Install_Contact_Widget_App]]