shopify.sidekick.launch({message}). But the button must be conditional: call isEnabled() first, launch only after a merchant click, and distinguish a rejected prompt from a request that may already have been sent.On this page
Why a Sidekick button appears broken
The Sidekick Launch API is part of App Bridge in the web Shopify admin, not a universal browser or mobile API. It may be unavailable on the current store, disabled by the merchant, or blocked by prompt screening. Shopify announced the API on October 28, 2026. The old pattern of linking merchants to help content is not equivalent to sending a contextual prompt into Sidekick.
Implement a guarded launch
Load the supported App Bridge script in your embedded admin app. Hide the entry point until an availability check resolves. Use a specific, merchant-readable prompt that refers to the current report or setup step, without embedding sensitive data or URLs.
const button = document.querySelector('#ask-sidekick');
button.hidden = true;
const enabled = await shopify.sidekick?.isEnabled().catch(() => false);
if (enabled) {
button.hidden = false;
button.addEventListener('click', async () => {
button.disabled = true;
try {
await shopify.sidekick.launch({
message: 'Explain the inventory discrepancies shown in this report.'
});
} catch (error) {
const message = String(error?.message || error);
if (message.startsWith('sidekick.launch:')) {
shopify.toast.show(message, {isError: true});
} else {
shopify.toast.show('Could not confirm Sidekick started.', {isError: true});
}
} finally {
button.disabled = false;
}
});
}
What to avoid
The API accepts a nonempty prompt of at most 5,500 characters; it does not accept hidden context, arbitrary instructions or conversation IDs. Shopify screens prompts and can reject URLs, cross-app actions, sensitive data extraction, risky store changes, or attempts to manipulate Sidekick. The launched conversation uses only your app’s Sidekick extension tools. Do not fire launches on page load or on a timer. For errors without the sidekick.launch: prefix, the conversation might already exist; automatic retry can duplicate it.
How to test this
- Open the embedded app in the desktop Shopify admin on a store with Sidekick enabled. Confirm the button appears only after
isEnabled()returns true. - Test a store without Sidekick and the Shopify mobile app. The entry point should remain hidden, not throw a render error.
- Click once and verify the prompt appears in Sidekick; confirm no duplicate conversations on slow networks.
- Test a rejected prompt and an API failure. Show a useful error, keep the page functional, and avoid blind automatic retries.

