Due to some maintenance issues, this service has been switched in read-only mode, you can find more information about the why

and how to migrate your plugin documentation in this blogpost

Skip to end of metadata
Go to start of metadata

Plugin Information

View HipChat on the plugin site for more information.

Older versions of this plugin may not be safe to use. Please review the following warnings before using an older version:

For detailed instructions on how to use this plugin please see the GitHub README page.


Version 2.2.1 (Sep 25, 2018)

Version 2.2.0 (Aug 20, 2018)

The plugin documentation has been updated and improved in general.

New Features:

  • BUILD_DESCRIPTION macro is now supported (#88)
  • Support custom card icons per notifications (#101)


  • First successful build should always result in SUCCESS notifications (#105)
  • Handle missing macro implementations more gracefully (#106, #108)
  • Straighten out Jenkins version dependency (#102)
  • Ensure configuration is only migrated during plugin upgrade (JENKINS-44790)

Version 2.1.1 (Feb 15, 2017)


  • BUILD_DURATION in pipeline builds always displayed "0 ms" (JENKINS-41861)
  • The HipChat cards should use HTTPS to display the Jenkins logo (#94) - Note: the cards only work when v2 API is enabled.
  • HIPCHAT_CHANGES_OR_CAUSE and COMMIT_MESSAGE variables weren't working at all in pipeline builds (JENKINS-41861)

Version 2.1.0 (Feb 7, 2017)

  • The $PRINT_FULL_ENV variable is no longer supported.
  • Several tokens that were possible to use in previous versions, are now deprecated and eventually will not be supported. To remain backwards compatible, the plugin still supports all the old tokens, but their replacement to the new tokens are recommended

    Deprecated token

    Supported replacement





















New Features:

  • Support for HipChat cards (#85, JENKINS-32083)
  • Support for token-macro-plugin tokens (#59, #65, #88, #90, JENKINS-34934)


  • Plugin fails with NPE if changeset cannot be computed (#89)
  • Very long notification messages caused HTTP 400 errors (#87)
  • Need ability to turn off blue ocean URLs (#92) -> $BLUE_OCEAN_URL has been introduced to represent these URLs instead. $URL/$BUILD_URL now always results in classic UI links
  • BUILD_DURATION token renders "and counting" messages in pipeline jobs (JENKINS-40461)

Version 2.0.0 (Oct 27, 2016)

The plugin now requires JDK 7 runtime.

New Features:

  • Blue Ocean UI support - the HipChat plugin should now generate URLs that are compatible with Blue Ocean (#82)
  • Expose commit message as a variable, $COMMIT_MESSAGE (when using HTML format) and $COMMIT_MESSAGE_TEXT (when using text format) variables have been added
  • Display "No changes" if no SCM change happened between builds
  • v1/v2 API/OAuth2 tokens are now stored in Jenkins using the Credential API. Existing keys will be migrated across to the new format as part of Jenkins upgrade (JENKINS-27303)
  • Expose $SUCCESS_TEST_COUNT and $SKIPPED_TEST_COUNT as message template variables


  • Fix incorrect link for help text (#76)
  • Small updates to logging statement to make the plugin a bit less verbose
  • Made the help text for message templates more available, should be harder to miss the available variables
  • Plugin ignored proxy authentication settings (JENKINS-33214)

Version 1.1.0 (Oct 27, 2016)

The release build was terminated half-way in the process due to a socket timeout. Usage of 1.1.0 version is NOT recommended.

Version 1.0.0 (Jan 9, 2016)

The plugin now requires at least Jenkins 1.609.2.

New Features:

  • Flexible notification configuration:
    • allow setting room notification, message template and notification color for each notification type (JENKINS-18127, JENKINS-28314, JENKINS-26974, #16, #54)
    • introduce default notifications (can be set under Global settings), which are only triggered if a job has no notifications set up (#30)
    • configuration stored in old format will keep on working
  • Expose failed and total test count in message templates, use $FAILED_TEST_COUNT and $TEST_COUNT respectively (#18)
  • Workflow plugin support (#60, JENKINS-27202)
  • Text format support (#47)


  • Potential NPE when collecting changeset information from git repositories (#55)

Version 0.2.0 (Sept 14, 2015)


  • Fix help message for v2 setting (#41, JENKINS-27304)
  • space in room name resulted in failure with v2 API (#52)
  • ABORTED->SUCCESS didn't result in a BACK_TO_NORMAL notification (#51)
  • noProxyHost setting is not obeyed (JENKINS-29057)

New Features:

  • Improve error handling, output messages to build logs (#9)
  • Room name now can be parameterized (#44, JENKINS-22723)
  • Added extra validation for the "Send As" field with helpful error messages (#46)
  • Improved support for matrix builds, now it's possible to select how and when should the plugin send notifications for Matrix builds (#50)
  • JOB_DISPLAY_NAME macro is now available, should contain the project's display name similarly to pre 0.1.9 notifications (JENKINS-27712)
  • Explicitly enable TLSv* protocols for the outgoing SSL connections (#49)

Version 0.1.9 (Mar 9, 2015)


  • Room setting and notification selection should be per post-build task, not per build (#29, JENKINS-25908)
  • Job configuration won't get updated when global configuration changes (#31, #33, JENKINS-19184, JENKINS-26845)
  • No HipChat notification sent when build status change from "Unstable" to "Back To Normal" (JENKINS-25714)
  • The plugin should set HTTP connect/read timeouts (#22)
  • Incorrect path to help files for config pages (#35)

New Features:

  • Support for HipChat v2 & per-project auth token settings (#11)
  • Allow customization of notification messages (#25)
  • Use full project display name in notifications (#12)
  • Introduce a Test Configuration button on global config page (#24)
  • The configuration pages are now localizable


  1. Unknown User (desbonne)

    It seems like this plugin does not work from behind a web proxy.

    Is this correct, or am I missing something?


  2. Unknown User (jhansche)

    It seems at some point the api.hipchat.com SSL certificate expired, or can no longer be validated in some situations. Is there a way to disable the SSL peer verification for this, or some other way that we can fix the SSL verification error? We haven't received updates from Jenkins or JIRA for a few weeks now. We have internal tools that are also using the API, and after disabling SSL verification in those tools, all started working again. But there doesn't seem to be an option to do that in these plugins.

  3. Unknown User (njspor82)

    It would be great if we could configure auth tokens on a per job basis.  I have several development teams each with their own hipchat rooms and auth tokens.  Having the ability to only set one global token does not help me serve all of my customers.

    github allows this ability by configuring a token/room per respository, it should be simple to implement.

  4. Unknown User (outspoken)

    There are 2 hipchat plugins listed. one works and one does not. This one (1.4) does not work at all for me. The other one (1.0) does work.

    Both are extremely limited so I'm hoping the author will come back and fix things up with the api as it stands today.

  5. Unknown User (lvaughn)

    How would I notify more than one HipChat room?  Is this supported?

    1. Unknown User (csconnell)

      First you set up the Global notifier, then you go to each project and set up the specific settings for rooms, etc.  There is a section called "HipChat Notifications" where you select the Project Room and whether or not you want a start notification (in the code I see settings for other things, but only Project Room and Start Notification in the UI).

      You also need to add a Post-build action of "HipChat Notifications".

      That is how we got everything working.

  6. Unknown User (johnsherwood)

    Neither 1.4 or 1.0 are working for me.  Where would I check in Jenkins for the error messages?  I've looked in the log but there's nothing interesting there.

  7. Unknown User (xorgate)

    Seeing as the author of this plugin hasn't made any releases in 2 years, I plan on writing a new Jenkins+HipChat plugin that targets the HipChat V2 API. I'll keep your requests in mind nick spor, Ken Garland, Leonard Vaughn, and John Sherwood.

    1. Unknown User (orrc)

      Please do not write a separate plugin, but take over maintainership of this plugin. If you post to the jenkinsci-dev mailing list with your intentions, you'll get commit access to this repo.

      1. Unknown User (csconnell)

        I agree .. I think it will just cause confusion to have another plugin that does this.

        Additionally, it looks to me like the original author has code changes in the repo that never went into an update of the plugin itself.  Perhaps a fresh build /release would be a nice start .. has anyone else looked at that?

  8. Unknown User (grayaii)

    I second that!  It'll quickly turn into a maintenance nightmare if 2 plugins with the same functionality exist.

  9. Unknown User (kevcheng)

    I tried to use v0.1.8 plugin with internal hosted HipChat server. It does not seem seeming out any message to HC.

    I tried with both server token and room token. Does the new version use HC v2 API? I tried to test with Curl using the 30 characters server token along with v1 API, it seems working, but the server token with v1 api does not work.

    Anyone who has encountered the same issue with internal HC server?

    1. Unknown User (aldaris)

      The 0.1.9 version now supports v2 API as well, 0.1.8 worked only with v1 API and API tokens.

  10. Unknown User (havramar)

    Tried few official (from Jenkins Plugin Manager) plugins and same effect - "Authorization failed". In addition to that I did not like that I have to use global Auth Token for all jobs and use token created by Admin (because of deprecated APIv1 being used).

    To handle all those issues I have picked manually build plugin that worked for me and updated it with the following:

    • can define Auth Token for each job,
    • can use Room Notification Token that can be created by Room Owner.

    Installation have to be done manually, but it requires only few steps.

    Link to repository: https://github.com/havramar/hipchat-notifier-plugin

    1. Unknown User (aldaris)

      Since 0.1.9 it is possible to define HipChat v2 OAuth2 tokens per build job.

  11. Unknown User (glittle)

    I get this error in the Jenkins System Log: HipChat post may have failed. Response: {"error":{"code":400,"type":"Bad Request","message":"From name must be between 1 and 15 characters."}}

    In the "Configure System" page, I have tried a number of options in the "Send As" field, all to no avail.

    Any ideas?

    1. Unknown User (aldaris)

  12. Unknown User (pashcan)

    I am trying to declutter my job config page and I can't comprehend why HipChat's job-specific configuration and the actual Post-build action are being shown in two different places. Unless I'm missing some rationale to have HipChat Notification section visible by default, does anyone know if it might be possible to prevent it from showing up on all new and already existing job configuration pages even though HipChat is not being added as a build step explicitely?

    Alternatively, I might as well submit a feature request to combine the two.

    1. Unknown User (aldaris)

  13. Unknown User (schniedergers)

    How would I specify a room name with spaces?

    I tried "roomA, My Test Room" as example, but notifications would only post to roomA. My workaround is using the room ID for "My Test Room".

    1. Unknown User (aldaris)

      Hmm, that should have worked, which version of the plugin are you using? Which version of the API?

      1. Unknown User (schniedergers)

        v2 API, 0.1.9 plugin, on Jenkins 1.609.1.

        I created a room "Hip Chat".

        Specifying 'Hip Chat' as room in the plugin config does not result in sending a message. Using a room "Hip-Chat" works.


        Jun  9 10:35:22 ip-172-29-0-188 [jenkins]: Jun 09, 2015 10:35:22 AM jenkins.plugins.hipchat.impl.HipChatV2Service publish
        Jun  9 10:35:22 ip-172-29-0-188 [jenkins]: INFO: Posting: "Hip Chat" to Ignore this message: green
        Jun  9 10:35:23 ip-172-29-0-188 [jenkins]: Jun 09, 2015 10:35:23 AM jenkins.plugins.hipchat.impl.HipChatV2Service publish
        Jun  9 10:35:23 ip-172-29-0-188 [jenkins]: WARNING: HipChat post may have failed. ResponseCode: 404, Response: {
        Jun  9 10:35:23 ip-172-29-0-188 [jenkins]:   "error": {
        Jun  9 10:35:23 ip-172-29-0-188 [jenkins]:     "code": 404,
        Jun  9 10:35:23 ip-172-29-0-188 [jenkins]:     "message": "Room not found",
        Jun  9 10:35:23 ip-172-29-0-188 [jenkins]:     "type": "Not Found"
        Jun  9 10:35:23 ip-172-29-0-188 [jenkins]:   }
        Jun  9 10:35:23 ip-172-29-0-188 [jenkins]: }
        1. Unknown User (aldaris)

          I've been able to reproduce this, and it appears that this is related to the v2 API, should work fine with v1 API... See also: https://github.com/jenkinsci/hipchat-plugin/issues/52

  14. Unknown User (david_birkhead)

    Any chance of getting any of the following:

    1. Multi-line posts
    2. last n lines of log in a post


  15. Unknown User (aldaris)

    The notify flag is always set when the color is not green. Currently green color is tied to STARTED, SUCCESS, and BACK_TO_NORMAL build results, in any other cases, the plugin should notify the HipChat room.

    1. Unknown User (jmurray)

      When the build results are SUCCESS and BACK_TO_NORMAL, our team needs to take actions after these specific build results but they're not aware of the status changes in these cases unless they go into the Hipchat room and read the history of messages.  It would be useful to have a config option for determining which statuses should use the notify flag.  

  16. Unknown User (bcreane)

    Just wanted to confirm that for an internal hipchat server, the "room" parameter is a url to the server+room, e.g.


    1. Unknown User (aldaris)

      If you use an internal HipChat server, then you should configure its URL in the Global Jenkins settings, the room name is always "just" the room name.

  17. Unknown User (matthiash)

    We would like to be able to send emoticons via messages from Jenkins, which doesn't work. After some Googling, it appears that this only works when sending text messages, not html. Html is default, so I assume that Jenkins always uses this mode. Would it be possible to make this a configuration parameter?

  18. Unknown User (venkat)

    Is tagging(@xxxxxx) possible with this plugin ?

    1. Unknown User (aldaris)

      Only when using text formatted messages. HTML formatted messages do not allow mentions.

  19. Unknown User (ldh)

    Is there any documentation available on what the expected message template format is? Looks like the existing text has a placeholder: (see (?) for more details on the template format).

    1. Unknown User (aldaris)

      Where exactly are you not seeing the help message? The help text is defined here.

      1. Unknown User (ldh)

        Ok, thanks, I do see the help text in the per-project configuration. What I was looking for was some help text at the global config level: 

        Or on this wiki page (note the '?' placeholder in the last bullet point):

  20. Unknown User (mduffy)

    Hi I've been seeing the following in my build console since the upgrade to 2.0 and the affected messages are not showing up in hipchat.
    It does not seem to affect the job failure messages, or messages from other build processes. One difference between my fail messaging and the other messaging is that I don't override the default message for a build failure, but I do for the other cases.  That may be a red herring though, I haven't had time to do any analysis.
    I haven't had a chance to dig into the problem yet, but I'm posting this as a signpost for any future travellers seeing the same error and welcome feedback on potential root causes.

    ERROR: Build step failed with exception
    at java.util.HashMap.putMapEntries(HashMap.java:500)
    at java.util.HashMap.putAll(HashMap.java:784)
    at jenkins.plugins.hipchat.utils.BuildUtils.collectParametersFor(BuildUtils.java:57)
    at jenkins.plugins.hipchat.model.NotificationType.getMessage(NotificationType.java:89)
    at jenkins.plugins.hipchat.model.NotificationType.getMessage(NotificationType.java:84)
    at jenkins.plugins.hipchat.HipChatNotifier.publishNotificationIfEnabled(HipChatNotifier.java:309)
    at jenkins.plugins.hipchat.HipChatNotifier.notifyOnBuildComplete(HipChatNotifier.java:287)
    at jenkins.plugins.hipchat.HipChatNotifier.perform(HipChatNotifier.java:275)
    at hudson.tasks.BuildStepMonitor$1.perform(BuildStepMonitor.java:20)
    at hudson.model.AbstractBuild$AbstractBuildExecution.perform(AbstractBuild.java:779)
    at hudson.model.AbstractBuild$AbstractBuildExecution.performAllBuildSteps(AbstractBuild.java:720)
    at hudson.model.Build$BuildExecution.cleanUp(Build.java:195)
    at hudson.model.Run.execute(Run.java:1775)
    at hudson.model.FreeStyleBuild.run(FreeStyleBuild.java:43)
    at hudson.model.ResourceController.execute(ResourceController.java:98)
    at hudson.model.Executor.run(Executor.java:404)
    Build step 'HipChat Notifications' marked build as failure

    1. Unknown User (aldaris)

      Do you see an error message like: "Unable to collect the affected files for job x"? This looks like a genuine bug, you can track it here: https://github.com/jenkinsci/hipchat-plugin/issues/89

      1. Unknown User (mduffy)

        I don't see that message, and I've found that if I clear out the custom template section for a message the message will fire (as was the case for the failed job message I mentioned above).

  21. Unknown User (schniedergers)

    Using the hipchat plugin 2.0.0 on Jenkins 2.32.1 with BlueOcean installed - I noticed that using $URL in the message template will insert a BlueOcean URL.

    However - I'd prefer the "classic" URL for the jobs using the plugin. Is there a way to configure it so it'd use classic URL and not BlueOcean?

    1. Unknown User (aldaris)

      This is not configurable, when the blueocean plugin is installed, HipChat will generate blueocean URLs (via https://wiki.jenkins-ci.org/display/JENKINS/Display+URL+API+Plugin).

      1. Unknown User (schniedergers)

        Using $BUILD_URL instead of $URL in the template would get me the classic URL.

        1. Unknown User (aldaris)

          Since version 2.1.0 the blue ocean URLs are now available as a separate variable: $BLUE_OCEAN_URL .

  22. Unknown User (garnerh42)

    If I create an API token as an Admin I will get the "Unexpected response code from HipChat: 401" error.  If I create a room API token, then that works.  I'm testing "working" by the Test Configuration button in the Setting and in my own test job.

    Has anyone run across this before?  I just want one token for all of Jenkins to use.

    I'm using version 2.1.1 for HipChat and my server version is 2.49.

    1. Unknown User (garnerh42)

      Figured out my problem, but not my solution.  I didn't make the connection that the API token I created as an Admin was v1 where the room one was v2.  I need v2.

      So I will continue to look for a solution where I can have one global token for notification to any room rather than a room specific version.  Our HipChat server is set up such that the only users are people and what I really want is a "Jenkins" user.  As a user I can create a token and use that for all Jenkins notifications but then all notification say they come from me with my picture.  I want it to be generic coming from "Jenkins".  The room token would do that but then I'd need a new token for every new room and that's annoying. 

      1. Unknown User (garnerh42)

        Final solution is to use fake email addresses.  IT redirected the emails to an IT specific one.  Once they authenticated the HipChat user they turned off the emails so no direct emails would go to an account that no one was looking at.

        From there people who know the fake email and password can log in and create a token to be used.  In our case we only needed 3 unique senders so not a big deal.

        Hopefully this is useful to someone else in the future.