Listen for State Changes and Events

You can add listeners for state changes and events during a chat session and respond accordingly. For instance, when the client ends a session, you can display a dialog to the user.

The legacy chat product is scheduled for retirement on February 14, 2026, and is in maintenance mode until then. During this phase, you can continue to use chat, but we no longer recommend that you implement new chat channels. To avoid service interruptions to your customers, migrate to Messaging for In-App and Web before that date. Messaging offers many of the chat features that you love plus asynchronous conversations that can be picked back up at any time. Learn about chat retirement in Help.

Important

Create a SessionStateListener implementation to handle session state changes.

In Java:

1public class MySessionStateListener implements SessionStateListener {
2
3  @Override public void onSessionStateChange (ChatSessionState state) {
4    if (state == ChatSessionState.Disconnected) {
5      // TODO: Handle the disconnected state change
6    }
7  }
8
9  @Override public void onSessionEnded (ChatEndReason endReason) {
10    if (endReason == ChatEndReason.EndedByAgent) {
11      // TODO: Show a UI telling the user that the agent ended the session
12    }
13  }
14}

In Kotlin:

1class MySessionStateListener: SessionStateListener {
2
3  override fun onSessionStateChange(state: ChatSessionState?) {
4    if (state == ChatSessionState.Disconnected) {
5      // TODO: Handle the disconnected state change
6    }
7  }
8
9  override fun onSessionEnded(endReason: ChatEndReason?) {
10    if (endReason == ChatEndReason.EndedByAgent) {
11      // TODO: Show a UI telling the user that the agent ended the session
12    }
13  }
14}

This implementation handles state changes (onSessionStateChange) and why the session ended (onSessionEnded). For information on other session states and reasons for ending, see ChatSessionState and ChatEndReason.

Create a ChatEventListener implementation if you want to listen for additional events.

This listener isn’t required, but it can be used to listen for events such as: when an agent joins (agentJoined), when a message is sent (processedOutgoingMessage), when a message is received (didReceiveMessage).

In Java:

1public class MyEventListener implements ChatEventListener {
2    public void agentJoined (AgentInformation agentInformation) {
3        // Handle agent joined
4    }
5
6    public void processedOutgoingMessage (String message) {
7        // Handle outgoing message processed
8    }
9
10    public void didSelectMenuItem (ChatWindowMenu.MenuItem menuItem) {
11        // Handle chatbot menu selected
12    }
13
14    public void didSelectButtonItem (ChatWindowButtonMenu.Button buttonItem) {
15        // Handle chatbot button selected
16    }
17
18    public void didSelectFooterMenuItem (ChatFooterMenu.MenuItem footerMenuItem) {
19        // Handle chatboot footer menu selected
20    }
21
22    public void didReceiveMessage (ChatMessage chatMessage) {
23        // Handle received message
24    }
25
26    public void transferToButtonInitiated () {
27        // Handle transfer to agent
28    }
29
30    public void agentIsTyping (boolean isUserTyping) {
31        // Handle typing update
32    }
33}

In Kotlin:

1class MyEventListener : ChatEventListener {
2    override fun agentJoined(agentInformation: AgentInformation) {
3        // Handle agent joined
4    }
5
6    override fun processedOutgoingMessage(message: String) {
7        // Handle outgoing message processed
8    }
9
10    override fun didSelectMenuItem(menuItem: ChatWindowMenu.MenuItem) {
11        // Handle chatbot menu selected
12    }
13
14    override fun didSelectButtonItem(buttonItem: ChatWindowButtonMenu.Button) {
15        // Handle chatbot button selected
16    }
17
18    override fun didSelectFooterMenuItem(footerMenuItem: ChatFooterMenu.MenuItem) {
19        // Handle chatboot footer menu selected
20    }
21
22    override fun didReceiveMessage(chatMessage: ChatMessage) {
23        // Handle received message
24    }
25
26    override fun transferToButtonInitiated() {
27        // Handle transfer to agent
28    }
29
30    override fun agentIsTyping(isUserTyping: Boolean) {
31        // Handle typing update
32    }
33}

Create a SessionInfoListener implementation if you want to get session information.

In Java:

1public class MySessionInfoListener implements SessionInfoListener {
2
3    public void onSessionInfoReceived (ChatSessionInfo chatSessionInfo) {
4        // TO DO: Do something with the session ID
5        String sessionId = chatSessionInfo.getSessionId();
6}

In Kotlin:

1class MySessionInfoListener : SessionInfoListener {
2
3    override fun onSessionInfoReceived(chatSessionInfo: ChatSessionInfo) {
4        // TO DO: Do something with the session ID
5        val sessionId = chatSessionInfo.getSessionId()
6    }
7}

Instantiate your listener instances from your Application class.

In Java:

1private MySessionStateListener mSessionStateListener;
2private MyEventListener mEventListener;
3private MySessionInfoListener mSessionInfoListener;
4
5@Override public void onCreate () {
6  super.onCreate();
7  mSessionStateListener = new MySessionStateListener();
8  mEventListener = new MyEventListener();
9  mSessionInfoListener = new MySessionInfoListener();
10}
11
12public SessionStateListener getSessionStateListener () {
13  return mSessionStateListener;
14}
15
16public ChatEventListener getEventListener () {
17  return mEventListener;
18}
19
20public SessionInfoListener getSessionInfoListener () {
21  return mSessionInfoListener;
22}

In Kotlin:

1val mSessionStateListener = MySessionStateListener()
2val mEventListener = MyEventListener()
3val mSessionInfoListener = MySessionInfoListener()

It’s important to have the listener at the Application scope to ensure that the session is trackable throughout the lifetime of the application rather than just within an Activity.

Note

When you configure and start a session, add the listeners that you implemented. Add the event listener (ChatEventListener) to the chat UI configuration object. Add the session info listener (SessionInfoListener) and the session state listener (SessionStateListener) to the chat UI client.

In Java:

1// Create a UI configuration instance from a core instance 
2// and add our event listener
3ChatUIConfiguration.Builder uiConfig = new ChatUIConfiguration.Builder()
4  .chatConfiguration(chatConfiguration)
5  .chatEventListener((MyApplication)getApplication()).getEventListener());
6
7// Create a chat session and add our session listener
8ChatUI.configure(uiConfig.build())
9  .createClient(getApplicationContext())
10  .onResult(new Async.ResultHandler<ChatUIClient>() {
11      @Override public void handleResult (Async<?> operation, 
12        ChatUIClient chatUIClient) {
13
14            SessionStateListener sessionStateListener =
15                ((MyApplication)getApplication()).getSessionStateListener();
16            chatUIClient.addSessionStateListener(sessionStateListener);
17
18            SessionInfoListener sessionInfoListener =
19                ((MyApplication)getApplication()).getSessionInfoListener();
20            chatUIClient.addSessionInfoListener(sessionInfoListener);
21
22            chatUIClient.startChatSession(MainActivity.this);
23        }
24});

In Kotlin:

1// Create a UI configuration instance from a core instance
2// and add our event listener
3val uiConfig = ChatUIConfiguration.Builder()
4    .chatConfiguration(chatConfiguration)
5    .chatEventListener(mEventListener)
6
7// Create a chat session and add our session listener
8ChatUI.configure(uiConfig.build())
9    .createClient(applicationContext)
10    .onResult { operation, chatUIClient ->
11        chatUIClient.addSessionStateListener(mSessionStateListener)
12        chatUIClient.addSessionInfoListener(mSessionInfoListener)
13        chatUIClient.startChatSession(this@MainActivity)
14    }

Embedded Service Chat SDK for Android Developer Guide

Listen for State Changes and Events

See Also