= Setting up Hipchat with BitlBee =
{{{#!wiki caution
'''Slack bought hipchat and is discontinuing it''' [[https://www.atlassian.com/blog/announcements/new-atlassian-slack-partnership|(announcement)]]
Hipchat cloud will be discontinued on 2019-02-15.
After that point, this plugin will still be useful for self-hosted variants (server / data center). End-of-life dates for those are available [[https://www.atlassian.com/partnerships/slack/faq#faq-98b17ca3-247f-423b-9a78-70a91681eff0|here]], the last one being 2020-06-30 for hipchat server 2.4. It's unclear if self-hosted hipchat will continue working past that point or if this just means no more support / security updates.
We don't have a strong need to remove that code from bitlbee, but we'll keep it in the codebase until at least 2020-06-30.
}}}
[[https://www.atlassian.com/software/hipchat/overview|Hipchat]] is a chat service by Atlassian that provides an XMPP server. It's the choice of many businesses, as it supports mission critical features like pasting images and having them show up inline in the chat, and silly meme-like things that happen if you type things like "(awwyeah)".
As such, it's only used by people who have no other choice. If you can decide what chat service to use, please get a real XMPP server with real XMPP clients instead.
Official information on their XMPP, including technical details, is available [[http://help.hipchat.com/knowledgebase/articles/64377-xmpp-jabber-support-details|here]]
<
>
== Since BitlBee 3.4.1 ==
!BitlBee 3.4.1 merges most of the "hip-cat" branch which some people have been using for a while. It left out the unstable parts, which might be included in a later release. If you needed those, read the section below.
=== Initial setup ===
The 'hipchat' account type does not work with the libpurple backend. If you are using it, you'll have to either switch to a version without libpurple or configure it the old way.
If you had a "jabber" account with hipchat, delete it with {{{account jabber del}}} (ensure it's the correct one before doing that)
Use the same account username you'd use in the official client, and protocol "hipchat" instead of "jabber":
{{{
account add hipchat your@email.com
account hipchat on
}}}
If you are using a private hipchat server, after creating the account, you may change the server using:
{{{
account hipchat set server
}}}
=== Groupchats in 3.4.2 ===
Since 3.4.2 you can add channels by their name:
{{{
chat add hipchat "Chat Name" #channel_name
/join #channel_name
}}}
Behind the scenes, what this does is:
1. Lowercase {{{Chat Name}}} to {{{chat name}}}
2. Replace all spaces and special characters with underscores: {{{chat_name}}}
3. Add the {{{123456_}}} and {{{@conf.hipchat.com}}} from above
And it works quite well, even with edge cases! If it doesn't, feel free to complain.
=== Groupchats in 3.4.1 ===
You can also find the JID from the [[https://hipchat.com/account/xmpp|the XMPP/Jabber info section of your account settings]], and create a channel for it like this:
{{{
chat add hipchat 123456_chat_name@conf.hipchat.com #channel_name
/join #channel_name
}}}
That's all.
=== Don't get room history upon connect ===
"Room history is automatically sent when joining a room unless your JID resource is “bot”." You can set it using:
{{{
account hipchat set resource bot
}}}
Not that all contacts are shown as offline then.
<
>
-----
<
>
== hip-cat branch ==
The hip-cat branch is where all of this started. Right now, the only difference is that it fetches the channel list from the server and lets you "/join" them directly. This feature has a few bugs, so it was excluded from the merge. If you feel like trying it out, read on.
For debian/ubuntu, builds should be available in the APT repo at http://code.bitlbee.org/debian/ (just pick hip-cat branch instead of master)
To get build it manually:
{{{
git clone https://github.com/bitlbee/bitlbee.git
cd bitlbee
git checkout feat/hip-cat
}}}
Then do the rest of the build as usual (assuming you have the build dependencies installed)
{{{
./configure
make
make install
}}}
Or for debian/ubuntu: {{{dpkg-buildpackage}}}
=== Known issues ===
If you have any problems with this branch, please join #bitlbee (irc.oftc.net) and ping me (dx)!
* HTML handling from hipchat bots is still weak.
* You might get some duplicate channels in your list (with underscores added at the end)
* If you use another client (web/desktop/mobile hipchat clients) to join to a channel when bitlbee is connected, you might get an invite from it, and Bad Things™ will happen
<
>
-----
<
>
== Workarounds for bitlbee 3.4 and older (or if you use libpurple) ==
If you can't use the newer releases for any reason, here's the list of workarounds you need to apply.
Again, '''ignore all this if you use 3.4.1 or the hip-cat branch'''.
<
>
=== Initial setup ===
Get your account details from [[https://www.hipchat.com/account/xmpp|this page]], and use your jabber ID here:
{{{
account add jabber 123456_789012@chat.hipchat.com
account jabber set tag hipchat
}}}
The jabber IDs of hipchat accounts are in the format `123456_789012@hipchat.com` where 123456 is the company-wide account ID and 789012 is your user account ID.
Fix nick display by setting nick_source:
{{{
account hipchat set nick_source full_name
}}}
=== Groupchats ===
Groupchats require you to have a "nick" set to your real name (`Givenname Surname`), otherwise you'll get an error on /join ("not-acceptable: Please use the nickname...")
Additionally, the channel names are in the format `#123456_chat_name` where 123456 is the company-wide account ID.
The best way to get this working is to avoid using the usual "invite" method of joining channels and add the channels manually before you join them.
{{{
chat add hipchat 123456_chat_name@conf.hipchat.com #channel_name
channel #channel_name set nick 'Givenname Surname'
}}}
Note that you can't rename channels - you have to remove and re-add them.
=== Highlights/mentions ===
Do `@mention_name` instead of `username:`. Otherwise people won't notice your messages are addressed to them. A great feature.
This mention_name comes from `- ` in the roster. This value isn't parsed by bitlbee, so the only way to get it is enabling [[Debugging|xmlconsole]] or using one of the official clients.
You can use [[https://weechat.org/scripts/source/atcomplete.pl.html/|atcomplete.pl]] to autocomplete in weechat.
=== "Message from unknown participant" when joining channel ===
Since the server sends wrong JIDs for the "from" field (`123456_chat_name@conf.hipchat.com/real name here`), all you can do is using client scripts to fix this up. If you write something to do this, add it here.
Using the `trigger.pl` script from Wouter Coekaerts (download [[http://wouter.coekaerts.be/irssi/trigger|here]]), you can add the following trigger to replace "Message from unknown participant " with a blank string to hide it:
{{{
/TRIGGER ADD -all -nocase -regexp '^Message from unknown participant ' -replace ''
}}}
For weechat:
{{{
/filter add hipchat_unknown_participant * nick_root ^Message from unknown participant
}}}
For emacs erc:
{{{
(defun my-reformat-jabber-backlog ()
(save-excursion
(goto-char (point-min))
(if (looking-at
"^ Message from unknown participant Your Name:")
(replace-match ""))))
(add-hook 'erc-insert-modify-hook 'my-reformat-jabber-backlog)
}}}
=== Set new password ===
{{{
account hipchat set -del password
/oper
}}}
=== Don't get room history upon connect ===
"Room history is automatically sent when joining a room unless your JID resource is “bot”." You can set it using:
{{{
account hipchat set username 123456_789012@chat.hipchat.com/bot
}}}
Not that all contacts are shown as offline then.
=== Debugging ===
If you want to figure out something, you can try enabling the [[Debugging|XMPP xmlconsole]] to your contacts. Good luck with that.