Interactive Actions

Add interactive elements to your notifications. There are two categories:

URL actions - Open links in Safari (no callback needed)
Interactive actions - Collect user input and POST responses to your callback URL

Action Types

Type	Description	Requires `key`	Requires `callback_url`
`url`	Opens external URL	No	No
`button`	Clickable button	Optional	Yes
`select`	Dropdown menu	Yes	Yes
`text`	Text input field	Yes	Yes
`number`	Numeric input	Yes	Yes
`toggle`	On/off switch	Yes	Yes

URL Actions

Open links directly in Safari. No callback URL required.

JSON

{
  "type": "url",
  "label": "View Build",
  "value": "https://github.com/org/repo/actions/runs/123"
}

Field	Type	Required	Description	Constraints
`type`	string	Yes	Must be `"url"`
`label`	string	Yes	Button text	Max 30 characters
`value`	string	Yes	URL to open	Max 500 characters, valid URL

Button Actions

Clickable buttons that trigger callbacks. Ideal for approve/reject workflows.

JSON

{
  "type": "button",
  "label": "Approve",
  "key": "approve",
  "style": "primary"
}

Field	Type	Required	Description	Constraints
`type`	string	Yes	Must be `"button"`
`label`	string	Yes	Button text	Max 30 characters
`key`	string	No	Identifier for callback	Max 50 characters
`style`	string	No	Visual style	`primary`, `secondary`, `destructive`

Button Styles

primary - Blue button, main action
destructive - Red button, dangerous actions
secondary - Gray button, secondary actions (default)

Select Actions

Dropdown menu for selecting from predefined options.

JSON

{
  "type": "select",
  "label": "Priority",
  "key": "priority",
  "options": [
    {"label": "Low", "value": "low"},
    {"label": "Medium", "value": "medium"},
    {"label": "High", "value": "high"}
  ],
  "value": "medium"
}

Field	Type	Required	Description	Constraints
`type`	string	Yes	Must be `"select"`
`label`	string	Yes	Label text	Max 30 characters
`key`	string	Yes	Identifier for callback	Max 50 characters
`options`	array	Yes	Selection options	Max 10 options
`options[].label`	string	Yes	Display text	Max 50 characters
`options[].value`	string	Yes	Value sent in callback	Max 100 characters
`value`	string	No	Default selection

Text Input Actions

Free-form text entry field.

JSON

{
  "type": "text",
  "label": "Reply",
  "key": "message",
  "placeholder": "Type your message...",
  "multiline": true
}

Field	Type	Required	Description	Constraints
`type`	string	Yes	Must be `"text"`
`label`	string	Yes	Label text	Max 30 characters
`key`	string	Yes	Identifier for callback	Max 50 characters
`placeholder`	string	No	Placeholder text	Max 100 characters
`multiline`	boolean	No	Allow multiple lines	Default: false
`value`	string	No	Default text

Number Input Actions

Numeric input with optional min/max bounds.

JSON

{
  "type": "number",
  "label": "Quantity",
  "key": "quantity",
  "min": 1,
  "max": 100,
  "defaultValue": 10
}

Field	Type	Required	Description	Constraints
`type`	string	Yes	Must be `"number"`
`label`	string	Yes	Label text	Max 30 characters
`key`	string	Yes	Identifier for callback	Max 50 characters
`min`	number	No	Minimum value
`max`	number	No	Maximum value
`defaultValue`	number	No	Default value

Toggle Actions

Boolean on/off switch.

JSON

{
  "type": "toggle",
  "label": "Enable notifications",
  "key": "enabled",
  "value": "false"
}

Field	Type	Required	Description	Constraints
`type`	string	Yes	Must be `"toggle"`
`label`	string	Yes	Label text	Max 30 characters
`key`	string	Yes	Identifier for callback	Max 50 characters
`value`	string	No	Default state	`"true"` or `"false"`

Complete Examples

Approval Buttons

JSON

{
  "title": "Approve Request",
  "body": "Alice requested access to production",
  "callback_url": "https://your-server.com/approvals",
  "actions": [
    {"type": "button", "label": "Approve", "key": "approve", "style": "primary"},
    {"type": "button", "label": "Reject", "key": "reject", "style": "destructive"}
  ]
}

Preview

Approve Request

just now

Alice requested access to production

Complex Form

JSON

{
  "title": "Issue Report",
  "body": "Please provide details",
  "callback_url": "https://your-server.com/issues",
  "actions": [
    {
      "type": "select",
      "label": "Category",
      "key": "category",
      "options": [
        {"label": "Bug", "value": "bug"},
        {"label": "Feature", "value": "feature"}
      ]
    },
    {
      "type": "text",
      "label": "Description",
      "key": "description",
      "placeholder": "Describe the issue...",
      "multiline": true
    },
    {"type": "button", "label": "Submit", "key": "submit", "style": "primary"}
  ]
}

Preview

Issue Report

just now

Please provide details

URL + Interactive Buttons

JSON

{
  "title": "Review PR #42",
  "body": "alice requested your review",
  "callback_url": "https://your-server.com/reviews",
  "actions": [
    {"type": "url", "label": "View PR", "value": "https://github.com/org/repo/pull/42"},
    {"type": "button", "label": "Approve", "key": "approve", "style": "primary"},
    {"type": "button", "label": "Request Changes", "key": "changes", "style": "destructive"}
  ]
}

Preview

Review PR #42

just now

alice requested your review

Constraints

Maximum 5 actions per message
Label max 30 characters
Key max 50 characters
URL max 500 characters (must be valid)
Select options max 10 options
Option label max 50 characters
Option value max 100 characters
Placeholder max 100 characters
callback_url required for interactive actions (not needed for URL-only)

iOS App Behavior

The iOS app handles actions with a polished UX:

Button-Only Actions (no form fields):

Buttons appear directly in message bubbles
Tapping a button immediately sends the callback
Shows loading state during submission
After success, buttons are replaced with a "Submitted" indicator

Actions with Form Fields (select, text, number, toggle):

Tapping a button opens a sheet with the form
Form adapts to content with fields at top, submit button at bottom
Cancel button in top-left toolbar
Full-width submit button at bottom (follows HIG)
Sheet dismisses on successful submission

Callback Result Details:

Tap the "Submitted" or "Failed" indicator to see details
Shows: status code, timestamp, action triggered, callback URL
For forms: shows all submitted form values
Error messages displayed for failed callbacks

Callbacks & Polling - Receive user responses
Ping it Back - Bidirectional workflow examples

Interactive Actions

Action Types

URL Actions

Button Actions

Button Styles

Select Actions

Text Input Actions

Number Input Actions

Toggle Actions

Complete Examples

Approval Buttons

Complex Form

URL + Interactive Buttons

Constraints

iOS App Behavior

Related