- This line was added.
- This line was removed.
- Formatting was changed.
|Table of Contents|
HipChat is a business chat software suite, either cloud or self-hosted, from Atlassian, the creators of JIRA, Confluence and several other products. Fort further information about the features and capabilities of HipChat please visit the Atlassian website.
Be advised: this feature is available only in Corporate licenses and above (server and cloud).
The HipChat token expires after 1 year. Because of this you are required to regenerate the token in HipChat admin (i.e. generate a new one with the same permissions), and replace the token in dynaBOARD. This is a requirement from Atlassian, not from dynaBOARD.
The integration with dynaBOARD allows the following features. Most of them can be activated or deactivated in the partner settings, depending on your requirements.
- let customer/stakeholder users enter chat without the need for individual HipChat users, directly from dynaBOARD
- on-the-fly creation of personal rooms for chat requests from dynaBOARD
- setting service hours of chat support, to avoid users entering chat when your business is closed
- sending chat request notifications to specific room to inform your staff
- sending notifications to specific room in case of dynaBOARD events
In order to connect dynaBOARD with HipChat, you need the following:
- installed HipChat Server or active HipChat Cloud instance
- installed dynaBOARD Server or active dynaBOARD Cloud instance
- a HipChat user for the connection (rights requirements see below)
- an active token on the aforementioned user (rights requirements see below)
- a room for dynaBOARD notifications (can be any existing room or a new one)
Setup in HipChat
You need an api token on the user you want to use for the connection. Log in to your HipChat web based administration with this user, and go to My Account, then click on Edit Profile on the top right corner. On the left hand menu, click on the top item, called API access. Create a new token, and label it "dynaBOARD". Set the scopes (=rights) to the following:
- View room
- Send messages
- Manage rooms
- Send notifications
- View group
Make sure your user has these rights, else he cannot provide them through the api user.
After creating the token, copy the token key you see in the table - you need it for the dynaBOARD setup (see below).
Setup in dynaBOARD
Log in to dynaBOARD (with your partner user, not the admin user), and go to Settings. Then click on the tab HipChat.
Select "active" under HipChat Integration. Several fields and options will now show up.
Enter the following information into the fields:
- HipChat URL: enter the url of your HipChat instance (cloud or server version)
- Token: Paste the token you copied earlier from your HipChat user area.
After that, click on Check connection. If all works well, you should get a positive response.
Now you need to set the room for the basic notifications dynaBOARD sends to your staff when something happens (events and chat requests). Click on the orange button labeled "...", next to the Notification room ID field. In the modal window select the room you want to use for these notifications. Please consider the following:
- you can use an existing room, or a new one
- invite all staff members, which should react to dynaBOARD events and chat requests, to the room (else they will not see push notifications)
Proceed to "Settings", below.
If an error occurs during connection setup, please check the following before contacting our support team:
- did you enter the token without blank spaces at the beginning or end of the token?
- does the user has sufficient rights for the required actions? Are the scopes set right in HipChat? (see above)
- is the url correct? (just the base url, do not include any path)
- is the HipChat server accessible for dynaBOARD? (if server self-hosted, check firewall settings)
You can customize the integration to your specific needs and requirements.
Show chat button
If you activate this feature, several more options will show up beneath. If deactivated, no chat request from dynaBOARD is possible.
You can decide where to show the chat button for your users. The following options are available:
- menu bar (top): the chat button will appear in the top menu, left of My Profile.
- footer bar (bottom): the chat button will appear in the footer bar, on the left hand side.
- both (top + bottom): the chat button appears on both aforementioned positions.
The following images show the active and inactive button states:
Active button menu bar (top)
Active button footer bar (bottom)
Chat service hours
You can set the service hours here, for when your chat should be available to users.
If you want your chat service to be available, click on the checkbox of the specific weekday, and select the from and to times. Unchecked weekdays mean no chat service is available. Outside of the times, the chat button is displayed as inactive, see below:
Inactive button menu bar (top)
Inactive button footer bar (bottom)
You can let dynaBOARD send notifications to the selected notification room (see above) in case of certain events.
If users log in to dynaBOARD or log out, you can get a notification. You may also select if this only should trigger for customer users, or also for partner users.
If active dynaBOARD sends a notification if a customer user creates a comment.
If active dynaBOARD sends a notification if a customer user creates a new issue.
If active dynaBOARD sends a notification if a customer user approves or disapproves an issue.
When a user clicks on the chat button, a new window opens and redirects him/her to the chat. If no room associated with this user does exist, a new one is created (see below for naming). Additionally, a notification message will be sent to the notification room (see settings above), to inform the staff about a user from dynaBOARD requesting a chat. Your staff users should join this room and activate notifications for it (if not already done globally).
The message in the notification room looks like this one:
A link is already there ("go to room"), as this helps your staff to just click and join the newly created room without the need to search and join it manually - just keeping ways short and the workflow simple.
The user in dynaBOARD gets a screen message in a modal, informing him about the opening of a new window - just in case his popup blocker prohibits this. He may also click on the icon there to open it manually.
In the new window, he will be asked for his name, though we prefill it with the name from dynaBOARD. We cannot skip this step currently, may be in the future if HipChat allows it.
After clicking on "Join room" he will be taken to the webchat interface.
Room naming conventions
The chat rooms, which are created for a user initiating a chat request, are named in the following way:
dynaBOARD: FIRSTNAME LASTNAME
First name and last name are fixed and cannot be changed - they are placeholders for the user name. The prefix ("dynaBOARD") can be changed through custom language files.
The topic part (descriptive text below the room name, when in HipChat) is build as follows:
CUSTOMER_NAME (CUSTOMER_NO) / USER_EMAIL
These are also fixed and cannot be changed. If the user is a partner or admin, only the email address will be shown.
Good to know
Things you should know about the integration:
- Chat availability is set on the partner level. So all users of a partner can access chat based on the settings in the partner area. It is not possible to allow the chat function for some users, but not for others.
- The service hours for your chat are based on the server time. You see the current server time in the partner settings, at the end of the description text under Chat service hours. You might need to do some calculations for your timezone, if it differs from the server timezone (check the web for timezone calc tools).
- If you make changes to the HipChat integration (including service hours), you need to log out and log in again to see the effects - these settings are loaded into the user session when logging in. So even if you do not see the changes during your current session, a user logging in after the changes were made will see them.
- Deleting chat rooms created by dynaBOARD is no problem. You can clean them up after some time, if you want. They are created anew if the user requests a chat again in the future. But beware, do not delete the notification room you selected in the partner settings. If you need to change it, go to the settings and select another one before deleting the old. Renaming the room is no problem.