Overview

The manifest is your App's configuration that should be registered in Pumble.
All the information that Pumble needs to know about your app exists in that configuration.

This guide will show you how you can manually create and update your apps.
You can also use pumble-cli instead of maintaining your apps manually, which will automate this process for you and will expose only the relevant details.

INFO

Your app's manifest will be served on this URL:

https://{APP_HOST_URL}/manifest

Creating an app

To manually create an app with a manifest you should send a request to this Pumble API endpoint:

POST https://api-ga.pumble.com/workspaces/{workspace_id}/workspaceUsers/{workspace_user_id}/apps

with this json body see Manifest Payload:

{
    "name": "my_app", 
    "displayName": "My App",
    "bot": true,
    "botTitle": "My App Bot Description",
    "socketMode": false,
    "scopes": {
        "botScopes": [
            "messages:read",
            "messages:write"
        ],
        "userScopes": [
            "messages:read",
            "messages:write"
        ]
    },
    "shortcuts": [
        {
            "shortcutType": "ON_MESSAGE",
            "url": "https://myapp.com/onmessage",
            "name": "message_shortcut",
            "displayName": "Message Shortcut",
            "description": "Message Shortcut Description"
        },
        {
            "shortcutType": "GLOBAL",
            "url": "https://myapp.com/global",
            "name": "global_shortcut",
            "displayName": "Global Shortcut",
            "description": "Global Shortcut Description"
        }
    ],
    "slashCommands": [
        {
            "command": "/my_slash_command",
            "url": "https://myapp.com/slash",
            "description": "Google Calendar commands",
            "usageHint": "/my_slash_command [first][second]"
        }
    ],
    "eventSubscriptions": {
        "url": "https://myapp.com/events",
        "events": [
            "APP_UNAUTHORIZED",
            "APP_UNINSTALLED",
            "NEW_MESSAGE"
        ]
    },
    "blockInteraction": {
        "url": "https://myapp.com/block_interaction"
    },
    "viewAction": {
        "url": "https://myapp.com/view_action"
    },
    "dynamicMenus": [
        {
            "url": "https://myapp.com/dynamic_menu",
            "onAction": "onDynamicItemSelect"
        }
    ],
    
    "defaultHomeView": {
        "enabled": true,
        "blocks":[
            { 
                "type": "rich_text",
                "elements":[
                    {
                        "type": "rich_text_section",
                        "elements":[
                            {
                                "type": "text",
                                "text": "Welcome to My App!"
                            }
                        ]
                    }
                ]
            }
        ]
    },
    "redirectUrls": [
        "https://myapp.com/redirect"
    ],
    "helpUrl": "https://myapp.com/help",
    "listingUrl": "https://myapp.com/install-on-pumble",
    "welcomeMessage": "Hello :wave:",
    "offlineMessage": "We are experiencing some issues at the moment. Please try again later"
}

INFO

All the requests to manage your apps, need to you use Authtoken header.
You can find this value in ~/.pumblerc file, under PUMBLE_ACCESS_TOKEN key, after you log in with npx pumble-cli login.

You will get a response with the full Manifest and your app's secrets:

{
	//...your manifest
	"id": "...",
	"clientSecret": "...",
	"appKey": "...",
	"signingSecret": "..."
}

name	description
id	Your app's id. This will be used as the clientId in OAuth2 request. See Authorization.
clientSecret	Your app's clientSecret. This will be used to generate access tokens. See Authorization.
appKey	Your app's secret key. This should be sent on every Pumble request along with the access token. See API
signingSecret	Your app's signing key. Pumble will sign every request that will be sent to your endpoints with this key. See Verifying Signature.

WARNING

Make sure not to share app secrets anywhere.

Updating an app

To update your app you should send the updated manifest in this URL:

PUT https://api-ga.pumble.com/workspaces/{workspace_id}/workspaceUsers/{workspace_user_id}/apps/{app_id}

The secrets will remain unchanged.

Listing your apps

To view a list of your created apps use this URL:

GET https://api-ga.pumble.com/workspaces/{workspace_id}/workspaceUsers/{workspace_user_id}/apps/mine

This list will not return secrets for every app.

Get your app manifest (along with its secrets)

To get the full app manifest along with the secrets use this URL:

GET https://api-ga.pumble.com/workspaces/{workspace_id}/workspaceUsers/{workspace_user_id}/apps/mine/{app_id}

Delete your app

To permanently delete your unpublished app use this URL:

DELETE https://api-ga.pumble.com/workspaces/{workspace_id}/workspaceUsers/{workspace_user_id}/apps/{app_id}

Manifest Payload

name	type	required	default	description
name	String	true	-	The name identifier for your app
displayName	String	true	-	The name that will be shown for your app. This also will be the name of the bots created when this app is installed
bot	Boolean	true	-	This specifies if your app should create a bot user when installed or not
botTitle	String	false	-	The description of your app that will be shown on the bot's profile
socketMode	Boolean	false	-	If this is set to true, all your of your app communication with Pumble will be done via websockets. Recommended for development mode only, as other users won't be able to authorize the app if HTTP endpoints are not enabled.
scopes	Scopes	true	-	Scopes that your app will use for both authorized users and your bot
shortcuts	Shortcut[]	true	-	Global and message shortcuts definitions
slashCommands	SlashCommand[]	true	-	Slash commands definitions
eventSubscriptions	Events	true	-	Event subscriptions definitions
blockInteraction	BlockInteraction	false	null	Object where you specify the URL for your app's block interaction handlers
viewAction	ViewAction	false	null	Object where you specify the URL for your app's view action handlers
defaultHomeView	DefaultHomeView	false	null	Your app's default home view. It will be displayed to all workspace users after the app is installed, until it is overriden by a custom home view.
redirectUrls	String[]	true	-	The list of redirect URLs that will be used to authorize your app. See Authorization.
helpUrl	String	false	null	A valid URL that Pumble will link for you app in Configure Apps page
listingUrl	String	false	null	A valid URL that will open when user clicks on Install or Authorize in Configure Apps page. If this is not specified, Pumble will open the consent screen for you app, with all the scopes selected and the first redirectUrl in your redirectUrls.
welcomeMessage	String	false	null	This message, if specified, will be sent to all the users in the workspace when your app is first installed
offlineMessage	String	false	null	Whenver you app fails to respond to Pumble trigger requests, this message will be shown as an ephemeral message

Scopes

name	type	required	default	description
botScopes	String[]	true	-	Scopes that your bot will use in an installed workspace when making requests or subscribing to events.
userScopes	String[]	true	-	Scopes that your app will use when making requests, or subscribing on events on behalf of users that have authorized.

Shortcuts

name	type	required	default	description
shortcutType	"ON_MESSAGE" | "GLOBAL"	true	-	Specifies if the shortcut is a global or message shortcut.
url	String	true	-	URL where Pumble will send the signed request when the shortcut is triggered. You should respond to this request within 3 seconds to acknowledge.
name	String	true	-	Unique name across your app for the shortcut. Pumble will send this name when a trigger happens. Maximum length for this field is 32 characters.
displayName	String	true	-	The name that will be shown in Pumble for this shortcut.
description	String	false	null	Description that users will see for this shortcut.

SlashCommands

name	type	required	default	description
command	String	true	-	The actual command that will be typed in Pumble's message editor. It should start with /. Maximum length for this field is 32.
url	String	true	-	URL where Pumble will send the signed request when command is triggered. You should respond to this request within 3 seconds to acknowledge.
description	String	false	null	Description of the command.
usageHint	String	false	null	Usage hint of the command. It should include some hints for the text that should come after the slash command. Maximum length for this field is 55.

Events

name	type	required	default	description
url	String	true	-	URL where Pumble events will be sent. These requests do not need to be acknowledged.
events	String[]	true	-	List of the events you want to subscribe. For more info, read Events

BlockInteraction

name	type	required	default	description
url	String	true	-	URL where Pumble will send the signed request when block interaction is triggered. You should respond to this request within 3 seconds to acknowledge.

ViewAction

name	type	required	default	description
url	String	true	-	URL where Pumble will send the signed request when view action is triggered. You should respond to this request within 3 seconds to acknowledge.

DynamicMenu

name	type	required	default	description
url	String	true	-	URL where Pumble will send the signed request when view action is triggered. You should respond to this request within 3 seconds to acknowledge.
onAction	String	true	-	Action identifier defined by the app (controlled and used on the app's side).

DefaultHomeView

name	type	required	default	description
enabled	Boolean	true	-	Specifies whether the default home view is enabled.
blocks	RichTextBlock[]	true	-	Blocks that define default home view content. Can only contain blocks of type rich_text.