Migrating Hipchat Plugins to Slack
A few months ago, Slack announced our partnership with Atlassian. 👋 Hello and welcome to the all of the new Hipchat and Stride developers moving to the platform.
To make translating Hipchat add-ons into Slack apps a bit simpler, I’ll share some best practices to get started with our APIs, developer tooling, and common platform features.
If you’re just looking to migrate your existing Hubot script, take a look at our adapter and sample code to make migration simpler.
At any point during your migration journey you find yourself thinking well, this guide is nice, but I really wish I could talk to someone to address my specific issue, reach out to our developer support friends over at developers@slack.com and they’ll be able to help.
Alright, let’s dig in.
In Hipchat, developers enhance a team’s experience with add-ons, extending access to information and tools into a familiar context. Depending on the behavior of an add-on, specific permissions, tokens, and APIs are used.
Similarly, Slack has the concept of apps. These have powerful capabilities to bring external services into Slack. Developers can use apps to send messages to a channel, let users trigger actions, and respond to events.
Introducing the Slack APIs
While Slack and Hipchat’s APIs have similarities (like both offering a REST-like interface), the individual endpoints and features don’t have a 1-to-1 mapping, which makes some apps more complex to move over to Slack. That said, it’s helpful to take a step back and look at how your add-on (soon-to-be app 😉) behaves:
- The Web API is used to interact with a workspace directly, whether your app needs to query for a list of users, post a message, or interact with long-lived data. It’s made up of REST-like methods that let you pull and push information to Slack.
- The Events API is for listening for specific events happening in a workspace, like when a user joins a team, a reaction is added to a message, or another event. Event subscriptions are similar to webhook subscriptions in Hipchat, though it’s done from a centralized hub in your app configuration page.
- The RTM API uses WebSockets to receive events and send basic messages to Slack. It’s outdated for most use cases and can become highly resource intensive. However, if you’re developing an app that is limited to outgoing connections, it may be a good fit.
If you want a dive deeper into Slack’s APIs, this article on our blog that details the differences and lists some helpful resources to get started.
🤖 Hubot Slack Adapter While it’s not an API, we know a lot of Hipchat add-ons are built using Hipchat’s Hubot adapter. Slack has maintained a Hubot adapter over the years with sample code and documentation available.
Creating a Slack App
If you’ve never developed a Slack app before, there are a few things in the app creation process worth calling out. To start, you can create a Slack app on your apps page. When you’re developing an app, we recommend installing it to a free workspace dedicated to development and testing.
Once you create your app, you’ll be presented with your app configuration page:
From this point, you have a world of possibilities. If you plan to use the Web API, you’ll need to add scopes so your app has the permissions to call the intended endpoints after a user installs the app. You can add one of the many scopes to your app on the OAuth & Permissions page (under Features). If you’ll be using the Events API and event subscriptions, you can add those on the Event Subscriptions page, as well as specify an endpoint that Slack can send the events your app needs.
After configuring your app with the permissions, events, and features you need, go ahead and install it on your development workspace and begin coding! For a bit more detail on the configuration of the app, take a look at our building Slack apps documentation.
Breaking down feature migration
Sending a message
At one point or another, your app will probably want to send messages to a channel or user in Slack.
Hipchat allows an add-on to send a message to a room by calling their REST API with a specified room and text after configuring the add-on with the send_notification permission scope. Slack has two different ways a developer can post a message:
- The first way uses incoming webhooks. This is the fastest way to start sending messages into a Slack channel. When you configure the incoming webhook on your app configuration page (pictured below), it will generate a unique URL that will let you post a message to a single channel.
- The second is nearly the same as Hipchat’s implementation: Slack’s Web API has a method called
chat.postMessage. This lets you send a message into a channel by calling it with the text you want to send and the associated channel ID. Calling the method requires your app to have thechat.write.userorchat.write.botpermission scope.
💡Either of these methods will allow you to send plain text or markup into Slack, but you can power-up your app by sending interactive elements in your message, such as buttons and menus. Interactive features allow users to take decisive action in the context of the conversation rather than having to context switch to and from another tool.
Responding to user invocation
Whether you want to enable a user to pull analytics, query a database, or create a ticket from within Slack, your app will need to receive invocations from users. In Hipchat, this was achieved primarily with webhook triggers where you could specify a regex pattern to receive events for any matching message text.
In Slack, you can register slash commands. On your app configuration, you can register a trigger connected to your app. When a user is in Slack, they’ll type /<trigger> and your app will receive an event with the message text, user, and associated information. The UI in Slack will even prompt autocompletion of your trigger keyword as a user is typing.
🧠 Making it more intuitive Slash commands can be unintuitive for less technical teammates to discover and use. We recently launched message actions, which allows users to invoke your app from the context of a message. This is perfect for apps that open tickets or tasks, start approval workflows, and more.
Gathering input
Sometimes you need to gather more information from a user than can fit in a single message. Hipchat and Slack both offer dialogs, which allow apps to quickly collect structured information. In Slack, dialogs are part of the interactive message framework, and can be invoked when a user clicks an interactive message (message buttons, message menus, and actions) or a slash command. You’ll receive a trigger_id in the event which you can use to call dialog.open.
🔋 Powering up a workflow Dialogs are an easy way to make workflows simpler for teams inside of Slack. We’ve developed an example app that implements an approval workflow using dialogs.
Migrating your developer tools
Getting a jumpstart
We’ve built a collection of apps that tackle common goals developers build for in Slack. That means if you’re migrating an app that is trying to create actionable notifications, build approval workflows, or capture data with dialogs, we have app blueprints for you to get started! You’ll likely need to customize them to make them fit your team, but they’re a great place to start.
Slack Developer Kits
Slack offers developer tooling to quickly get developers up and running with the APIs. We have in-house SDKs to interact with the Web API in Node and Python. You can use these together with our Events API adapters in Node and Python to build apps that listen and respond to subscribed events.
If your app is using the Hubot framework, fear not! We’ve maintained a Slack Hubot adapter over the years with documentation available that details getting up and running with Slack. The adapter interface is a little different, so we’ve put together sample code that goes over migration of basic features, like posting a message to a channel and responding to reactions.
Other tooling
The rest of our tooling can be found on our API tools page, whether you want to easily test your Slack apps or compose what your app’s messages will look like inside of Slack. It also links out to some community-built tools, like Java and .NET wrappers around our APIs.
If the add-on you want to migrate to Slack is focused on a specific event or action, you may look into an automation framework like Zapier or Workato, which both have extensive support for Slack.
Support
Last and most important is developer support. I’ve mentioned it a few times because we really want you to reach out when you get stuck. You can email us over at developers@slack.com, where we have dedicated support agents ready to help you with migration. You can also reach out to the team on Twitter.
And of course, your source of truth for all things platform is the API site, where we post changelogs, updates, and documentation about all of our platform features.
Curious about what’s next in the near and far future of our platform? Check out our platform roadmap for developers.
