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

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 a Business Chat button, you'll need to link to Business Chat's JavaScript library. The JavaScript library intelligently displays the Business Chat button, showing it only when the device supports Business Chat, otherwise the phone button is displayed. Use the following <script> tag for calling the JavaScript library:

<script src="https://static.cdn-apple.com/businesschat/start-chat-button/2.0.0/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 JavaScript 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 with the value apple-business-chat-banner-container for the banner mode layout.

  • 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 Buisness 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 message and phone 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 phone or 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 icon'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 Data Attributes.

Figure 4

Business Chat button icons mode

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

Business Chat Button 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 new data attributes. The following data attributes are supported:

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

The group to receive a chat message based on the message's intent. For example, "billing department" or "shipping".

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

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

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-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 phone and message icons. 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 between 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-phone

The phone number you want customers to call if they cannot use the chat button. If not included, the phone icon does not display.

data-apple-icon-background-color

(Icons mode only) Color of the phone 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 phone 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

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

data-apple-icon-title

(Required) (Icons mode only) Text is displayed as a tooltip when hovering over the icon.

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, Safari, Siri, and Spotlight searches.