Documentation

Console

Settings

Sign out

Notifications

Alexa

Amazon Appstore

AWS

Documentation

Support

My Cases

Console

Vega Developer Docs

Home

Get Started

Design and Develop

Publish

Reference

Support

Messaging User Guide

Open Beta Documentation Amazon offers this technical documentation as part of a pre-release, open beta. The features described might change as Amazon receives feedback and iterates on the features. For the most current feature information, see the Release Notes.

This guide details the usage of the Vega Messaging Library (com.amazon.kepler.experimental_mr33.messaging) in the Vega SDK which offers a message passing communication mechanism.

You can use Vega Messaging in a variety of ways, such as launching apps, publishing system changes using broadcasts, and inter-app communication. In contrast to procedure calls, message-oriented communication decouples the execution of the sender and the recipient, so they don't have to be running at the same time. This is accomplished through the use of a centralized broker service called the Message Router.

This mechanism is also a foundation for deferred execution using the Vega Tasks Library (com.amazon.kepler.tasks).

Message Definition and Security

The key concept is that messages are treated as API contracts between the sender and receiver. The message URI, the type of attachment, the sender, and receiver privileges together are a contract that both parties must adhere to for the communication to be successful. Unilateral changes to the message constitute API breakage, leading to delivery or interpretation issues. To maintain message contract integrity, a message definition must be static, where the contract is specified upfront. Both system services and apps can define new messages as explained below. Existing Vega Modules are used for versioning and dependency specification for messages. Vega Modules are the Vega SDK's mechanism for expressing contracts and expressing dependencies upon them. For more information about modules, see the modules documentation in the manifest offers, wants, and needs documentation.

Author Messages

Follow these steps to author messages:

Define a module.
Define messages that are part of it.
Define privileges for using the message at runtime.

Define Module

Define a module and include all messages that are part of the module. Do not use a URI via Message Router unless it is part of a module.

[offers]
[[offers.module]]
id = "/com.amazon.samplepkg.module@IMod1"
includes-messages = [
   "pkg://com.amazon.messaging.mr33.testSendPriv.main",
   "pkg://com.amazon.messaging.mr33.testSendPriv.self_privileges"
]

Define Messages

Define multiple messages by adding as many [[message]] blocks as needed. Specify the URI of the message without query params. Include fragments only when defining legacy URIs (discouraged). Skip adding [[message]] section for pkg:// scheme URIs that are not used outside the vpkg. For more information, see Message Addressing Schemes.

[[message]]
uri = "pkg://com.amazon.messaging.mr33.testSendPriv.main"

[[message]]
uri = "pkg://com.amazon.messaging.mr33.testSendPriv.self_privileges"

Add Security Rules

You can restrict who can send or receive a message by specifying the necessary sender and receiver privileges to the message section.

For example, if you have package called "com.amazon.messaging.mr33.testSendPriv" and you want to restrict its usage to senders that have the com.amazon.security.example1 privilege and receivers that have the com.amazon.security.example2 privilege you define your message as follows.

[[message]]
uri = "pkg://com.amazon.messaging.mr33.testSendPriv.main"
sender-privileges = ["com.amazon.security.example1"]
receiver-privileges = ["com.amazon.security.example2"]

If multiple privileges are specified then the sender or receiver must have all privileges in the list to assume the role. If appropriate, you can use * or self instead of specific privilege strings:

Use * if you want to allow anyone to use the message.
Use self if you want only the vpkg your module is part of to use the message.

You can use these reserved values in the sender-privileges and receiver-privileges independently.

Use Messages

Add Module Dependency

Note: The following sections don't apply if the messages were defined within your own vpkg.

To use the message in a different vpkg, add the following manifest specification. Use the syntax uniformly as a message senders or a receiver. The module is the unit of dependency specification. When depending on a module, you can use all messages defined by the module.

[[wants.module]]
id = "/com.amazon.samplepkg.module@IMod1"

[[needs.module]]
id = "/com.amazon.samplepkg.module@IMod1"

The needs syntax is a stronger form of dependency specification that requires your dependencies to exist before your app can be installed on the device. Refer to the app manifest user guide for more details.

Request Privilege

Unless the message of interest has a self or * include the following section to request the necessary privileges. The following snippet shows how you would to specify that your app wants the privilege to use the testSendPriv.main message defined in /com.amazon.samplepkg.module@IMod1.

[wants]
[[wants.privilege]]
id = "com.amazon.security.example1"

[needs]
[[needs.privilege]]
id = "com.amazon.security.example1"

The needs syntax is a stronger specification than the wants syntax. For more information on needs, see Needs.

Note: If your app requests a runtime privilege, it is only granted after user grants consent. To request consent at runtime, your app must call com.amazon.kepler.security.IKeplerSecurityModule when your app is visible.

Map Messages to Launch Component

Launch every lifecycle component by name by using the pkg:// scheme followed by the name of the component to launch. However, as noted in the message addressing document, there are other URI schemes that do not directly identify the component to launch. In such circumstances, specify additional information in the manifest in the offers.message-target section.

[[offers.message-target]]
uris = [
  "https://demo.com",
  "https://demo.com/example/path"
]
uses-component = "com.demo.main"

Debugging FAQs

Why are my messages not being received even though I registered a filter?

For messages to be received, the message channel that registered the filter should be kept alive. If the channel is killed or it goes out of scope, messages can no longer be received.

Even when channel is alive, why are my messages are not being received?

Make sure that your channel registers the filter before the sender sends the message. Your channel will only receive messages that are sent after the filter is successfully registered.

Use the vmsgr CLI on the device to confirm if a broadcast/unicast of interest is being sent.

In situations where a message is being sent but is not being received by the app, the vmsgr listen command allows developers to confirm if a message is being sent. Run this CLI from the root shell or the non root shell.

$ vmsgr listen broadcast://com.amazon.test1
CLI Listener Message Channel: Received: broadcast://com.amazon.test1
CLI Listener Message Channel: Received: broadcast://com.amazon.test1
^CSignal received, stopping

When the msg is being received via the CLI but the app does not receive the message it indicates a potential misconfiguration or API usage issue.

How do I verify message access controls are set up correctly?

If you do not have the required message access controls in the manifest or made an error in setting them up correctly, it will result in failures in the app at runtime. You may observe failure in the launch of the app, an error when the app tries to launch another app, or listen to system event messages (broadcasts or unicasts).

Use the following debugging tips to root cause issues in your app.

Before side loading your app run vpt validate on the development machine. Static analysis checks are built into vpt validate command that can assist developers when they are trying to migrate from the old launch configuration syntax to the new one described in this document. Address both warnings and errors. See Migration Errors for specific error strings and corrective actions. Amazon will make additional static checks available over time to better assist your app development journey and to shorten the time to market of your apps. See Use Vega Packaging Tool for Vega App Packages.
Access controls will be turned on in a future release to provide app developers the time to configure their manifests appropriately. However, you can certify that your app is compliant by turning on enforcement locally for your app. Use vmsgr enforce-security to turn on enforcement. See Test With Access Controls for details on how to detect violations from the logs. Once you detect the violations, you can use feature documentation to identify the right snippets to add to your manifest. If you are unsure why a certain error is printing you can also identify the missing module using the next tip.
The static checks described in item 1, will only ensure that the old and the new syntax are consistent. However, if you make the same mistake in both sections (e.g. you requested the wrong privilege) or when integrating a brand new functionality which did not exist previously, then the vmsgr check-access command can be used on the device as a further confirmation that message access controls are configured correctly. Developers can use this CLI in the development cycle, to detect errors in the manifest. The CLI can also be used to debug issues discovered in QA. See Verify Access Controls for details on how to use this CLI.

Migration Errors

Use the following examples to interpret the warnings/errors. This step will also ensure that there is no inconsistencies between programmatic launching of your app and when using the CLI.

Missing [[message]] section

manifest.toml:21:6 error: [offers.interaction.id] Component 'com.amazon.samplepkg.component.task' is found in [[offers.interaction]] but corresponding 'pkg://com.amazon.samplepkg.component.task' is not found in [[message]]
  help: For all components declared as interactions, add corresponding 'pkg://<componentId>' URI as a [[message]] in your manifest

Missing [[offers.message-target]] section

manifest.toml:18:16 error: [offers.interaction.launch_uris] URI 'samplepkg://main' found in [[offers.interaction]] but not in [[offers.message-target]]
  help: For all launch-uris listed as interactions in [[offers.interaction]], add corresponding [[offers.message-target]]. May also require definition of a [[message]] section if you are the owner of the URI, otherwise add a [[wants.module]] entry to the manifest to make the URI accessible to your app.

Missing URIs in [[offers.message-target]]

manifest.toml:18:16 error: [offers.interaction.launch_uris] For URI 'samplepkg://main', [[offers.interaction]] component '{"com.amazon.samplepkg.component.main"}' is different from [[offers.message-target]] component 'com.amazon.samplepkg.component.task'
  help: Use same component for a URI in [[offers.interaction]] and [[offers.message-target]]

For more information about the app manifest, see Vega App Manifest File Overview.

Test With Access Controls

The enforce-security CLI configures the system to locally turn on enforcement for a specific package. After turning on, run through various app usage scenarios to detect what breaks. Collect device logs and filter out the error string listed below and take the appropriate action described. Note that the setting is automatically cleared on reboot. Run the command again to reapply after reboot.

Usage:

vmsgr enforce-security --package <package-id>

Where package-id is a package ID of sender or receiver.

For example:

vmsgr enforce-security --package com.amazon.messaging.mr33.okidl.ac.example1

After applying the command you can detect following missing sections searching for specific log patterns.

missing [[wants.module]] section:

ERROR com.amazon.message_router.external: [...] Message is not accessible for package: 'com.amazon.messaging.mr33.okidl.ac.example1'

Your app has not requested access to the module in the manifest. Add a [[wants.module]] entry to the manifest.

missing [[wants.privilege]] section:

ERROR com.amazon.message_router.external: [...] Package: 'com.amazon.messaging.mr33.okidl.ac.example2' is missing privileges for URI: 'launch://com.amazon.messaging.mr33.okidl.ac.example2/component'

Your app has not requested this privilege in the manifest or it has not been granted the privilege by the device user. Add a [[wants.privilege]] entry in the manifest and additionally request user to grant the privilege if it is a runtime privilege. Check feature documentation for the feature that requires a runtime privilege.

missing [[offers.message-target]] section:

ERROR com.amazon.message_router.core: [...] Failed to get package and ACL info for the uri: launch://com.amazon.messaging.mr33.okidl.ac.example2/component pid: 25509, status: Unspecified run-time error

Your app is not configured to be launched in response to this URI. Add a [[offers.message-target]] entry for this URI and designate a lifecycle component to be launched in response. If unsure if the error is relevant to your app, please reach out to Amazon.

missing message definition:

ERROR com.amazon.message_router.external: [...] Message uri 'broadcast://*/com.amazon.messaging/messaging-mr33-example/subtopic' is not defined in any module inside manifest/conf

It is not expected for app developers to encounter this error. If you see it, please file a bug for Amazon to investigate.

Verify Access Controls

The check-access CLI verifies if the app passes module and privileges checks and prints an informative output on the shell. As an example if your package ID is com.amazon.messaging.mr33.okidl.ac.example1 and you are interested in receiving the URI, pkg://com.amazon.messaging.mr33.okidl.ac.example2.explicit_privileges, you can use the CLI command as follows.

Usage:

vmsgr check-access --package <package-id> <uri>

Where pkg_id is a package ID of sender or receiver and uri is the URI to test access control.

Example:

vmsgr check-access \
    --package com.amazon.messaging.mr33.okidl.ac.example1 \
    pkg://com.amazon.messaging.mr33.okidl.ac.example2.explicit_privileges

Checking access for package: com.amazon.messaging.mr33.okidl.ac.example1
Dependencies for: pkg://com.amazon.messaging.mr33.okidl.ac.example2.explicit_privileges
    Canonical Uri: pkg://com.amazon.messaging.mr33.okidl.ac.example2.explicit_privileges
    Required Module: /com.amazon.messaging.mr33.okidl.ac.example2@IAcExample2 [PASS]
    Required Sender Privilege(s): [com.amazon.security.example1]
    Sender Privilege Check: [PASS]
    Message Target Check (Not applicable to broadcast or unicast): [PASS]
    Required Receiver Privilege(s): [com.amazon.security.example2]
    Receiver Privilege Check: [FAIL]

If you are a message sender ensure that the 'Required Module' and 'Sender Privilege(s)' checks pass. If you are a broadcast/unicast message receiver ensure that the 'Required Module' and 'Receiver Privilege(s)' checks pass. If your app must be launched in response to a message URI, ensure that the 'Required Module', 'Receiver Privilege(s)' and 'Message Target' checks pass.

In this example the app has the correct [[wants.module]] but lacks the right privilege to receive the message. This can be because of a missing [[wants.privilege]]. Add it if missing. If you have the right manifest entry and have confirmed that there are no typos, then the privilege check fails if the privilege needs user consent which has not been granted yet.

Last updated: Sep 30, 2025