Simple WhatsApp Button

Setup guide

A floating WhatsApp button for your storefront. Two steps to get it live, then every setting explained.

Both steps are required. Saving a number without turning the app embed on shows nothing, and turning the embed on without a saved number also shows nothing. The button appears once both are done.

Getting the button live

  1. Save your WhatsApp number

    Open the app from your Shopify admin, go to the Settings page and enter the number you want to receive messages at. Use the country code, area code and number, with no leading zero and no symbols: for example 5511999999999.

    Write your greeting in Initial message if you want the conversation to start with text already typed, then press Save settings.

  2. Turn the app embed on in your theme

    The button stays hidden until your theme allows it. In your Shopify admin go to Online Store → Themes → Customize, open the App embeds panel in the left sidebar, switch on WhatsApp Button, and save the theme.

    The app's home page has an Open theme editor button, in the Turn it on in your theme step, that opens the theme editor on that panel directly.

Open your storefront and the button is there. Everything below is optional.

Every setting

Grouped by what they control. The first group is on the app's Settings page, the next two are on the Appearance page, and the last is on the Visibility page. Each page has its own Save button and saves only its own fields.

Who the button talks to

Link the button todefault: number
Whether the button opens your number or your WhatsApp username. Your number stays saved either way, so you can switch back at any time.
WhatsApp numberrequired
10 to 15 digits, starting with the country code and no leading zero. This is required even when the button links to a username, because it is what the button falls back to if the username is not working.
WhatsApp usernameoptional
3 to 35 characters: letters, numbers, dots or underscores, with at least one letter. The name also has to be active in WhatsApp, not merely reserved — WhatsApp is releasing usernames country by country, so test the link before you publish.
Initial messageoptional
Text that is already typed when the chat opens, up to 500 characters. Leaving it empty is a valid choice: the chat then opens blank.

How it looks

Button colordefault: #25D366
The circle's color, as a six-digit hex value. The default is WhatsApp's own green.
Icon colordefault: #FFFFFF
The color of the WhatsApp glyph inside the circle.
Button sizedefault: 64px
The diameter, between 32 and 96 pixels. Always pixels, so the button is the same size on every theme.
Icon sizedefault: 70%
How much of the button the glyph fills, between 30% and 80%. Being a percentage, it scales with the button rather than needing its own adjustment.
Animationdefault: none
None, Pulse or Bounce. Visitors who ask their device for reduced motion never see the movement, whichever you pick.
Drop shadowdefault: on
A soft shadow behind the button, which lifts it off the page.

Where it sits

Positiondefault: bottom right
One of four corners or sides: bottom right, bottom left, middle right or middle left.
Distance from the sidedefault: 20px
The gap to the left or right edge, whichever side the position uses. 0 to 200 pixels.
Distance from the bottomdefault: 20px
The gap to the bottom edge, 0 to 200 pixels. Shown only for the two bottom positions.
Vertical adjustmentdefault: 0
Moves the button off the centre line: a positive number raises it, a negative one lowers it. Shown only for the two middle positions.
Stacking order (z-index)default: 100
Which element wins when something overlaps the button. Raise it if a sticky header, a cart drawer or another app covers the button.

Which pages show it

Show the button ondefault: every page
The page types the button appears on, named as in the theme editor: home page, products, collections, collections list, gift card, cart, customer accounts, pages, blogs, blog posts, search, password and the 404 page. Untick one to hide the button there. Customer accounts covers classic accounts only; the button never shows on new customer accounts or at checkout.

Restore defaults, on the Appearance page, only resets that page. Your number, username, link mode and message are left alone, and nothing is stored until you press Save.

If something looks wrong

The button does not appear on my store

Either the app embed is off, no number has been saved, or that page type is unticked on the Visibility page. Both steps at the top of this page are required, and none of the three shows an error on the storefront: the button is simply not rendered.

The button is hidden behind my header or cart

Raise Stacking order (z-index). Sticky headers often sit at 1000 or higher, so try a value above that.

The button overlaps a cookie bar or another widget

Use Distance from the side and Distance from the bottom to move it clear, or switch to a position on the other side of the screen.

The username link does not open a chat

A reserved username is not necessarily an active one. WhatsApp is enabling usernames country by country, so yours may not work yet. Switch Link the button to back to the number — it is still saved — and try the username again later.

I changed a setting and the storefront looks the same

Check that you pressed Save settings on the page where you made the change, then reload the storefront. The live preview beside the form always reflects what is on screen, which is not necessarily what is saved yet.

Privacy and uninstalling

The app collects nothing about your shoppers: no cookies, no analytics, no tracking. The button is plain HTML and CSS, and it loads no JavaScript on your storefront. Your settings live in your own Shopify store, and uninstalling removes the button and the settings with it, leaving no leftover code in your theme. The full privacy policy has the detail.

Still stuck?

Write to [email protected] and we will help. New features are listed on the changelog.