Article

Adding a Business Chat Button to Your Website

Let customers start a conversation with you by adding a Business Chat button to your website.

Overview

You can display the Business Chat buttons on your webpage by adding a script tag with the JavaScript (JS) library link and a <div> container to your HTML page. The JS library links to a downloadable file that contains business logic and assets. You can design your website by matching the Business Chat buttons, banners, and text with your company's logo colors and font. You can also place the icons, context, and call to action (CTA) horizontally or vertically in your design. For more information and design guidelines, see Business Chat Human Interface Guidelines.

Figure 1

Business Chat button and container as shown on a webpage

Website depicting the Business Chat button residing in a button container with context and CTA, displayed in Safari.

Add the JavaScript Library to the Page Headers

On the webpages where you intend to include Business Chat buttons, you'll need to link to Business Chat's JS library. The JS library intelligently displays the Business Chat button, showing it only when the device supports Business Chat, otherwise the Call button is displayed. Use the following <script> tag for calling the JS library:

<script src="https://static.cdn-apple.com/businesschat/start-chat-button/2/index.js"></script>

You can place the <script> tag in one of two places:

  • Within the <head>...</head> element of the page.

  • Following the </body> element at the end of the page.

The script automatically triggers when the webpage loads into the browser. It finds all button containers on the page and converts them into Business Chat buttons with the configuration you specify within the <div> tag, as described in the next section.

Add a Container for the Business Chat Button

With the JS library and assets in place, the next step is to use the <div> tag where you want to include a Business Chat button banner with the context and CTA on the webpage. You can use multiple <div> tags to add more than one Business Chat button on the page. The <div> tag must include the following:

  • A class attribute to specify the type of container: banner, phone, or message. For more information, see Business Chat Button Class and Data Attributes.

  • A data-apple-business-id attribute with the business ID you received when you registered your company with Business Chat.

For example, here is the base structure of what your <div> tag for the Business Chat button in a banner should look like:

<div class="apple-business-chat-banner-container" data-apple-business-id="insert your business id here"></div>

Add the Buttons in a Banner

In addition to the attribute and class, the banner mode button layout also requires that a data-apple-banner-cta attribute with a CTA or a data-apple-banner-context attribute message to engage customers (or both) be present on the <div> container.

For example, here is the base structure of what your <div> container for the Business Chat button should look like for banner mode in default horizontal alignment (see Figure 2) with the Message and Call buttons:

<div
    class="apple-business-chat-banner-container"
    data-apple-business-id="ca0db090 <truncated>"
    data-apple-business-phone="+18005551212"
    data-apple-banner-cta="Questions? We can help."
    data-apple-banner-context="Chat with one of our pros to get your offer for iPhone Xs."
    data-apple-banner-rounded-corners="false"
></div>

You can choose to center your context, CTA, and buttons in a vertical style by setting the data-apple-banner-orientation="vertical" attribute as shown in Figure 2.

Figure 2

Banner mode with context and CTA centered horizontally (left) and vertically (right)

A Business Chat button in banner mode with context, CTA, and message and phone buttons centered horizontally (left); and vertically (right).

You can also set the Business Chat banner with intent and group IDs. Below is an example of intent and group IDs with CTA and context messaging, scaled to 1, oriented vertically, with customized colors.

<div
    class="apple-business-chat-banner-container"
    data-apple-business-id="ca0db090 <truncated>"
    data-apple-business-phone="+18005551212"
    data-apple-business-intent-id="Financial"
    data-apple-business-group-id="Investment-Advisor"
    data-apple-banner-cta="Got questions?"
    data-apple-banner-context="Chat with a financial advisor now."
    data-apple-banner-scale="1"
    data-apple-banner-background-color="rgb(27, 63, 104)"
    data-apple-banner-text-color="rgb(255, 255, 255)"
    data-apple-banner-icon-background-color="rgb(255, 255, 255)"
    data-apple-banner-icon-color="rgba(0, 210, 143, 0.3)"
    data-apple-banner-orientation="vertical"
></div>

Figure 3 shows the custom Business Chat banner. Although the intent and group IDs are set in the <div> container, the customer doesn't see them when hovering over or tapping the buttons.

Figure 3

Customized Business Chat banner

Screenshot of a banner displaying different colors for phone and message buttons, with CTA and context.

Add a Button to Your Webpage

Icons mode gives you the ability to display only a Call or the Message button on your webpage. You can display the phone button by adding the class apple-business-chat-phone-container and setting the data-apple-business-phone attribute:

<div class="apple-business-chat-phone-container" data-apple-business-phone="+123221223"></div>

You don't need to add the data-apple-business-id for the phone because the button's sole function is to start a call with the vendor.

To display only the Message button, add the class apple-business-chat-message-container and set the data-apple-icon-title attribute:

<div
    class="apple-business-chat-message-container"
    data-apple-business-id="ca0db090 <truncated>"
    data-apple-icon-color="#1B3F68"
    data-apple-icon-background-color="#1B3F68"
    data-apple-icon-scale="1.7"
    data-apple-icon-title="Style questions? We can help."
></div>

Figure 4 shows the output of an icons mode Message button for a website footer. The message container, background, and icon button are centered horizontally (default) with CTA and context. When setting the message container for icons mode, you can only use icons mode attributes. For more information, see Business Chat Button Class and Data Attributes.

Figure 4

Business Chat button icons mode

A screenshot of the icons mode footer for a Business Chat message button.

Add Support for Unsupported Devices

Apple devices running iOS 11.3 and later or macOS 10.13.4 and later support Business Chat. For devices that don't fall into the supported category, you can use the isSupported function and the fallback child element to detect unsupported devices and display custom messages.

The Message button appears only on supported devices in either banner or icons mode. If you're using banner mode and the data-apple-business-phone attribute is not populated, the entire banner is hidden on unsupported devices.

Add the isSupported Function

To allow for further customization, the Business Chat JS library exports the window.appleBusinessChat.isSupported() function to verify Business Chat's support of a device.

You can use the isSupported function to integrate an alert into your script:

<script>
    function checkIfBusinessChatIsSupported() {
        if(!window.appleBusinessChat.isSupported()) {
            alert("Business Chat is not supported");
        } else {
            alert("Business Chat is supported");
        }
    }
</script>

<!-- The following is used for testing. -->
<a onclick="checkIfBusinessChatIsSupported()">
    Click here to check if Business Chat is supported
</a>

Add a Fallback Child Element

If you know you'll have customers using unsupported devices, add a child <div> container in the banner container with the class name apple-business-chat-fallback-container. You can show custom content inside the fallback container for unsupported devices:

<div
    class="apple-business-chat-banner-container"
    data-apple-business-id="ca0db090 <truncated>"
    data-apple-banner-cta="Questions? We can help."
    data-apple-banner-context="Chat with one of our pros to get your offer for iPhone Xs."
>
    <div class="apple-business-chat-fallback-container">
        <b>Business Chat<b> is not supported
    </div>
</div>

Add Support for Single Page Application

The script that creates Business Chat banners and icons runs once on page load. If you dynamically generate content that transforms into Business Chat banners and icons, the transformation doesn't happen automatically.

To support Single Page Application, initialize the components manually by exporting the window.appleBusinessChat.refresh() function from the JS library into a script:

<script>
    function dynamicallyCreateABannerPlaceholder() {
        var refreshPlaceholder = document.getElementById("refreshPlaceholder");
        refreshPlaceholder.classList.add("apple-business-chat-banner-container");
        refreshPlaceholder.setAttribute("data-apple-business-id", "ca0db090 <truncated>");
        refreshPlaceholder.setAttribute("data-apple-banner-cta", "Questions? We can help.");
        refreshPlaceholder.innerHTML = "Placeholder created.";
    }
</script>

<!-- The following is used for testing. -->
<a onclick="dynamicallyCreateABannerPlaceholder()">
    Click here to create a placeholder for the Banner
</a>

<div id="refreshPlaceholder"></div>

<a onclick="window.appleBusinessChat.refresh()">
    Click here to initialize the Banner
</a>

Business Chat Button Class and Data Attributes

Configuration for the button passes through as data-* attributes for the <div> tag. Although this JS library is backward compatible with the legacy button, you cannot use the legacy JS library with the *-banner-* and *-icon-* data attributes. The following classes and data attributes are supported:

apple-business-chat-banner-container

A class that supports the banner container to display both the Message and Call buttons.

apple-business-chat-fallback-container

A child class placed inside the apple-business-chat-banner-container that provides custom content for an unsupported device.

apple-business-chat-message-container

A class that supports the message container to display only the Message button.

apple-business-chat-phone-container

A class that supports the phone container to display only the Call button.

data-apple-banner-background-color

The banner’s background color. You can use red, green, blue (RGB), RGB-alpha (RGBA), or a hexadecimal color code to set the color. The default value in RGB is rgb(255, 255, 255), and the hex color code is #FFFFFF.

data-apple-banner-context

A short sentence that lets customers know what they can expect when tapping the button. This is required if you don’t provide a CTA.

data-apple-banner-corners

A Boolean value that allows you to have rounded or square corners. If not set, the banner defaults to true, or rounded corners.

data-apple-banner-cta

CTA text for the icons. This is required if you don’t provide context.

data-apple-banner-font-family

A string value allowing you to choose the font of the context and CTA text. All standard OS fonts are supported.

data-apple-banner-icon-background-color

Color of the phone and message icon's circular background. You can use RGB, RGBA, or a hex color code to set the color. The default value in RGB is rgb(239, 239, 244), and the hex color code value is #EFEFF4.

data-apple-banner-icon-color

Color of the Call and Message buttons. You can use RGB, RGBA, or a hex color code to set the color. The default value in RGB is rgb(0, 122, 255), and the hex color code value is #007AFF.

data-apple-banner-orientation

Sets the orientation of the container. You can choose either horizontal or vertical. The default is horizontal.

data-apple-banner-scale

A string value that allows you to scale the contents of the banner. The values are from 1 through 2 for scaling, the icons are between 45 and 90 pixels, and the font is 10 through 20 point.

data-apple-banner-text-color

Color of the context and CTA text on the banner. You can use RGB, RGBA, or a hex color code to set the color. If no color is specified, then the color defaults to rgb(255, 255, 255).

data-apple-business-body

A data attribute parameter that prepopulates a message for your customers so all they need to do is tap Send in Messages. For example, "Order an additional credit card."

data-apple-business-group-id

A data attribute to identify the group that receives a chat message based on the message's intent. For example, "billing department" or "shipping."

data-apple-business-id

(Required) Identifies and routes messages to the owner of the Business Chat ID. Insert your Business Chat ID between the quotes. For example, "insert your business id here".

data-apple-business-intent-id

The intent for initiating the chat conversation. This can be anything that you specify; for example, "account statement" or "track order".

data-apple-business-phone

The phone number you want customers to call if they cannot use the chat button. If the phone number isn't included, the Call icon isn't displayed.

data-apple-icon-background-color

(Icons mode only) Color of the Call or Message buttons. You can use RGB, RGBA, or a hex color code to set the color. The default value in RGB is rgb(0, 122, 255), and the hex color code value is #007AFF.

data-apple-icon-color

(Icons mode only) Color of the Call or Message buttons. You can use RGB, RGBA, or a hex color code to set the color. If no value is specified, the default value in RGB is rgb(0, 122, 255), and the hex value is #007AFF.

data-apple-icon-scale

(Icons mode only) (Required) A decimal value from 1 through 2 that determines the scale of the icons. The default scale value is 1.

data-apple-icon-title

(Icons mode only) (Required) Text displayed as a tooltip when either a pointer or customer's finger hovers over the button.

See Also

Chat with Customers

Starting a Chat from your App

Let customers start a conversation with you from your app.

Starting a Chat from a URL

Let customers start a conversation with you from your website or email message.

Business and Place Cards

Allow customers to contact your business from Maps, Siri, and Spotlight searches.