---
title: Use extensions to surface app actions
description: Use extensions to surface app actions
source_url:
  html: 'https://shopify.dev/docs/apps/build/sidekick/build-app-actions'
  md: 'https://shopify.dev/docs/apps/build/sidekick/build-app-actions.md'
---

# Use extensions to surface app actions

**Developer preview:**

We're selecting developer partners to get limited early access and provide feedback on Sidekick app extensions. [Submit your interest](https://docs.google.com/forms/d/e/1FAIpQLScxM8VQao5GGlIF-8TeiYQp-ucQiTFwSai35oDBzDuIpN5O7g/viewform?usp=dialog) and we'll reach out if you're selected.

By declaring and defining your app's actions in an app extension, Sidekick can take the merchant to the right page in your app to perform a rich action.

***

## Example: Edit email content

In this example, a merchant can ask Sidekick to edit the content of an email campaign. Sidekick takes the merchant to the [Shopify Messaging](https://apps.shopify.com/shopify-email) app, navigated to the correct email campaign.

![Sidekick with email app](https://shopify.dev/assets/assets/admin/sidekick/sidekick-messaging-BmyWcPHr.png)

***

## Expose actions to Sidekick

Use app extensions to expose actions in your app. By providing your app's actions in an app extension, Sidekick can take the merchant to the right page in your app to perform a rich action.

Multiple app extension types are supported. Choose the right app extension type for your app.

| Extension type | Embedded app support | Non-embedded app support |
| - | - | - |
| Admin link | ✅ | ❌ |
| UI extension | ✅ | ✅ |

***

## Requirements

* [Create an app](https://shopify.dev/docs/apps/build/scaffold-app).
* For app home, use the latest version of [App Bridge](https://shopify.dev/docs/api/app-home).
* Add an [`extensions_summary`](https://shopify.dev/docs/apps/build/sidekick#add-an-extensions-summary-to-your-app) to your `shopify.app.toml`. This is required for all apps with Sidekick-eligible extensions.

**Coming soon:**

Support for intents without tools (pure navigation) is not yet available. Currently, Sidekick only supports invoking activities that have activity tools. Navigation-only intents will be supported in the near future.

**Limits:**

You can register a maximum of 5 intents and 20 tools for each app. The tool limit is shared across all extension types (data and action).

***

## Example: Allow Sidekick to edit email content

Use an **app extension** to allow Sidekick to edit content in your app.

The example below shows how to create an app extension using an [admin link](https://shopify.dev/docs/apps/build/admin/admin-links).

### Create an app extension

Use `shopify-cli` to create an [admin link](https://shopify.dev/docs/apps/build/admin/admin-links) extension.

## Terminal

```terminal
shopify app generate extension --template admin_intent_link --name open-email
```

The command creates a new extension template in your app's `extensions` directory with the following structure:

## Edit extension folder structure

```toml
extensions/open-email
  ├── email-schema.json // Schema definition for the intent's input parameters
  ├── instructions.md // Guidelines for Sidekick on tool usage
  ├── README.md
  ├── shopify.extension.toml // The config file for the extension
  └── tools.json // Tool definitions for Sidekick actions
```

Modify `shopify.extension.toml` to include the `name`, `handle`, and `type` of your app extension.

## extensions/open-email/shopify.extension.toml

```toml
[[extensions]]
name = "Open email"
description = "Edit an email campaign"
handle = "open-email"
type = "admin_link"


[[extensions.targeting]]
target = "admin.app.intent.link"
url = "/edit/{id}"
tools = "./tools.json"
instructions = "./instructions.md"
```

**Note:**

`admin.app.intent.link` is a special target that is not tied to a Shopify resource that can be invoked from anywhere in the Shopify Admin.

The `description` field helps Sidekick understand when your extension is relevant. Be specific about what your extension does — a vague description means Sidekick won't reliably invoke your extension when merchants need it. See [Writing effective extension descriptions](https://shopify.dev/docs/apps/build/sidekick#writing-effective-extension-descriptions) for detailed guidance and examples.

### Register your extension as an intent

Add an `intents` configuration to your `shopify.extension.toml` with an `action`, `type` and `schema`.

`application/email` is used as an example `type` for this guide. App extensions support several app types for various popular use cases.

## extensions/open-email/shopify.extension.toml

```toml
[[extension.targeting.intents]]
type = "application/email"
action = "edit"
schema = "./email-schema.json"
```

**Coming soon:**

A full list of supported types for app intents will be available soon.

### Declare the extension schema

Declare your schema in the `JSON` file referenced in `shopify.extension.toml`.

**Note:**

`inputSchema` is required and must reference a schema matching the `type` defined in `shopify.extension.toml`. For example, `application/email` should reference <https://extensions.shopifycdn.com/shopifycloud/schemas/v1/application/email.json>

## ./email-schema.json

```json
{
  "$schema": "https://extensions.shopifycdn.com/shopifycloud/schemas/v1/intent.json",
  "inputSchema": {
    "$ref": "https://extensions.shopifycdn.com/shopifycloud/schemas/v1/application/email.json",
    "type": "object",
    "properties": {
      "recipient": {
        "type": "string",
        "description": "Primary recipient email address (e.g., email@example.com)",
        "format": "email"
      },
      "cc": {
        "type": "array",
        "description": "CC recipient email addresses",
        "items": {"type": "string", "format": "email"}
      },
      "subject": {
        "type": "string",
        "description": "Email subject line (1-200 characters)",
        "minLength": 1,
        "maxLength": 200
      },
      "body": {
        "type": "string",
        "description": "Email message body (supports rich text formatting)"
      },
      "template_id": {
        "type": "string",
        "description": "Email template to use",
        "enum": ["blank", "welcome", "promotion"]
      },
      "send_at": {
        "type": "string",
        "description": "Schedule email for future delivery (ISO 8601 date-time format)",
        "format": "date-time"
      },
      "priority": {
        "type": "string",
        "description": "Email priority level",
        "enum": ["low", "normal", "high"],
        "default": "normal"
      },
      "track_opens": {
        "type": "boolean",
        "description": "Enable email open tracking",
        "default": true
      }
    },
    "required": ["recipient", "subject", "body"]
  }
}
```

### Write your tools schema

Declare your tools in a `JSON` file referenced by the `tools` field in `shopify.extension.toml`. Tools define the actions Sidekick can perform while the intent is open. These should be specific to the intent context — for example, a `design_email` tool that updates the visual design of the email campaign the merchant is currently editing.

## ./tools.json

```json
[
  {
    "$schema": "https://extensions.shopifycdn.com/shopifycloud/schemas/v1/tool.json",
    "name": "design_email",
    "description": "Update the visual design of the currently open email campaign, including background color, layout, and styling",
    "inputSchema": {
      "type": "object",
      "properties": {
        "background_color": {
          "type": "string",
          "description": "Background color for the email body (hex code, e.g. #FFFFFF)"
        },
        "layout": {
          "type": "string",
          "description": "Email layout template",
          "enum": ["single-column", "two-column", "hero-image"]
        },
        "font_family": {
          "type": "string",
          "description": "Primary font family for email text"
        }
      }
    }
  }
]
```

**Limits:**

Each tool `name` can be up to 64 characters. Each tool `description` can be up to 512 characters. You can register a maximum of 20 tools for each app, shared across all extensions (data and action).

### Write instructions for using the app extension

Define instructions for how Sidekick should use your app extension in an `instructions.md` file.

**Note:**

`instructions.md` is optional, but is highly recommended for providing context and guidance to Sidekick about your app extension.

## ./instructions.md

```md
## When to Use the Design Email Tool


Use the `design_email` tool when the merchant asks to:
- Change the background color or layout of the email they're editing
- Update the visual styling or font of the current campaign
- Switch to a different email layout template


## Important Guidelines


- Only use `design_email` while the merchant has an email campaign open
- When updating the design, confirm changes with the merchant before applying
- Refer to layouts as "single-column", "two-column", or "hero-image"
```

**Limits:**

The `description` field has a 256-token limit. The `instructions.md` file has a 2,048-token limit.

***

## Putting it all together

After following this tutorial, your `extensions` folder structure should look like this:

## Folder structure

```toml
extensions/open-email
  ├── email-schema.json // Schema definition for the intent's input parameters
  ├── instructions.md // Guidelines for Sidekick on tool usage
  ├── README.md
  ├── shopify.extension.toml // The config file for the extension
  └── tools.json // Tool definitions for Sidekick actions
```

***