Hipchat Integration

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 Admin > 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

 

Have more questions? Submit a request

Comments

  • Avatar
    Drew Baumann

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

  • Avatar
    Skip Moore

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

  • Avatar
    Skip Moore

    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  

  • Avatar
    Skip Moore

    added the ability to pull in messages to the widget

    tech_assistant___Forums-1.jpg                             tech_assistant___Forums-2.jpg

  • Avatar
    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

  • Avatar
    Skip Moore

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

    PacificHost___Edit_trigger.png

  • Avatar
    Skip Moore

    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

  • Avatar
    Hasso Reifert

    @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.

  • Avatar
    Wendy

    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

  • Avatar
    Skip Moore

    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  

  • Avatar
    Wendy

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

  • Avatar
    Jay Gibb

    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}})
  • Avatar
    Ben Hadden

    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-our-messaging-api/

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

  • Avatar
    Tom Meeks

    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}})

  • Avatar
    Allen Lai

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

  • Avatar
    Justin

    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

  • Avatar
    Gary Sackett

    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}}"](http://%7B%7Bticket.url%7D%7D%22/ "Opens in new window")></a> {{ticket.id}}

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

    Cheers,

    Gary

  • Avatar
    Justin

    Hey Gary! 

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

  • Avatar
    Gary Sackett

    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}}"](http://%7B%7Bticket.url%7D%7D%22/ "Opens in new window")></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

  • Avatar
    Justin

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

  • Avatar
    Gary Sackett

    Will do Justin - thanks for the support.

    Cheers,

    Gary

  • Avatar
    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.

  • Avatar
    Ches Martin

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

  • Avatar
    Jennifer Rowe

    Ches,

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

  • Avatar
    Tony So

    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

  • Avatar
    Matt Bonetti

    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

  • Avatar
    Skip Moore

    @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. 

  • Avatar
    Aaron Pewtherer

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

  • Avatar
    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?

  • Avatar
    Aaron Pewtherer

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

Please sign in to leave a comment.