Message Addressing Schemes

A Message Target URI is an identifier used to identify a target endpoint which acts as a destination for an IMessage object. The target resource represents a lifecycle entry point component or an abstract topic on which recipients can register filters to listen for updates. All Message URIs conform to a subset of RFC 3986.

Syntax

A Message Target URI should adhere to the standard URI syntax: scheme "://" authority ["/" path] ["?" query] ["#" fragment]. It can be divided into 4 parts - scheme, authority, query params, and fragment. If a URI does not follow this syntax or if it fails to follow the rules defined for each individual as mentioned below, the makeMessageBuilder API will throw an InvalidArgument error.

Only the scheme, authority, and path portions of the URI are used for addressing.

Scheme

Scheme is the part of URI that precedes the scheme separator: ://. The scheme string is used to convey the protocol that must be followed to route the message to the correct receiver.

Scheme strings must be a single word that contains lower-cased alphanumerics and must not contain any whitespaces. Every URI must start with a non-empty scheme string.

Authority

Authority consists of a host string and a port string separated by a :. However, port specification is not recognized in message URIs.

Host

Host is the part of URI that follows the scheme separator ,://, and precedes either a / or ?. If a / or ? are not included, the URI ends.

Host strings must be a literal * as a wildcard or contain lower-cased alphanumerics. They must not contain any whitespaces but they can have multiple words with periods, ., to indicate hierarchy of the naming scheme. For example, com.amazon.ota. Every URI must contain a non-empty host string after the scheme string and separator.

Path

Path is an optional part of the URI that follows a / (after the host string) and precedes either a ?. If a / or ? are not included, the URI ends.

Paths can be used to identify the function that the receiver of the message must perform after receiving the message.

Path strings must only contain alphanumerics (lower or upper) without any whitespaces but it can have a / between words to indicate nested functionality. Path strings, must be added immediately after the host string or it must be omitted.

Query Params

Query params is an optional string that follows a ? after the path string, or if it doesn’t exist, host string. Query params are not used for routing a message to its target.

Query params are used to pass string data as part of the URI.

Note, it is preferable to use message attachments rather than query params.

Query params must have the following format: ?key1=value1&key2=value2.... The keys and values must only contain alphanumerics (lower or upper) without any whitespaces.

Fragments

Fragment is an optional string that follows a # and can be present after query params. They are usually used to provide any additional metadata on the task to be performed. Fragments must contain alphanumerics (lower or upper) without any whitespaces. As described later in the document, fragments are used in limited circumstances for routing a message to its target.

URI Schemes in Vega Messaging

Launching and Deep linking Schemes

Common characteristics:

• Filter Specification: Manifest only
• Configurable Message Priority: No. Handled Immediately.
• Supports Inline Message Response: Yes

PKG Scheme (pkg)

The pkg scheme allows you to directly address lifecycle components by name.

Format: pkg://<component-id>

Example: pkg://com.amazon.lcm.test.main

Filter Matching: Host

Notes:

• The host string is a component ID from an app manifest.
• This is the only scheme that third party app developers can use to define new messages.
• You identify the lifecycle component to launch.

OS Scheme (os)

The OS scheme offers a platform-independent method for accessing core operating system functions, such as launching the home screen or settings app.

Format: os://<use-case>[<sub-page>]

Examples:

• os://settings - Settings main page
• os://home - Used to identify the component that gets pinned to the backstack as the default app
• os://browser - Used to launch default browser

Filter Matching: Host + Path

Access requirement: Apps must add following section in their manifest to get access to OS scheme URIs.

[[wants.module]]
id = "/com.amazon.kepler.os_messages@IOsMessageModule"

Amzns Scheme (amzns)

The amzns scheme is consumed by the package manager to launch an app based on the identifier provided in the query parameters.

Format: amzns://apps[/path]?<identifier_type>=<identifier_value>

Examples:

• amzns://apps?si=ABCD1234
• amzns://apps?p=com.foo.bar
• amzns://apps?asin=ABCD1234

Filter Matching: Host

Access requirement: Apps MUST add following section in their manifest to get access to Amzns scheme URIs.

[[wants.module]]
id = "/com.amazon.kepler.os_messages@IOsMessageModule"

Notes:

• The host string must be "apps".
• The identifier type must be one of si, p, or asin where si stands for store identifier (Amazon or a different app store), p stands for package id as listed in the manifest of the app and asin stands for the Amazon app store identifier.
• If no such app is present on the device, the default app store, if present, is launched.
• No other app is permitted to install a message target for this URI.

Http, Https Scheme (http, https)

The http and https schemes allow an app to open web URIs targeting websites that normally open in the browser.

Format: {http/https}://<host>[<path>][?query_params]

Example: https://www.amazon.com/shop

Filter Matching: Host + Path

Notes:

• By deep linking to content within the app using standard web URIs, the app developer can gracefully fallback to their website on devices that do not have the app installed.
• Prefer https over http as it is more secure and prevents accidental leakage of privacy-sensitive user information.

Custom Scheme

Custom schemes are defined by apps, allowing an app to be launched directly from another app or website.

Format: <custom-scheme>://[<host>[<path>]][?query_params]

Example: livetv://watchnow

Filter Matching: Host + Path

Notes:

• The scheme must be defined with the correct package ID in the config file.
• There are no restrictions on the host and path.
• In comparison to http, custom schemes can only be intercepted after the app is installed and offer no fallback in scenarios where the app is not installed.
• Prefer https over custom schemes.

Eventing Schemes

Common characteristics:

• Filter Matching: Host + Path
• Filter Specification: Runtime only

Broadcast Scheme (broadcast)

The broadcast scheme URI is an event topic identifier that allows a publisher to distribute messages to all registered subscribers.

Format: broadcast://*/<reverse-dns-namespace>/<topic>/<sub-topic>

Example: broadcast://*/com.amazon.idle/state/idle/screensaver

Notes:

• Configurable Message Priority: No. Delivered Immediately except for Task Manager launches.
• Supports Inline Message Response: No.

Unicast Scheme (unicast)

A unicast scheme URI is an event topic identifier that allows a publisher to distribute messages to a specific subset of registered subscribers based on their package ID.

Format: unicast://*/<reverse-dns-namespace>.<topic>/<sub-topic>

Example: unicast://*/com.amazon.push-service/force-ota

Notes:

• Configurable Message Priority: Yes. Use Immediate or Deferred.
• Supports Inline Message Response: Yes.

Support for Android intent-style URIs

Kepler Messaging primarily uses a URI-based system. However, to maintain compatibility with existing Fire OS apps, limited support for intent-style URIs is available. Use this compatibility feature be used sparingly.

HTTPS URIs are the preferred method for ensuring cross-platform compatibility. App developers should use standard URI schemes as intent-style URIs might not be supported in the future.

Custom schemes, amzns, amzn, http, and https support intent fragments at the end of the URI. In addition, the following URI representations of the intent object may be used with Kepler Messaging.

Common characteristics for all intent-based schemes:

• Filter Specification: Manifest only
• Configurable Message Priority: No. Handled Immediately.
• Supports Inline Message Response: Yes
• Filter Matching: Intent rules

Fragment Only

Format: #Intent;<key1>=<value1>;<key2>=<value2>;....;end;

Example: #Intent;action=OPEN_NETFLIX_ACTION_2;end;

Notes:

• There can only be one intent fragment per URI.
• key1, key2 etc. are known list of keys supported as part of intents.
• Some keys have restrictions on the data type of values that can be supported.
• This scheme must be defined with the fos:// prefix in the manifest. However, at runtime, messages can be sent with URIs without the prefix.

Android-app Scheme (android-app)

Format: android-app://<package-id>[<scheme>[<host>[<path>]]][#<intent-fragment>]

Example: android-app://com.netflix#Intent;action=OPEN_NETFLIX_ACTION;end;

Notes:

• The host string must be the package-id from an app manifest.
• This scheme is not directly supported in the manifest. To define it in a manifest, convert it to a fragment only representation with the fos:// prefix. However, at runtime, messages can be sent with these URIs without any change.

Intent Scheme (intent)

Format: intent:[//][<host>][<path>][#<intent-fragment>]

Example: intent:#Intent;action=OPEN_NETFLIX_ACTION;end;

Notes:

• // after intent: is necessary if scheme= is present in the URI.
• No host or path should be present in the fragment.
• This scheme is not directly supported in the manifest. To define it in a manifest, convert it to a fragment only representation with the fos:// prefix. However, at runtime, messages can be sent with these URIs without any changes.

Supported Fragment Keys

Intent keys supported and their restrictions are listed in the table below:

Key	Value type	Component Resolution	Allowed in the URI	Multiple items in single uri okay?
action	string	yes	yes	no
category	string	yes	yes	no
package	string	yes	yes	N/A
component	string	yes	yes	N/A
scheme	string	yes	yes	N/A
S.<>	string	no	yes	yes A key foo cannot repeat with a different type. A repeating key foo of the same type is overwritten.
B.<>	boolean	no	yes	yes A key foo cannot repeat with a different type. A repeating key foo of the same type is overwritten.
b.<>	byte	no	yes	yes A key foo cannot repeat with a different type. A repeating key foo of the same type is overwritten.
c.<>	char	no	yes	yes A key foo cannot repeat with a different type. A repeating key foo of the same type is overwritten.
d.<>	double	no	yes	yes A key foo cannot repeat with a different type. A repeating key foo of the same type is overwritten.
f.<>	float	no	yes	yes A key foo cannot repeat with a different type. A repeating key foo of the same type is overwritten.
i.<>	int	no	yes	yes A key foo cannot repeat with a different type. A repeating key foo of the same type is overwritten.
l.<>	long	no	yes	yes A key foo cannot repeat with a different type. A repeating key foo of the same type is overwritten.
s.<>	short	no	yes	yes A key foo cannot repeat with a different type. A repeating key foo of the same type is overwritten.

Related topics

• Messaging User Guide
• Linking

---

Last updated: Sep 30, 2025