Skip to main content

Chat
component

Requires access to the Chat in checkout extensions scope. Request access in the Partner Dashboard.

Use the Chat component to create real-time chat applications.

Note

The Chat component can only be added to the chat targets of checkout and Thank you pages.

Anchor to chatpropsChatProps

Anchor to accessibilityLabel
accessibilityLabel
string

A label that describes the purpose or contents of the component. When set, it will be announced to users using assistive technologies and will provide them with more context.

Anchor to blockSize
blockSize
number

Adjust the block size.

Checkout imposes sizing restrictions for the component, therefore the size set may not be the actual size rendered.

number: size in pixels.

Learn more about block size on MDN.

Anchor to id
id
string

A unique identifier for the component.

Anchor to inlineSize
inlineSize
number

Adjust the inline size.

Checkout imposes sizing restrictions for the component, therefore the size set may not be the actual size rendered.

number: size in pixels.

Learn more about inline size on MDN.

Anchor to onMessage
onMessage
(event: ) => void

Callback when the embedded page sends a message.

Anchor to onReady
onReady
(event: ) => void

Callback when the embedded page is ready and a message port has been created to communicate with the host page.

Was this section helpful?

Anchor to app bridge for checkoutApp Bridge for checkout

The App Bridge script for checkout provides APIs that enables a secure communication channel between the Shopify checkout and the embedded application within the Chat iframe. It also offers convenient methods to perform common actions like resizing the iframe from within the application.

After App Bridge is set up in your app, you have access to the shopify global variable. This variable exposes the following App Bridge functionalities and configuration information:

Anchor to config
config

The static configuration values that will not change during runtime.

Anchor to extension
extension

The references and APIs to the UI extension that helped bootstrap the iframe.

Anchor to idToken
idToken
() => Promise<string>

The ID token providing a set of claims as a signed JSON Web Token (JWT) with a TTL of 5 minutes. It can be used to ensure that requests came from a Shopify authenticated user. See the ID Token documentation for more information.

Anchor to platform
platform
'browser' | 'shop-app' | 'pos'

The platform or application that the app is embedded within.

Anchor to surface
surface
"checkout"

The Shopify surface that the app is embedded within.

Anchor to visitor
visitor
() => Promise<>

Information about the current visitor.

Was this section helpful?

Basic Chat

import {
reactExtension,
Chat,
} from '@shopify/ui-extensions-react/checkout';

export default reactExtension(
'purchase.checkout.chat.render',
() => <Extension />,
);

// This component requires the configuration of the `extensions.targeting.preloads.chat` in the extensions configuration file.
// Its value will be used as the `src` attribute of the Chat component.

function Extension() {
return <Chat inlineSize={100} blockSize={50} />;
}

Preview

Anchor to src-and-query-parametersChat source and query parameters

The src of the iframe rendered by Chat is provided by the preloads chat key in the extension configuration file. Shopify automatically appends query parameters to the URL which allows developers to verify the authenticity of the request and the identity of the merchant. We guarantee these tokens are valid and signed by Shopify.

id_token

The ID token providing a set of claims as a signed JSON Web Token (JWT) with a TTL of 5 minutes. It can be used to retrieve merchants information on the backend as well as ensure that requests came from a Shopify authenticated source. See the ID Token documentation for more information.

locale

The locale of the shop that’s embedding the app, i.e. en-CA. This information is also available in the shopify global variable under config.

handle

The unique handle name of the UI extension as defined by the developer. This information is also available in the shopify global variable under extension.

Was this section helpful?

Chat source

shopify.extension.toml

[[extensions.targeting]]
target = "purchase.checkout.chat.render"

[extensions.targeting.preloads]
chat = "https://my-chat-application.com"

Anchor to chat-dimensionsChat dimensions

To provide developers with the most flexibility when it comes to responsive changes, the iframe rendered in the page by Chat takes the full width and height of the browser window. Only a specific part of the iframe is visible, the rest is clipped.

The inlineSize and blockSize values set on the Chat component or changed through the App Bridge resizeTo() method dictates the bounding box of the visible part. That box is fixed and positioned in the bottom right corner of the iframe.

Your application can rely on the window’s dimension to change styles or apply specific behaviors to different window sizes. This allow developers to style their app as if as if the application would be outside an iframe. For example, CSS media queries can now work within the iframe.

Was this section helpful?

Anchor to about-app-bridgeGetting started with App Bridge for checkout

You must add App Bridge to your hosted chat application by including the script tag pointing to the app-bridge-checkout.js as the first script in the <head> section as seen in the example. The script loads directly from Shopify and keeps itself up-to-date.

Was this section helpful?

Hosted chat application

<head>
<script src="https://cdn.shopify.com/shopifycloud/checkout-web/assets/app-bridge-checkout.js"></script>
</head>

Anchor to global-variableApp Bridge’s global variable

After App Bridge is set up in your app, you have access to the shopify global variable. This variable exposes various App Bridge functionalities, such as resizing the iframe or retrieving details of the shop.

The reference above list all the available methods and properties.

Alternatively, to explore all the functionality available on the shopify global variable:

  • Open the Chrome developer console while in checkout.
  • Switch the frame context to your app's iframe.
  • Enter shopify in the console.
Was this section helpful?

Shopify

config

shopify.config.locale;
// => 'en-CA'

Anchor to app-bridge-css-apiApp Bridge’s CSS API

Since the Chat iframe is clipped and fills the whole window as seen in the previous section, using percentage based sizes for its UI elements will most likely resolves in clipped content. As mentioned in the UX guidelines, Chat is constraint to specific maximum sizes on large and small screens set by Shopify. Setting a 100% width on an element will not be constraint to the visible size of the iframe, but to the whole window.

To remediate this issue, through App Bridge we offer a set of CSS custom properties with all the maximum dimensions defined in our UX guidelines. You can use these custom properties whether in Javascript or in the CSS of you application to set protections against overflowing content while using percentage based sizes. Using these properties will also reduce regressions if Shopify ever changes the maximum dimensions.

Was this section helpful?

App Bridge CSS API

:root {
--shopify-checkout-chat-minimized-max-inline-size: 224px;
--shopify-checkout-chat-minimized-max-block-size: 72px;
--shopify-checkout-chat-maximized-max-inline-size: 415px;
--shopify-checkout-chat-maximized-max-block-size: 700px;

@media screen and (max-width: 569px) {
--shopify-checkout-chat-maximized-max-inline-size: 100dvi;
--shopify-checkout-chat-maximized-max-block-size: 93dvb;

@supports not (inline-size: 100dvi) {
--shopify-checkout-chat-maximized-max-inline-size: 100vi;
--shopify-checkout-chat-maximized-max-block-size: 93vb;
}
}
}

Anchor to examplesExamples

Anchor to example-resize-the-chat-iframe-from-the-hosted-applicationResize the Chat iframe from the hosted application

A very common action in your application will be to request a resize of the iframe. This is done through the App Bridge resizeTo() method. The following example resizes the iframe following the click of an activator button to show a dialog window.

Anchor to example-communicate-information-between-the-hosted-application-and-the-ui-extensionCommunicate information between the hosted application and the UI extension

Information can be passed between the hosted application and the UI extension through App Bridge. Extensions API are available in the UI extension and can be shared through that method.

Was this section helpful?

Resize the Chat iframe from the hosted application

import {reactExtension, Chat} from '@shopify/ui-extensions-react/checkout';

export default reactExtension('purchase.checkout.chat.render', () => (
<Extension />
));

function Extension() {
return <Chat inlineSize={150} blockSize={50} />;
}