Skip to main content
Shopify themes are rendered on Shopify’s servers with Liquid, so you can add the chat widget and sign customer variables without running a backend of your own. This guide adds two theme snippets: a small HS256 JWT signer and the Typewise widget embed that uses it.
You need your client ID and workspace ID from Behavior → Channels → Chat → Installation, and the signing key from Identity verification. Add your store’s domain to the Domain allowlist on the same page.

How it works

  • Shopify exposes the logged-in shopper as the customer object in Liquid. For guests it is empty.
  • Liquid has a built-in hmac_sha256 filter, so the JWT is built and signed on Shopify’s servers. The browser only ever sees the finished token.
  • The signing key lives in a theme setting, never in the page source.
  • Guests get the widget without signedVariables. Logged-in customers get a token with userId and user_email. You can sign any other customer value the same way.
Shopify stores the key in the theme’s config/settings_data.json. Staff with Edit code access and installed apps with theme read access can read it, and theme duplicates and exports carry it too. Anyone who holds the key can forge verified variables for any customer. Review which apps can read your themes, and regenerate the key in Typewise whenever staff access changes, a theme-reading app is removed, or a theme file is shared.

Add the theme setting

Open Online Store → Themes → ⋯ → Edit code, then Config → settings_schema.json. Add this group at the end of the array, after the last existing group. Do not replace the file; it holds all of your theme’s other settings.
Once saved, a new Typewise group appears in the theme editor with two fields: Typewise secret key and Typewise debug logging. The widget does not sign anything until the key is filled in.
1

Open the theme editor

Go to Online Store → Themes → Customize, then click the gear icon at the bottom of the left sidebar to open Theme settings.
2

Enter the secret key

Open the Typewise group and paste the sk_... key from Identity verification into Typewise secret key.
3

Save

Click Save at the top right. Leave Typewise debug logging off for now; you turn it on later to verify the setup.
Typewise group in Shopify theme settings Theme settings are per theme. If you publish a different theme, repeat this setup there. A duplicated or exported theme already contains the key, so treat those copies as holding the secret.

Add the JWT signer snippet

Under Snippets, choose Add a new snippet, name it jwt-hs256, and paste the following. It takes a JSON payload string and a secret, and outputs a signed token. The loop converts the hex output of hmac_sha256 into the base64url form a JWT needs.
snippets/jwt-hs256.liquid

Add the widget snippet

Add a second snippet named typewise-widget. Replace YOUR_CLIENT_ID and YOUR_WORKSPACE_ID with your values.
snippets/typewise-widget.liquid
The token expires 7 days after the page was rendered. Shopify’s page cache can serve a page rendered a few minutes earlier, which is well inside that window.
user_email is pre-configured in Context Variables. To sign more values, add them to tw_payload in the snippet, for example customer.first_name or customer.tags, and declare the same variable name in Context Variables. Anything signed this way is a verified variable and can be used as a secure input on actions and lookups. Variables that are not declared are dropped on arrival.

Render it in the theme layout

Open Layout → theme.liquid and add one line just before </body>:
layout/theme.liquid
Save, then open the storefront. The chat bubble appears for every visitor. Log in as a customer through the store’s account page to test the signed path. Being logged into the Shopify admin does not create a storefront customer session.
Checkout and the order status page are not rendered by your theme, so the widget does not appear there. That requires a Shopify app with a theme app extension.

Verify the setup

Turn on Typewise debug logging in theme settings and add the block below to the end of typewise-widget. It prints one JSON object to the browser console under [typewise-debug] with presence checks and masked values only. It never prints the key, the email, the names or the token.
A working setup for a logged-in customer logs overall_ok: true. What to check when it does not: Turn debug logging off once you are done.

Troubleshooting

  • The chat shows “An error occurred” on the first message. The page sent signedVariables: null. The widget snippet above omits the key when there is no token; make sure you did not change that branch.
  • The widget loads but variables are untrusted. The key in theme settings does not match the current key in Typewise, or the token has expired. Copy the key again from Identity verification.
  • Nothing renders. Check that your store’s domain is on the Domain allowlist and that the render line sits inside <body>.

See also