Every WhatsApp chat button setting in the Shopify theme editor

Position, offsets, size, label, colours, new tab and the hide on product or cart switches: what each app embed setting does and which ones live in the app instead.

The WhatsApp button has two homes. Who answers, when they answer and what the panel says live in the app. Where the button sits, how big it is, what colour it is and which pages it skips live in your theme, as settings on an app embed. The split is deliberate: the theme owns the look of the storefront, so the look of the button is edited where the rest of the storefront is edited. This post walks the embed's settings in the order they appear, with the defaults, the ranges and the reason you would change each one. It assumes Beacon Messenger is installed; the setup guide covers getting there.

Where the settings are

Online Store, Themes, Customize on the theme you want, then the App embeds icon in the left sidebar. The embed is called Beacon Messenger WhatsApp chat. The toggle next to it turns the button on for this theme; the settings appear when you expand the row. Save in the top right applies them. The Chat page in the app has an Open theme editor button that lands you in the same place.

One consequence of the embed living in the theme is worth stating early: the settings belong to that theme. If you publish a different theme, or a duplicate you have been working on, the embed on the new theme starts off and with defaults. Turn it on again and copy your settings across before you publish, or the button quietly disappears on launch day.

Position and the two distances

Position is Bottom right or Bottom left, default right. Distance from bottom and Distance from side are each 0 to 200 pixels, default 20. The bottom distance has a note in the editor that says it plainly: move the button up if it overlaps another widget. The widget it most often overlaps is a cookie consent banner that sits along the bottom edge, followed by a back-to-top arrow, a reviews badge or a second chat tool left over from an earlier app.

  • **Cookie banner along the bottom.** Set Distance from bottom to the banner's height plus a little, often 80 to 120, so the button clears it while the banner is visible. The space looks generous once the banner is accepted, which most merchants accept as the price of not covering the consent buttons.
  • **Back-to-top arrow or reviews badge in the same corner.** Move to the other corner with Position. Two round buttons stacked in one corner look like a mistake even when they do not overlap.
  • **Mobile safe areas.** On phones with a gesture bar, 20 pixels can feel tight. 24 to 32 clears the bar on most devices without pushing the button into the content.

The values are pixels, not percentages, and they apply on every screen size. Preview on the mobile view in the theme editor before saving; the desktop preview hides most overlap problems.

Size

Small, Medium or Large, default Medium. Small suits stores whose theme already has a busy footer and an icon-only button. Large is for stores where WhatsApp is the main support channel and the button is meant to be seen from across the room. Size scales the icon and the label together, so a Large button with a long label is wide; shorten the label or drop it on mobile if that happens.

Button label and Show label on mobile

Button label defaults to Chat with us. The editor note says what the empty state does: leave it empty for an icon-only button. The label is the text next to the WhatsApp icon on the closed button, not the panel heading; the panel title and greeting are set in the app, so a label of Ask us anything and a panel title of Customer care are both possible and both common.

Show label on mobile is off by default, which means phones get the icon only even when desktops get the label. Turn it on if the label carries meaning, for example WhatsApp in a market where shoppers look for that word specifically, or Habla con nosotros on a Spanish storefront where the icon alone reads as generic chat. Leave it off on stores with a sticky add-to-cart bar on product pages, where the horizontal room is spoken for.

Button colour and Button text colour

Defaults are WhatsApp green, #25D366, and white text. Keeping the green is the safe choice because shoppers recognise it as WhatsApp before they read anything. Changing it to match your brand is fine for the closed button, but keep enough contrast with the text colour that the label stays readable; the editor does not check this for you. The panel that opens when the button is pressed uses the app's own styling and is not affected by these two fields.

Open WhatsApp in a new tab

On by default. When a shopper picks an agent, the WhatsApp link opens in a new tab on desktop, so your store stays open behind the conversation. On a phone the link hands off to the WhatsApp app regardless of this setting. Turn it off only if your theme or an analytics setup has trouble with new tabs; the difference for shoppers is small, and keeping the store open is usually what you want.

Hide on product pages and Hide on cart and checkout

Both off by default. Hide on product pages removes the button from every product template; Hide on cart and checkout removes it from the cart page. Checkout is included in the label for completeness: app embeds do not run on Shopify's checkout, so the button is never there, and the switch controls the cart template. The check happens in the theme before anything is rendered, so a hidden page does not load the button and then remove it; it simply does not include it.

Why hide it at all? Product pages often have a sticky buy bar and a size guide that already compete for the corner. Cart pages have a checkout button that nothing should distract from. The counter-argument is that a product page is exactly where a pre-purchase question happens, so most stores leave the product switch off and consider the cart one. Try the cart switch for a fortnight and compare abandoned checkout counts; it is a cheap experiment.

What the embed tells the app about the page

The embed passes the page title, the page URL and the shop name into the panel. On a product page the title is the product's name rather than the browser tab text. That is what fills the {page_title} and {page_url} placeholders in an agent's prefilled message, so a message set to Hi, I have a question about {page_title} arrives on the agent's phone as Hi, I have a question about Linen Shirt, with the link under it. The placeholders are set in the app; the embed only supplies the values.

Why the preview shows a grey placeholder

In the theme editor, if the embed is on but the app has no agents or the button is switched off in the app, a grey box appears in the button's position reading Add an agent and turn the button on in the Beacon Messenger app to show it here. Shoppers never see it; it exists so you can position an empty slot before the first agent is added. The business hours and agents post covers the app side. Once at least one agent exists and Show button is on, the real button replaces the placeholder in the preview.

A note on Canvas themes

Themes carrying Shopify's Canvas badge do not support app blocks or embeds yet. The embed will not appear in their App embeds list. Use a theme without the badge, or a copy made with Duplicate rather than Duplicate in Canvas, and the embed shows up as described.

A settings recipe that works for most stores

  1. Position Bottom right, Distance from bottom 24, Distance from side 20, unless a cookie banner lives there; then bottom 96 until you have checked the mobile preview with the banner showing.
  2. Size Medium, label Chat with us or the equivalent in your storefront language, Show label on mobile off.
  3. Colours left at the defaults. Brand colours on the button are a decision to make after you have seen the green one convert for a month.
  4. Open in a new tab on. Hide on product pages off. Hide on cart on if your cart page already feels crowded, off otherwise.
  5. Save, then open the storefront on a phone, scroll a product page to the bottom and open the cart. If the button covers anything you need to tap, come back and raise Distance from bottom.

That is the whole list. None of it needs code, all of it is reversible with Save, and because it lives in the theme it is also what remains when the app is removed, which is why the post on a chat widget that is still showing after uninstall starts with the App embeds panel too.

Frequently asked questions

I changed the button colour but the chat panel is still green. Why?

Button colour and Button text colour apply to the closed button in the corner. The panel that opens uses the app's own styling and is not themed from these settings.

The button is covering my cookie banner's Accept button on phones. What do I change?

Raise Distance from bottom in the embed settings until the button clears the banner, typically 80 to 120 pixels, and check the mobile preview with the banner visible. Moving the button to the other corner with Position is the alternative when the banner is a small box rather than a full-width bar.

Does Hide on cart and checkout really hide the button at checkout?

The button is never at checkout, because app embeds do not run there. The switch hides it on the cart page. The label mentions checkout so nobody wonders whether a separate setting is needed.

I published a new theme and the button vanished. Did the app break?

No. Embed settings, including the on and off toggle, belong to the theme they were set on. Open the new theme in the editor, turn the Beacon Messenger WhatsApp chat embed on under App embeds and reapply your settings.

More guides