Article

Business Chat: Adding a Business Chat Button to Your Website

Start a conversation with your customers by adding a Business Chat button to your website.

Overview

To use the Business Chat button on your website, add the JavaScript library in your site's HTML. The library links to a file that contains business logic and assets for the button. You can customize layout, colors, sizes and fonts. For more information on design guidelines, see Business Chat Entry Points Guide.

Add the JavaScript Library to the Page Headers

Wherever you intend to use a Business Chat button, you'll need to add the JavaScript library to a script tag in the page header. 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.

Use the following script tag for calling the JavaScript library:

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

Add a Container for the Business Chat Button

With the JavaScript library in place, the next step is to include a <div> tag where you want the Business Chat button to appear on your web page.

The <div> tag must include the following:

A class attribute with the value "apple-business-chat-banner-container", "apple-business-chat-phone-container", or "apple-business-chat-message-container". (See below for details of each class.)
A data-apple-business-id attribute with the business ID you received when you registered your company with Business Chat.

Banner mode

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

For example, here is the base structure of what your <div> tag for the Business Chat button should look like for the message and phone icons:

Figure 1

Business Chat banner with default colors (border added externally) oriented horizontally (first banner) and vertically (second banner).

<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>

<div
    class="apple-business-chat-banner-container"
    data-apple-business-id="ca0db090 <truncated>"
    data-apple-business-phone="+18005551212"
    data-apple-banner-cta="Style questions? We can help."
    data-apple-banner-context="Tap to chat with out styling expert now."
    data-apple-banner-orientation="vertical"
></div>

Figure 2

Business Chat banner with default colors oriented vertically, scaled to 2, and context only messaging.

<div
    class="apple-business-chat-banner-container"
    data-apple-business-id="ca0db090 <truncated>"
    data-apple-business-phone="+18005551212"
    data-apple-banner-context="Chat with one of our pros to get your offer for iPhone Xs."
    data-apple-banner-scale="2"
    data-apple-banner-orientation="vertical"
></div>

Figure 3

Business Chat banner using intent, group IDs and body, 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-business-body="Order an additional credit card."
    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 4

Business Chat banner with the same style as the one in Figure 3, but scaled to 1.3 its original size.

<div
    class="apple-business-chat-banner-container"
    data-apple-business-id="ca0db090 <truncated>"
    data-apple-business-phone="+18005551212"
    data-apple-business-intent-id="Design-Advice"
    data-apple-business-group-id="Design questions"
    data-apple-business-body="Order an additional credit card."
    data-apple-banner-cta="Design questions? We can help."
    data-apple-banner-context="Chat with one of our experts to get design ideas!"
    data-apple-banner-scale="1.3"
    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>

Icons mode

In this mode, the button can appear as a Phone or a Message icon depending on which class name value we add. To display a Phone icon, class "apple-business-chat-phone-container" should be added and data-apple-business-phone attribute should be set:

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

In this case, data-apple-business-id is not required since the icon's sole function is to start a call.

To display a Message icon, class "apple-business-chat-message-container" should be added, as well as the data-apple-icon-title attribute:

<div class="apple-business-chat-message-container" data-apple-business-id="ca0db090" data-apple-icon-title="Title text"></div>

Figure 5

Business Chat Message and Phone icons with no additional formatting.

Figure 6

Business Chat Message scaled to 1.7, with customized colors.

<div
    class="apple-business-chat-message-container"
    data-apple-business-id="ca0db090 <truncated>"
    data-apple-icon-color="rgba(0, 210, 143, 0.3)"
    data-apple-icon-background-color="rgb(192, 192, 192)"
    data-apple-icon-scale="1.5"
    data-apple-icon-title="Design questions? We can help."
></div>

Handling unsupported devices

Business Chat is supported on macOS (from version 10.13.4) and iOS (from version 11.3) devices, which means that the Message icon (in either Banner or Icon modes) will be shown only on supported devices.

In Banner mode, if the data-apple-business-phone attribute is not populated, the entire banner will be hidden on unsupported devices.

`isSupported` function

To allow for further customization, Business Chat JS library exports a function that can be used to check if Business Chat is supported.

window.appleBusinessChat.isSupported()

Figure 7

Alert functionality that uses the isSupported function of the Business Chat JS library.


<script>
    function checkIfBusinessChatIsSupported() {
        if(!window.appleBusinessChat.isSupported()) {
            alert("Business Chat is not supported");
        } else {
            alert("Business Chat is supported");
        }
    }
</script>
<a onclick="checkIfBusinessChatIsSupported()">
    Click here to check if Business Chat is supported
</a>

Click here to check if Business Chat is supported

Fallback child element

Another way to handle unsupported devices is to add a child div with a class name "apple-business-chat-fallback-container" inside the "apple-business-chat-banner-container" element. Custom content inside the fallback container will be shown if Business Chat is not supported.

Figure 8

Show "Business Chat is not supported" on 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>

Single Page Application (SPA) support

The script that creates BC Banners/Icons runs only once, on page load. This means that if you dynamically generate content which should be transformed into BC Banners/Icons, the transformation would not happen automatically.

For cases like the one mentioned (usually the case in SPAs), Business Chat JS library exports a function that can be used to initialize BC components manually:

window.appleBusinessChat.refresh()

Figure 9

Manually initialize a BC Banner using refresh function of the Business Chat JS library.

<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>

<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>

Click here to create a placeholder for the Banner

Click here to initialize the Banner

Data attributes

Configuration for the button passes through as data-* attributes for the <div> tag. The following data attributes are supported:

data-apple-banner-background-color: The banner’s background color. You can use red, green, blue (RGB) or RGB-alpha (RGBA) parameters, 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. (Optional)
data-apple-banner-cta: Call-to-Action (CTA) text for the icons. This is required if you don’t provide context.
data-apple-banner-context: Lets customers know what they can expect when tapping the icon. This is required if you don’t provide a CTA.
data-apple-banner-rounded-corners: A boolean value that allows you to have rounded or square corners (value: false). If not set then the banner defaults to true, or rounded corners. (Optional)
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. (Optional)
data-apple-banner-icon-background-color: Color of the phone and message icon's circular background. You can use RGB or RGBA parameters, 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. (Optional)
data-apple-banner-icon-color: Color of the phone and message icons. You can use RGB or RGBA parameters, 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. (Optional)
data-apple-banner-orientation: Identifies the orientation of the container. You can choose either horizontal or vertical. The default is horizontal. (Optional)
data-apple-banner-scale: A string value that allows you to scale the contents of the banner. The values are between 1 through 2 for scaling, the icons are between 45-90px, and the font is 10 through 20pt. (Optional)
data-apple-banner-text-color: Color of the context and CTA text on the banner. You can use RGB or RGBA parameters, or a hex color code to set the color. If no color is specified, then the color defaults to rgb(0, 0, 0). (Optional)
data-apple-business-id: 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". (Required)
data-apple-business-phone: The phone number you want customers to call if they cannot use the chat button. If not included, then the phone icon does not display. (Optional)
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". (Optional)
data-apple-business-group-id: The group to receive chat messages based on the message's intent. For example, "billing department" or "shipping". (Optional)
data-apple-business-body: A 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.". (Optional)
data-apple-icon-color: [Icons mode only] Color of the phone or message icons. You can use RGB or RGBA parameters, 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. (Optional)
data-apple-icon-background-color: [Icons mode only] Color of the phone and message icon's circular background. You can use RGB or RGBA parameters, 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. (Optional)
data-apple-icon-scale: [Icons mode only] Decimal value, 1 through 2, in the range that determines the scale of the icons. The default scale value is 1. (Optional)
data-apple-icon-title: [Icons mode only] Text displayed as a tooltip on the icon. (Optional)