Handle Custom URLs in Chat

Have your agents pass along custom URLs to perform specific actions in your mobile app.

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

When an agent sends a standard link to a user in your app, a preview tile appears that the user can tap to view in a browser. However, you can come up with your own URL scheme that displays a custom tile and performs a custom action within your app.

  1. Create a custom URL scheme and expression.

    Create a URL scheme using the AppEventList class. This class allows you to add URLs either for specific paths (such as action/settings) or using regular expressions (such as action\\/a.*). Patterns are matched in the order that you add them to the AppEventList object. Be sure to add items starting with the most specific and ending with the most generic.

    // Create an app event list
    // TO DO: Replace "servicesdk" with your own unique scheme
    AppEventList appEventList = new AppEventList("servicesdk"); 
            
    // Add a regular expression for a path
    appEventList.addDescriptionForPath("action/settings", "Tap for regex action");
    
    // Add a custom path for a specific path
    appEventList.addDescriptionForExpression("action\\/a.*", "Tap for path action");
  2. Implement the AppLinkClickListener so that you can handle when the user taps on the URL.

    In order to minimize or maximize the chat window, you need access to the ChatUIClient that you used when creating the chat UI.

    Note

    public static class ChatAppLinkClickListener implements AppLinkClickListener {
    
      private final Activity mActivity;
      private final ChatUIClient mUIClient;
    
      // Constructor requires the chat UI client and the activity
      public ChatAppLinkClickListener(ChatUIClient uiClient, Activity activity) {
        mActivity = activity;
        mUIClient = uiClient;
      }
    
      @Override
      public void didReceiveAppEventWithURL(@NonNull String url) {
    
        if (url.contains("settings")) {
    
          // Minimize chat window
          mUIClient.minimize();
    
          // TO DO: Perform some action for this url. For example:
          Intent intent = new Intent(mActivity, ChatSettingsActivity.class);
          mActivity.startActivity(intent);
        }
        if (url.contains("alert")) {
    
          // TO DO: Perform some action for this url. For example:
          Toast.makeText(
            mActivity.getApplicationContext(),
            "An example of an alert",
            Toast.LENGTH_SHORT)
          .show();
        }
    
        // NOTE: You can maximize the chat window using
        //       mUIClient.maximize();
    
      }
    }
  3. Configure the chat SDK using the ChatUIConfiguration builder. Add the AppEventList object and the AppLinkClickListener.
    new ChatUIConfiguration.Builder()
      // … other ChatUIConfiguration details
      .chatUIConfigurationBuilder.appEventList(appEventList)
      .appLinkClickListener(new ChatAppLinkClickListener(context))