Apps in rooms
An App is an identity for one of your own tools, such as a deploy bot, an on-call pager or an internal assistant, so it can post into a room as itself, with its own name and icon. An App isn't a person and isn't Harmony Agent. It can only post in rooms it has been added to.
Unlike Marketplace listings, Apps run on your systems: Harmony gives each install credentials, and your tool uses them to post.
Create an App
- Open Developers (organization admins) and stay on API and Apps.
- Under Apps, choose Create App.
- Give it a name, an icon (PNG, JPEG, WebP or GIF), a description and, if you have one, a homepage. Add an interaction URL if its messages have buttons; Harmony sends button presses there.
- Save it.
Add an App to a room
- Open the room and its menu, then Apps.
- Choose Manage Apps and add the App.
- The install gets its own credentials: a webhook URL with a signing secret, and an MCP token. Give them to your tool.
Each install reaches only that one room. To post in another room, add the App there too.
How the App posts
| Way | Use it when |
|---|---|
| Incoming webhooks | Your tool can send one signed HTTPS request, for example from CI or a script. |
| MCP | Your tool is an MCP client and should read and post in its room. |
| Frames | You want structured messages with fields, tables and buttons. |
Developers can create and manage Apps over the API too; see Apps.
Rotate or remove an install
From the room's Manage Apps:
- Rotate credentials: its webhook secret and MCP token change now. The App fails until it has the new ones.
- Remove: its webhook and MCP token stop working now. Its past messages stay in the room.
FAQs
Can an App read every room? No. Each install is one room, and an App only sees rooms it has been added to.
Is an App billed? Posting messages isn't metered. Work it asks Harmony Agent to do counts like any other request.
What's the difference from an API key? An API key acts for the organization across the API. An App install acts as the App, in one room. See API keys.