Configuring and starting a chat

This is the developer guide for Chat SDK v1. The new Chat SDK v2 for Android is now available and is the recommended version to integrate Chat into your mobile app.

Configuring visitor data

You can update the app's visitor data at any time with the following code. Providing this data means that the visitor won't be asked for the information before starting a chat.

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

VisitorInfo visitorInfo = new VisitorInfo.Builder()
        .name("Visitor name")
        .email("[email protected]")
        .phoneNumber("0123456789")
        .build();
// set visitor info
ZopimChat.setVisitorInfo(visitorInfo);
Adding extra notes to the chat

The VisitorInfo can also be used to add notes to a chat, using the note method of its Builder:

import com.zopim.android.sdk.model.VisitorInfo;
...

VisitorInfo visitorInfo = new VisitorInfo.Builder()
        .note("Your note goes here")
        .build();

Configuring chat

If you'd like your visitors to provide certain information before starting a chat, this can be configured in 2 ways: globally for the entire Chat SDK, or at the start of a specific chat session.

Global defaults (chat initialization)

Specify global defaults for the chat configurations on app launch at the same time the account key is defined:

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

// build pre chat form config
PreChatForm defaultPreChat = new PreChatForm.Builder()
        .name(PreChatForm.Field.OPTIONAL)
        .email(PreChatForm.Field.OPTIONAL)
        .phoneNumber(PreChatForm.Field.OPTIONAL)
        .department(PreChatForm.Field.OPTIONAL)
        .message(PreChatForm.Field.OPTIONAL)
        .build();

// initialize the chat with global configuration
ZopimChat.init("Your Zopim account key")
        .preChatForm(defaultPreChat)
        .department("A department")
        .tags("tag1", "tag2")
        .build();

Pre chat form settings define whether the data is required before a chat session can be started. Any data that's not already known by the SDK will be requested before the visitor can proceed to the chat itself.

Tracking visitor events (breadcrumbs)

Visitor event tracking can help you understand where your users have been recently in your application when they start a chat and what actions they take while in a chat. You can track visitor events by placing a ZopimChat.trackEvent(String description) call in relevant sections of your application. Tracked events appear in the chat window on the agent's dashboard page.

breadcrumbs

Example

When tracking actions, consider what information will be useful to your chat agents in answering questions from users. Provide relevant information but not so much as to reach information overload. One example would be instrumenting a login screen.

DO track when:

  • A user navigates to the login screen
  • A user taps to log in
  • Login fails including a short reason/code
  • Login succeeds

DON'T track when:

  • Tapping the clear username or password field
  • Selecting a text entry field

The events you choose to log are entirely specific to the app, context, and support requirements. This is just a limited example to provide some ideas.

Enabling or disabling sending attachments

While chatting, it is possible for visitors to send attachments into the thread. This is enabled or disabled in your Zendesk Chat settings in the agent interface. For instructions, see Managing file sending options in the Zendesk Chat Help Center.

Starting a chat

A chat can be started as either an activity or a fragment.

Start as activity
import com.zopim.android.sdk.prechat.ZopimChatActivity;
...

// start chat with default config
startActivity(new Intent(context, ZopimChatActivity.class));
Start as fragment

To start a chat as a fragment, you need to provide a layout file that contains a ViewGroup with the chat_fragment_container ID.

<FrameLayout
        android:id="@+id/chat_fragment_container"
        android:layout_width="match_parent"
        android:layout_height="match_parent" />

Next, add the fragment like this:

import com.zopim.android.sdk.chatlog.ZopimChatLogFragment;
...

ZopimChatFragment fragment = new ZopimChatFragment();
FragmentManager manager = getSupportFragmentManager();
FragmentTransaction transaction = manager.beginTransaction();
transaction.replace(R.id.chat_fragment_container, fragment, ZopimChatFragment.class.getName());
transaction.commit();
Start a chat with session-specific config

To start a chat session with context-specific settings and requirements, you can provide a config when starting the new chat session. If a config is provided, it will override all global defaults for the session. As a result, you must ensure that you specify all desired requirements and data for the session.

import com.zopim.android.sdk.api.ZopimChat;
import com.zopim.android.sdk.prechat.PreChatForm;
import com.zopim.android.sdk.prechat.ZopimChatActivity;
...

// build pre chat form config
PreChatForm preChatForm = new PreChatForm.Builder()
        .name(PreChatForm.Field.REQUIRED)
        .email(PreChatForm.Field.REQUIRED)
        .phoneNumber(PreChatForm.Field.REQUIRED)
        .department(PreChatForm.Field.REQUIRED)
        .message(PreChatForm.Field.REQUIRED)
        .build();

// build session config
ZopimChat.SessionConfig config = new ZopimChat.SessionConfig()
        .preChatForm(preChatForm)
        .department("A department")
        .tags("tag1", "tag2");

// start chat activity with config
ZopimChatActivity.startActivity(context, config);

OR

// prepare and show chat fragment with config
ZopimChatFragment fragment = ZopimChatFragment.newInstance(config);

FragmentManager manager = getSupportFragmentManager();
FragmentTransaction transaction = manager.beginTransaction();
transaction.replace(R.id.chat_fragment_container, fragment, ZopimChatFragment.class.getName());
transaction.commit();

Note: If adding ZopimChatFragment to your activity then implement ChatListener interface to listen for chat events.

Session duration

A session lasts 1 hour if you configured push notifications or 5 minutes if not.

The chat session will terminate after any of the following conditions:

  • There's no activity on the chat for the duration of the session (1 hour or 5 minutes)
  • The visitor has been disconnected for the duration of the session
  • The agent ends the chat, at which point the session disconnect timeout is reset to 5 minutes
  • The visitor ends the chat, at which time the session immediately terminates