Forums/Documentation/Setting up integrations

Hipchat Integration

Skip Moore
posted this on January 06, 2011 09:07

By using targets you can send a message to a Hipchat room letting you know if a ticket has been created or even updated. You will need from Hipchat the room id you want the message to go to and a API key. Login to Hipchat and goto your Admin page, click API Tokens and then Create another token. 

HipChat_-_API_Tokens_skip.png

The easiest way I found to get the room ID is to go to Chat History and click on the room. The ID shows in the URL. 

HipChat_-_History_-_zendesk_skip.png

The Hipchat API documentation can be found here, the specific API to send messages is here. There are four required parameters needed in the POST call in the URL 

Auth required

Yes (details)

Parameters

  • room_id

    Required. ID or name of the room.

  • from

    Required. Name the message will appear be sent from. Must be less than 15 characters long. May contain letters, numbers, -, _, and spaces.

  • message

Required. The message body. Must be valid XHTML. HTML entities must be escaped (e.g.: &instead of &). May contain basic tags: a, b, i, strong, em, br, img. 5000 characters max.

You can also set two more optional parameter. Since target can't accept data other then status the format will be ignored by Zendesk.

  • notify

    Boolean flag of whether or not this message should trigger a notification for people in the room (based on their individual notification preferences). 0 = false, 1 = true. (default: 0)

  • format
    Desired response format: json or xml. (default: json)

To create a target in Zendesk go to Settings > Extensions > Targets and add target. Select URL target from the options. You will have to build the URL you want to send. All messages are sent to the same URL http://api.hipchat.com/v1/rooms/message? the combination of the auth_token and room_id routes the message to the correct room. You can use Zendesk placeholders for the from and message parts of the URL. In the example below I use "Zendesk" as the from and {{ticket.title}} as the message posted to chat. 

 

 We made a slight change to the way targets work. Because Hipchat uses the message and if you set the attribute name to message the target doesn't send the hipchat message block. So just change the target attribute to something like hipchatnotification 

tech_assistant___Edit_url_target.png

 

Now you have to create a trigger to fire the target. I made a simple one based on a tag. It will send the subject line every time the ticket is updated. One thing to note you have to have a message in the trigger message body. Anything will do even just one character. 

Edit trigger image

 

 

Comments

User photo
Drew Baumann

This failed for me on the URL bit. I can send you a screencap if you shoot me an email.

January 13, 2011 17:40
User photo
Skip Moore
Zendesk

@Drew sure can just send it to support@zendesk.com and reference hipchat and Skip

January 14, 2011 15:13
User photo
Skip Moore
Zendesk

Adding a bit more to the hip chat integration. A sidebar widget that can see who's in the room and when the last message was sent. 

Create a custom widget with the following code. 

You have to put your API token and room ID into the widget. Because the widget uses our proxy it will only work for logged in users.

The end result looks like this 
hipchatroom.png 

January 14, 2011 15:31
User photo
Skip Moore
Zendesk

added the ability to pull in messages to the widget

tech_assistant___Forums-1.jpg                           tech_assistant___Forums-2.jpg

February 21, 2011 21:40
User photo
Thomas

When I click "test target" it works fine however when I send a test email the trigger executes the rules however I don't get the notification in the chat room regarding the ticket, so I imagine there is an issue with Zendesk

May 31, 2011 18:55
User photo
Skip Moore
Zendesk

@Thomas I have checked out your hipchat trigger and you have to have a message in the trigger message body. 

PacificHost___Edit_trigger.png

May 31, 2011 20:41
User photo
Skip Moore
Zendesk

Here are some example targets that send clickable links to Hipchat. The key is to use http://meyerweb.com/eric/tools/dencoder/ however remove the {{and}} tags before you encode it and then you need to manually add them {{and}} tags after you encode it.

http://api.hipchat.com/v1/rooms/message?auth_token=AUTH_TOKEN_HERE&room_id=ID_HERE&from=Zendesk&message=Twitter%20Update%3A%20{{ticket.title}} 
That looks like: Twitter Update: Title Only

http://api.hipchat.com/v1/rooms/message?auth_token=AUTH_TOKEN_HERE&room_id=ID_HERE&from=Zendesk&\
message=Server%20Alert%3A%20{{ticket.title}}%20%3Ca%20href%3D%22https%3A%2F%2F{{ticket.url}}%22\
%3EView%20Ticket%3C%2Fa%3E

That looks like: Server Alert: Title Here View Ticket

June 09, 2011 09:17
User photo
Hasso Reifert
nyxus

@Skip: Would you please provide an updated and more detiled instruction on how to use and integrate HipChat into Zendesk. For me neither the target nor the widget seem to work, depite having changed the room id and the auth code.

December 21, 2011 07:50
User photo
Wendy
taskrabbit

For some reason, my URLs are looking a little wonky in HipChat today. I haven't changed anything but the URL encoding I originally did are showing up as simple text: i.e, what used to look like this:

http://i.imgur.com/ZX15E.png

now looks like this:

http://imgur.com/ZX15E,LLP0v#1

March 12, 2012 10:24
User photo
Skip Moore
Zendesk

We made a slight change to the way targets work. Because Hipchat uses the message and if you set the attribute name to message the target doesn't send the hipchat message block. So just change the target attribute to something like hipchatnotification  

March 15, 2012 10:07
User photo
Wendy
taskrabbit

Thanks for the update Skip! They're working fine now :)

March 16, 2012 13:50
User photo
Jay Gibb
cloudsponge

In case anyone else was confused by the back and forth above, here's what worked for me.

1) Make a URL target

(Notice that "message" is not in the Url, it's in the Attribute Name, that's intentional)

2) Make a trigger

  • Title: Notify HipChat of comment update
  • All: nothing in this section
  • Any: Ticket is... Created
  • Any: Ticket is... Updated
  • Perform these actions: Notify target... HipChat
  • Message: "{{ticket.title}}" was updated by {{current_user.email}} (assigned to {{ticket.assignee.first_name}})
May 12, 2012 00:48
User photo
Ben Hadden
tank

With the recent changes to the HipChat API, will this integration support messages formatted as text?

http://blog.hipchat.com/2012/07/10/a-simple-but-powerful-change-to-...

We'd like to @mention people and display emoticons.

July 12, 2012 11:36
User photo
Tom Meeks
webtexts

I used Jay's code and added some html to make the ticket title clickable.  Thanks all for the push!

<a href="http://{{ticket.url}}">{{ticket.title}}</a> was updated by {{current_user.email}} (assigned to {{ticket.assignee.first_name}})

August 03, 2012 14:27
User photo
Allen Lai
bitcasa

Is there a customer website that I can see HipChat in action? Or maybe a demo account? Thanks!

November 07, 2012 11:53
User photo
Justin Seymour
Zendesk

Hey Allen: 

The HipChat widget will be an internal thing, so it's not available for public viewing. Additionally  the widget is optional, since the target does most of the work in sending messages to your HipChat instance. I wish I had more to share! Maybe somebody using the integration could post a few screenshots of their setup. 

http://www.zendesk.com/apps/hipchat

November 08, 2012 09:26
User photo
Gary Sackett
atlassiandevrel

Hey Skip,

Working with a client on their integration - orginally they had their code set to:

{{ticket.title}} {{ticket.url}} {{ticket.id}} {{ticket.latest_comment}}

Had them try:

{{ticket.title}} <a href="http://{{ticket.url}}"></a> {{ticket.id}}

but they are still only seeing the ticket title in Hipchat.  Am I misssing something with the above syntax?

Cheers,

Gary

January 25, 2013 11:01
User photo
Justin Seymour
Zendesk

Hey Gary! 

Were they seeing the URL as expected with those original placeholders? 

January 28, 2013 05:20
User photo
Gary Sackett
atlassiandevrel

Hey Justin,

They are only seeing the ticket title in Hipchat when receiving updates.  They have tried using both:

{{ticket.title}} {{ticket.url}} {{ticket.id}} {{ticket.latest_comment}}

and:

{{ticket.title}} <a href="http://{{ticket.url}}"></a> {{ticket.id}}

Not sure if the syntax is correct?  If so, then I was going to have the client open a ticket with you guys as I am not sure what their Zendesk account is.

Cheers,

Gary

January 28, 2013 11:11
User photo
Justin Seymour
Zendesk

Have them send a ticket in. The syntax looks good to me. The same setup works fine in a trigger. 

January 29, 2013 04:55
User photo
Gary Sackett
atlassiandevrel

Will do Justin - thanks for the support.

Cheers,

Gary

January 29, 2013 12:12
User photo
Ches Martin

Stuffing placeholders into URL parameters instead of being able to use the message block from a trigger is really clumsy -- it should be trivial to format a slightly complex notification message like including ticket title, requestor URL and ticket URL without asking users to understand URL encoding.

The original article says the trigger message can be blank because it is unused, yet in the comments Skip notes that it must contain something (though it won't be used -- confused yet?).

HipChat is a popular enough service at this point IMO that it should be a preset target, not required to be setup as a custom URL with all these awkward workarounds.

March 11, 2013 23:08
User photo
Ches Martin

Actually it does work more intuitively, as per Jay Gibb's comment above (thanks!). The original article just needs an update.

March 12, 2013 01:12
User photo
Jennifer Rowe
Zendesk

Ches,

Thanks for letting us know! We'll work on updating the article.

March 12, 2013 11:25
User photo
Tony So
huronlegal

Also tried to create a clickable link and its not working. We see the link but no luck.

Here is what I have- 

<a href="http://{{ticket.url}}">{{ticket.id}}</a>&color=red&notify&notify=1

April 11, 2013 07:11
User photo
Matt Bonetti
transvault

Is there a way to store the response from a URL target into a field of a ZEN Desk ticket?

So - let's say that I have created a target that calls the rooms/create method on the HipChat API when I update a given ticket. This works fine in that I can make my URL target create the room, but is there a way to save a field (e.g. room_id) from the response that we get back into a field in my ZenDesk?

This is so that I can store the ID of the room created to link the ZenDesk ticket and the Room....

A similar thing I'd like to do would be to call the rooms/history method on the HipChat API, and to add the message history from the linked chat room to the ZenDesk ticket

April 23, 2013 09:18
User photo
Skip Moore
Zendesk

@Matt, Targets are fire and forget kind of things in Zendesk so we can't add the response we get back from the target to the ticket.  I am looking at building a new integration for the New Zendesk interface and will try and make it so you don't have to use a target to send data to a room. The target was so you could be notified in chat when a ticket was created or updated. 

April 23, 2013 09:27
User photo
Aaron Pewtherer
Zendesk

@Tony: We have created a ticket on your behalf. Let us know more what you are seeing.

May 11, 2013 12:33
User photo
Ngan Pham

Hi, how come in the instructions it says that you can leave the message blank...but in one of your comments (Skip Moore), it says a message is required.  Which is the case?  Are messages still required? If so, why does Zendesk require a message when it doesn't apply?

June 06, 2013 21:10
User photo
Aaron Pewtherer
Zendesk

@Nigan: "Message" in the target, which can be blank. "Message" in the Integration parameters, is a comment in a ticket, and is required.

June 07, 2013 11:19
User photo
Steven Klass
pivotalenergysolutions

Much better!!

 

message=<!--?xml version="1.0" encoding="UTF-8" standalone="no"?--> https://api.hipchat.com/v1/rooms/message?auth_token=XXX&room_id...%3Ca+href%3D%22http://{{ticket.url}}%22%3E{{ticket.id}}.+{{ticket.title+|+truncate:100}}%3C/a%3E+{{ticket.description+|+truncate:400}}

July 11, 2013 12:22
User photo
Katie
waveaccounting2

Hey Steven, 

Thanks for this! It works like a charm.  The only thing I'd like to clean up is after the ticket title, it's displaying '--------------------------------------------- ' before the time stamp.  Any thoughts on how to make this line smaller? 

Katie

September 03, 2013 05:04
User photo
Craig Willis
hostanalyticsinc

Loving the integration but also struggling with adding a clickable link to the case.  This is the URL I'm currently using:-

http://api.hipchat.com/v1/rooms/message?auth_token=XXXXXX&room_...

And this is how I've updated it to make the ticket ID clickable but is not work as it says the URL is not valid:-

http://api.hipchat.com/v1/rooms/message?auth_token=XXXXXX&room_... href="http://{{ticket.url}}">{{ticket.id}}</a>:+{{ticket.organization.name}}+-+{{ticket.requester.name}}+-+{{ticket.title}}

Any advice would be gratefully received.

Thanks

Craig

October 01, 2013 21:48
User photo
Jeremy
Zendesk
October 09, 2013 14:26
User photo
Michał Gonciarz

Hi!

I would like to integrate Hipchat with my Zendesk account, but I can't find Manage ==> Targets, here's view from my dashboard: http://awesomescreenshot.com/09c1tjh60a
I think the menus has been updated. 

Can anybody show me where should I define targets?

October 11, 2013 07:59
User photo
Wes Drury
muscogee

@Michal - You can define targets under Sections - "Extensions" which is location at the very bottom of the menu.  See screenshot below.

October 11, 2013 08:09
User photo
Michał Gonciarz

Thank's for quick responding @Wes
I'll check it.

October 11, 2013 16:21
User photo
Kye Hittle
LogMeIn Rescue Beta

HipChat's v2 API now allows you to send private messages to an individual user instead of a room (https://www.hipchat.com/docs/apiv2/method/private_message_user). This would be a great zendesk Target!

But I'm getting an error when I try to create a Target using this API call. Here's the POST URL that I'm trying to use in the Target (my actual token's replaced with [MY_V2_PERS_TOKEN] below for security): 

https://api.hipchat.com/v2/user/123456/message?auth_token=[MY_V2_PE...

POST is selected and I've tried a few different values in Attribute, but I believe this doesn't matter as long as this field is populated. 

When I hit Test Target, I get a big long error javascript alert back that begins: Error during transmission: HTTP client call failed: #&lt;Faraday::Response:0x007f92fef0cda8 @env={:method=&gt;:post, :body=&gt;&quot;{\n  \&quot;error\&quot;: {\n    \&quot;code\&quot;: 400,\n    \&quot;message\&quot;: \&quot;Invalid content type\&quot;,\n    \&quot;type\&quot;: 

Perhaps it is because HipChat expects a JSON-formatted message. The following works successfully at the command line (again my actual token is represented by [MY_V2_PERS_TOKEN] below): 

curl -X POST -d @message.json https://api.hipchat.com/v2/user/123456/message?auth_token=[MY_V2_PE... --header "Content-Type:application/json"

where 'message.json' is a text file containing: 

{
"message": "testing"
}

Thanks in advance for any advice or insight.

October 15, 2013 21:07
User photo
Skip Moore
Zendesk

There's not much we can do with OATH right now; targets can't use it at all.

-Skip

November 18, 2013 08:43
User photo
Katie
waveaccounting2

@jeremy - Tried truncating the title to 75 to see what happened +{{ticket.title+|+truncate:75}} and the ---- amount stayed the same but the text was trunctated. I'm assuming the same would happen if I changed the truncate of description.  Any ideas?

November 18, 2013 10:01
User photo
Bob Novak
Zendesk

Hi Katie. I think you're right - the truncate filter for Liquid should truncate the string down to x characters. I suspect that the integration is filling in the remaining spots of the field with ----s. Are your ticket titles too long for the integration, and causing errors? I don't see in these comments the reason for adding the truncate filter, so can you simply remove it? If not we may want to create a ticket to discuss this in further detail. You can submit a request to support@zendesk.com and we'll be happy to investigate other options.

December 06, 2013 10:32
User photo
Katie
waveaccounting2

Thanks Bob. It's really not a big issue or anything, just aesthetic, and I like fiddling around with the integration. I'll give a few more things a try and will be in touch if need be. Thanks again!

December 06, 2013 14:13
User photo
Matteo Lupatelli
baasbox

Hi! I go into business rules-triggers-add trigger but in "Meet all the following conditions" I don't have tags. I have Ticket:...., Requester:... and Other:Current User.

April 04, 2014 03:51
User photo
Matteo Lupatelli
baasbox

Sorry, it's Ticket:tags... I resolve.

April 04, 2014 03:56
User photo
Laura D.
Zendesk

Glad you were able to sort it out Matteo :)

April 04, 2014 16:03