Customization

The following sections describe how to change the look and feel of the components.

Phone styles example

Add the following XML chat_style.xml file to your values directory. Note that ZopimChatTheme.Light is a light theme that extends Theme.AppCompat.Light. We also supply ZopimChatTheme.Dark if your app uses a dark theme. Feel free to explore the sample project provided.

<resources>
...
    <!-- Base chat sdk theme. -->
    <style name="ZopimChatTheme" parent="ZopimChatTheme.Light">
        <!-- Customize chat theme here. -->
        <item name="colorAccent">@color/sample_red</item>
        <item name="colorPrimary">@color/sample_red</item>
        <item name="colorPrimaryDark">@color/sample_dark_red</item>
    </style>

    <style name="no_agents_button">
        <item name="android:background">@color/sample_red</item>
        <item name="android:padding">8dp</item>
        <item name="android:textColor">@android:color/white</item>
    </style>

    <!--Customize toolbar that replaces action bar-->
    <style name="zopim_toolbar">
        <item name="android:background">?attr/colorPrimary</item>
        <item name="android:minHeight">?attr/actionBarSize</item>
        <item name="android:theme">@style/ThemeOverlay.AppCompat.Dark.ActionBar</item>
        <item name="popupTheme">@style/ThemeOverlay.AppCompat.Light</item>
    </style>

    <!--Customize where chat widget appears-->
    <style name="chat_widget" parent="_chat_widget">
        <item name="anchor">bottom_left</item>
    </style>

    <!--Customize chat colors-->
    <color name="chat_bubble_visitor">@color/sample_red</color>
...
</resources>

Example

image

To apply your project's application theme to the chat UI simply override 'ZopimChatTheme' style like in this example.

<resources>

    <!-- Base application theme. -->
    <style name="AppTheme" parent="Theme.AppCompat.Light">
        <!-- Customize your theme here. -->
    </style>

     <style name="ZopimChatTheme" parent="AppTheme">
         <!--Chat UI uses the toolbar so no need to show ActionBar-->
         <item name="windowActionBar">false</item>
         <!-- Customize chat theme here. -->
         <item name="colorAccent">@color/sample_red</item>
         <item name="colorPrimary">@color/sample_red</item>
         <item name="colorPrimaryDark">@color/sample_dark_red</item>
     </style>

</resources>

Tablet styles example

Add the following XML chat_style.xml file to your values-sw720dp directory. Note that ZopimChatTheme.Light.Dialog is a light theme with that extends Theme.AppCompat.Light.Dialog. We also supply ZopimChatTheme.Dark.Dialog if your app uses a dark theme. Feel free to explore the sample project provided.

<resources>
...
    <!-- Base application theme. -->
    <style name="ZopimChatTheme" parent="ZopimChatTheme.Light.Dialog">
        <!-- Customize chat theme here. -->
        <item name="colorAccent">@color/sample_red</item>
        <item name="colorPrimary">@color/sample_red</item>
        <item name="colorPrimaryDark">@color/sample_dark_red</item>
    </style>
...
</resources>

Example

image

Pre chat form

<resources>
...
    <!-- dimensions -->
    <dimen name="chat_default_text_padding">8dp</dimen>
    <dimen name="pre_chat_form_container_padding">16dp</dimen>
    <dimen name="pre_chat_form_list_item_padding">12dp</dimen>
    <dimen name="pre_chat_form_padding">@dimen/chat_default_text_padding</dimen>
    <dimen name="pre_chat_form_item_margin">8dp</dimen>
...
</resources>

Example

image

Chat log

<resources>
...
    <!-- styles -->
    <style name="chat_row_event_message">
        // style this view
    </style>

    <style name="chat_member_event">
        // style this view
    </style>

    <style name="pre_chat_form_selected_item">
        // style this view
    </style>

    <style name="chat_bubble_visitor">
        // style this view
    </style>

    <style name="chat_bubble_agent">
        // style this view
    </style>

    <style name="chat_bubble_agent_name">
        // style this view
    </style>

    <style name="chat_input_field">
        // style this view
    </style>

    <!-- colors -->
    <color name="chat_bubble_agent">@android:color/white</color>
    <color name="chat_bubble_visitor">@android:color/darker_gray</color>

    <!-- dimensions -->
    <dimen name="chat_log_padding">16dp</dimen>
    <dimen name="agent_avatar_max_size">40dp</dimen>
    <dimen name="agent_avatar_margin_right">16dp</dimen>
    <dimen name="chat_bubble_min_height">4dp</dimen>
    <dimen name="chat_bubble_min_width">4dp</dimen>
    <dimen name="chat_bubble_radius">10dp</dimen>
    <dimen name="chat_bubble_padding">10dp</dimen>
    <dimen name="chat_bubble_vertical_margin">8dp</dimen>
    <dimen name="chat_row_vertical_margin">20dp</dimen>
    <dimen name="chat_bubble_visitor_margin_left">112dp</dimen>
    <dimen name="chat_bubble_agent_margin_right">56dp</dimen>
    <dimen name="typing_indicator_diameter">8dp</dimen>
    <dimen name="typing_indicator_spacing">2dp</dimen>
    <dimen name="chat_input_container_padding_bottom">5dp</dimen>
    <dimen name="lead_message_padding_top">16dp</dimen>
    <dimen name="chat_message_padding_top">0dp</dimen>
...
</resources>

Example

image

Chat widget

<resources>
...
    <!-- styles -->
    <style name="chat_widget">
        // style this view
    </style>

    <style name="chat_widget_background">
        // style this view
    </style>

    <style name="chat_widget_unread_notification">
        // style this view
    </style>

    <!-- dimensions -->
    <dimen name="widget_vertical_margin">16dp</dimen>
    <dimen name="widget_horizontal_margin">16dp</dimen>
    <dimen name="widget_width">50dp</dimen>
    <dimen name="widget_height">50dp</dimen>

    <!-- colors -->
    <color name="typing_indicator_primary">#40FFFFFF</color>
    <color name="typing_indicator_secondary">#0DFFFFFF</color>
...
</resources>

Example

image

Using the chat widget on Android 6 (Marshmallow, API Level 23)

Since the release of Android 6, special permission is required to use SYSTEM_ALERT_WINDOW. Because this is used by the Chat SDK, the default behavior is for the chat widget not to show.

Visitors will still be able to return to an active chat without the chat widget, using the navigation you put in place in your app, but they will not see notification of any agent replies.

To display the chat widget in your app in Android 6:

  • Use Settings.canDrawOverlays() to check whether your app has permission to draw overlays. For more information, see the canDrawOverlays() method in the Android developer docs.
  • If your app does not have permission, request it by creating an Intent with an action of Settings.ACTION_MANAGE_OVERLAY_PERMISSION, and optionally add a URI of package:<package name>, as per the Android developer documentation. Be aware that this will open a settings page, rather than the usual runtime permission check.
Disabling chat widget

The chat widget can be disabled by either calling ChatWidgetService.disable(); or removing the SYSTEM_ALERT_WINDOW permission by specifying the following into your AndroidManifest.xml:

<uses-permission tools:node="remove" android:name="android.permission.SYSTEM_ALERT_WINDOW"/>

Email Transcript

image

You can disable the Email Transcript action with the following chat configuration:

import com.zopim.android.sdk.api.ZopimChat;
...

ZopimChat.init("your account key")
    .emailTranscript(EmailTranscript.DISABLE);

No agents available

<resources>
...
    <!-- styles -->
    <style name="no_agents_button">
        // style this view
    </style>

    <!-- colors -->
...
</resources>

Example

image

No connection toast slide view

<resources>
...
    <!-- styles -->
    <style name="no_connection_error_view_title">
        // style this view
    </style>

    <style name="no_connection_error_view_text">
        // style this view
    </style>

    <style name="no_connection_view_container">
        // style this view
    </style>
    <style name="no_connection_view_separator">
        // style this view
    </style>

    <style name="no_connection_view_text">
        // style this view
    </style>

     <!-- colors -->
     <color name="no_connection_view_container_background_color">#434343</color>
     <color name="no_connection_view_separator_color">@android:color/black</color>
     <color name="no_connection_view_text_color">@android:color/white</color>

     <!-- dimensions -->
     <dimen name="no_connection_error_view_asset_padding">12dp</dimen>
     <dimen name="no_connection_error_view_padding">6dp</dimen>
     <dimen name="no_connection_view_separator_height">2px</dimen>
     <dimen name="no_connection_view_padding">16dp</dimen>
...
<resources>

Example

image

Menu items

Add the following XML chat_log_menu.xml, offline_message_menu.xml, pre_chat_menu.xml files to your menu directory to customize the ActionBar menu items.

Chat log menu

<?xml version="1.0" encoding="utf-8"?>
<menu xmlns:android="http://schemas.android.com/apk/res/android"
      xmlns:app="http://schemas.android.com/apk/res-auto"
      xmlns:tools="http://schemas.android.com/tools"
      tools:context=".ui.ZopimChatLogFragment">

    <item
        android:id="@+id/end_chat"
        android:orderInCategory="100"
        android:title="@string/chat_menu_end_button"
        app:showAsAction="always"/>

</menu>

Offline message menu

<?xml version="1.0" encoding="utf-8"?>
<menu xmlns:android="http://schemas.android.com/apk/res/android"
      xmlns:app="http://schemas.android.com/apk/res-auto"
      xmlns:tools="http://schemas.android.com/tools"
      tools:context=".ui.ZopimOfflineMessageFragment">
    <item
        android:id="@+id/send"
        android:title="@string/offline_menu_send_button"
        app:showAsAction="always"/>
</menu>

Pre chat form menu

<?xml version="1.0" encoding="utf-8"?>
<menu xmlns:android="http://schemas.android.com/apk/res/android"
      xmlns:app="http://schemas.android.com/apk/res-auto"
      xmlns:tools="http://schemas.android.com/tools"
      tools:context=".ui.ZopimPreChatFragment">
    <item
        android:id="@+id/start_chat"
        android:title="@string/pre_chat_menu_next_button"
        app:showAsAction="always"/>
</menu>

Animations

<resources>
...
    <!--Animation : typing indicator-->
    <integer name="typing_dot_duration">300</integer>
    <!--Animation : widget cross-fade-->
    <integer name="crossfade_duration">300</integer>
...
</resources>

Customizing strings and localization

To change the default strings in your application, add replacements for the following strings. Make sure to include placeholders in the replacements of any strings that contain them.

Note that some system messages sent by Zendesk Chat are not controlled by the SDK, and so cannot be edited. Any string not documented on this page cannot be edited.

The Pre Chat Form component contains the following strings:

<resources>
    ...
    <string name="pre_chat_email_hint">Email address</string>
    <string name="pre_chat_email_error_message">Email is required</string>
    <string name="pre_chat_email_error_hint">Please enter an email address</string>
    <string name="pre_chat_name_hint">Name</string>
    <string name="pre_chat_name_error_message">Name is required</string>
    <string name="pre_chat_name_error_hint">Please enter your name</string>
    <string name="pre_chat_phone_hint">Phone number</string>
    <string name="pre_chat_phone_error_message">Phone number is required</string>
    <string name="pre_chat_phone_error_hint">Please enter your phone number</string>
    <string name="pre_chat_departments_hint">Select a department</string>
    <string name="pre_chat_departments_error_message">Department is required</string>
    <string name="pre_chat_departments_error_hint">Please select a department</string>
    <string name="pre_chat_message_hint">Message</string>
    <string name="pre_chat_message_error_message">Message is required</string>
    <string name="pre_chat_message_error_hint">Please enter a message</string>
    <string name="pre_chat_menu_next_button">Next</string>
    <string name="pre_chat_validation_error_message">Please correct above errors</string>
    <string name="required_field_template">%1$s *</string>
    ...
</resources>

The Chat Log contains the following strings:

<resources>
    ...
    <string name="input_field_hint">Message</string>
    <string name="chat_agent_left_message">%1$s left the chat</string>
    <string name="chat_agent_joined_message">%1$s joined the chat</string>
    <string name="chat_menu_end_button">End chat</string>
    <string name="chat_ended_message">Chat ended</string>
    <string name="chat_session_timeout_message">We\'ve not heard from you for a while so this chat session has been closed. Please start a new chat if you still have questions.</string>
    <string name="chat_visitor_queue_message">Please wait while our agents attend to you. There are currently %1$s visitor(s) waiting to be served.</string>

    <!--Chat fragment-->
    <string name="chat_loading_message">Starting chat...</string>

    <!--Email transcript dialog-->
    <string name="email_transcript_title">Email a transcript?</string>
    <string name="email_transcript_message">Send a transcript of this chat to your email address</string>
    <string name="email_transcript_email_message">Please enter your email address</string>
    <string name="email_transcript_email_hint">"email@address.com"</string>
    <string name="email_transcript_confirm_button">Send</string>
    <string name="email_transcript_cancel_button">Don\'t send</string>

    <!--Chat end confirm dialog-->
    <string name="chat_end_dialog_title">End this chat?</string>
    <string name="chat_end_dialog_message">Your chat session will be closed</string>
    <string name="chat_end_dialog_confirm_button">End</string>
    <string name="chat_end_dialog_cancel_button">Cancel</string>

    <!--Reconnection timeout dialog-->
    <string name="reconnect_timeout_title">Connection lost</string>
    <string name="reconnect_timeout_message">We have been unable to reconnect. Do you wish to continue trying?</string>
    <string name="reconnect_timeout_confirm_button">Yes</string>
    <string name="reconnect_timeout_cancel_button">No</string>
    ...
</resources>

The No Agents Available contains the following strings:

<resources>
    ...
    <string name="no_agents_title">No agents available</string>
    <string name="no_agents_message">Sorry there are no agents available to chat. Please try again later or leave us a message.</string>
    <string name="offline_message_button">Leave a message</string>
    ...
</resources>

The No Connection Slide Toast contains the following strings:

<resources>
    ...
    <string name="no_connectivity_toast_message">No connection</string>
    <string name="reconnecting_toast_message">Reconnecting...</string>
    ...
</resources>

The Offline Message contains the following strings:

<resources>
    ...
    <string name="offline_menu_send_button">Send</string>
    <string name="offline_validation_error_message">Please correct the above errors</string>
    <string name="offline_sent_confirmation_message">Your message has been sent</string>
    <string name="offline_email_hint">Email</string>
    <string name="offline_email_error_message">Email is required</string>
    <string name="offline_email_error_hint">Please enter email</string>
    <string name="offline_name_hint">Name</string>
    <string name="offline_name_error_message">Name is required</string>
    <string name="offline_name_error_hint">Please enter name</string>
    <string name="offline_message_hint">Message</string>
    <string name="offline_message_error_message">Message is required</string>
    <string name="offline_message_error_hint">Please enter message</string>
    <string name="offline_message_send_failed">Unable to send message</string>
    <string name="offline_message_retry_button">Retry</string>
    <string name="offline_message_cancel_button">Cancel</string>
    ...
</resources>

The Chat Push contains the following strings:

<resources>
    ...
    <string name="chat_push_chat_ended_body">Your chat with %1$s has ended</string>
    <string name="chat_push_chat_ended_title">Chat ended</string>
    ...
</resources>

To learn more about resource handling and strings in Android, see https://developer.android.com/guide/topics/resources/string-resource.html.

To learn more about localization in Android, see https://developer.android.com/guide/topics/resources/localization.html.

You can't find what you wish to customize?

In case a style, color, dimension or string you're looking to customize is not listed in the examples above you can still find all of the current values defined with Android Studio. Values are described under build > intermediates > exploded-aar > com.zopim.android > sdk > 1.4.3 > res > values > values.xml

image