URL Scheme Provider

The URL Scheme provider allows you to send messages to channelBar using channelbar:// URLs. This provider is always active by default and requires no configuration — it works as soon as channelBar is running.

The URL Scheme is ideal for:

  • AppleScript – Trigger messages from any scriptable macOS app
  • Automator workflows – Integrate channelBar into automation pipelines
  • Shell scripts – Send notifications from Terminal using open
  • Inter-app communication – Let other macOS applications push messages directly

Because it relies on the standard macOS URL handling mechanism, any application that can open a URL can send messages to channelBar without additional libraries or network configuration.

Sending Messages

To send a message, use the set command with the following URL format:

channelbar://set?channel=CHANNEL&text=MESSAGE

The following parameters are available:

Parameter Required Description
channel Yes Target channel identifier
text or message Yes Message content
source No Source label (e.g., “Jenkins”)
link No URL opened when clicking the message
open No Command or app to execute
args No Arguments for the open command
message_context No JSON metadata for the message
channel_context No Context data for the channel

Note: All parameter values must be URL-encoded. Spaces become %20, special characters like & become %26, and so on.

Managing Channel Context

Channel context allows you to attach persistent key-value data to a channel. This data is available in templates and can be updated independently of messages.

Set context:

channelbar://context-set?channel=CHANNEL&context=VALUE

The context parameter accepts a JSON string that will be merged with the channel’s existing context data.

Remove context:

channelbar://context-remove?channel=CHANNEL

This clears all context data from the specified channel.

Reloading Configuration

You can trigger a configuration reload via URL Scheme. This is useful after externally modifying channel settings.

Reload all channels:

channelbar://config/reload

Reload a specific channel:

channelbar://config/reload?channel=CHANNEL

Triggering Last Message

Re-triggers the last message for a specific channel, causing it to be processed again through the output pipeline (menu bar update, notifications, sounds, etc.).

channelbar://trigger/last?channel=CHANNEL

The channel parameter is required. If no previous message exists for the channel, the command has no effect.

Examples

Shell (Terminal):

open "channelbar://set?channel=alerts&text=Build%20complete&source=CI"

AppleScript:

open location "channelbar://set?channel=test&text=Hello%20World"

Multiple parameters:

open "channelbar://set?channel=deploy&text=v2.1.0%20deployed&source=GitHub%20Actions&link=https%3A%2F%2Fgithub.com%2Fmy%2Frepo%2Freleases"

This example sends a deployment notification to the deploy channel with a source label of “GitHub Actions” and a clickable link to the release page.

Validation Limits

channelBar enforces the following size limits on URL Scheme parameters:

Field Maximum Size
text 10 KB
message_context 7,500 characters
channel_context 1,000 characters
link 2 KB
Channel identifier 64 characters

Messages exceeding these limits will be rejected.

Next
Webhook