Live Chat

This guide is a high level overview of the Airship Live Chat feature for Android devices.


In order to use Airship Live Chat, please contact your account manager or Airship Support. They will provision your account and provide the chat URLs for the config.

Add the chat module

Live Chat requires adding the urbanairship-chat module:

dependencies {
  def airshipVersion = "16.1.0"

  implementation "$airshipVersion"

Configure the URLs

The app needs to configure the chatUrl and chatSocketUrl in the AirshipConfig options.

  chatUrl = <CHAT_URL>
  chatSocketUrl = <CHAT_SOCKET_URL>

Displaying chat

The AirshipChat module provides an activity that can be displayed by calling openChat on the Chat instance:


Optionally, you can specify the draft message and or title when opening chat:

  Chat.shared().openChat("draftMessage", "Conversation Title")
  Chat.shared().openChat("draftMessage", "Conversation Title");

Routing Conversations

To route a message to a specific agent, set the routing information before the first message is delivered on the conversation:

  Chat.shared().conversation.routing = ChatRouting(agent: "bond")
  Chat.shared().getConversation().setRouting(new ChatRouting("bond"));

A conversation can only be routed once. The routing info is sent when delivering messages.

Styling the ChatFragment

The Android resource merging feature can be used to override the chat layout styles that the SDK provides. Copy the style sheet into the application’s resource directory, then change any of the styles.

Custom UI

If the provided activity does not work for your application, you can either embed the ChatFragment directly into your application, or you can provide your own UI.

Embedding the ChatFragment

When embedding the ChatFragment, either use a FragmentContainerView or create the fragment directly. You can pass message draft argument by setting the fragment’s arguments when the view is created:

  val fragment = ChatFragment()
  fragment.arguments = bundleOf(
          ChatFragment.ARG_DRAFT to "message draft"
  ChatFragment fragment = new ChatFragment();

  Bundle bundle = new Bundle();
  bundle.putString(ChatFragment.ARG_DRAFT, "message draft");


Build your own

If the fragment is insufficient for your app, you can build your own by accessing the Conversation directly:

  val conversation = Chat.shared().conversation
  Conversation conversation = Chat.shared().getConversation();

On the conversation instance, you can access a DataSource.Factory to be used in a paging adapter:

  val dataSourceFactory = conversation.messageDataSourceFactory
  DataSource.Factory<Integer, ChatMessage> dataSourceFactory = conversation.getMessageDataSourceFactory();

Instead of paging, you can access the last 50 messages directly as a PendingResult.

  val messagesPendingResult = conversation.getMessages()
  PendingResult<List<ChatMessage>> messagesPendingResult = conversation.getMessages();

To listen when messages are updated, add a ConversationListener to be notified when the list is updated:

  conversation.addConversationListener(object : ConversationListener {
      override fun onConversationUpdated() {
          // Conversation updated
  conversation.addConversationListener(() -> {
      // Conversation updated

To send a new message, call sendMessage.

  conversation.sendMessage("Some message")
  conversation.sendMessage("Some message");

Override openChat behavior

If you provide your own UI or embed the fragment directly, you need to override the openChat behavior to navigate to your custom UI. Set the listener during takeOff.

  Chat.shared().openChatListener =  object : Chat.OnShowChatListener {
      override fun onOpenChat(message: String?): Boolean {
        // Navigate to custom chat UI
        return true
  Chat.shared().setOpenChatListener( message -> {
      // Navigate to custom UI
      return true;

Deep linking

Optionally, setup a deep link that navigates directly to chat. The deep link just needs to call through to Chat.shared().openChat().

    fun onDeepLink(deepLink: String?) {
        when (deepLink) {
            "my-app://deeplink/chat" -> shared().openChat()
            else -> {
public void onDeepLink(String deepLink) {
    switch (deepLink) {
        case "my-app://deeplink/chat":