integrations:mobile-chat-android

Mobile chat for Android

With embeddable chat for Android, your clients can contact support directly from your app and get help. Your support specialists will process tickets in Pyrus even when the user communicates with you from a messenger app.

You can use the default chat setup or customize it for your app. You can also receive files and subscribe users to push notifications about new messages.

This guide will help developers embed Pyrus chat into their app.

Get an App ID

First, connect your app to the Pyrus form where support team processes clients’ requests. To get started, you need an administrator account in Pyrus with access to the form settings. If you aren’t a form administrator, ask a colleague who has this access.

1. Go to the service ticket form configuration page and find Integrations. Click Set Up next to Mobile App Chat.

2. Сopy App ID from the Credentials section.

Prepare the project

Add to the build.gradle file:

repositories {
   jcenter()
}

dependencies {
   ...
   implementation 'com.pyrus:servicedesk:1.1.2'
}

To let users attach files to messages, grant access to the camera and gallery.

"android.permission.WRITE_EXTERNAL_STORAGE"
"android.permission.CAMERA"

Initialize the library

When starting the app, invoke the init() method of the PyrusServiceDesk class.

The parameters of the init() method:

  • application — an Application class object used by your app.
  • appId — your application ID in Pyrus. It’s stored in the settings of the connected form in Pyrus. If you aren’t a form administrator, ask a colleague who has this access to copy the AppID as described in the Get an App ID section.

public class SampleApp extends Application {
   @Override
   public void onCreate() {
       super.onCreate();
       PyrusServiceDesk.init(
               application: this,
               appId: "your_app_id"
       );
   }
}

Launch chat UI

To launch the user interface, invoke the start() method of the PyrusServiceDesk class.

The start(activity) method launches the default user interface:

  • activity is an Activity class object. It’s used to run the user interface.

To configure the chat appearance, use the start(activity,configuration) method:

  • activity is an Activity class object. It’s used to run the user interface.
  • configuration is an ServiceDeskConfiguration class object. It’s used for setting up the chat appearance.

public class SampleActivity extends Activity{
   @Override
   protected void onCreate(Bundle savedInstanceState) {
	...
       findViewById(R.id.support).setOnClickListener(
               view -> PyrusServiceDesk.start(
				/* activity */this,
				/* configuration */
                      serviceDeskConfigurationInstance
       );
   }
}

Customize the chat

To launch the interface, use the start(activity, configuration) method. To create and configure the ServiceDeskConfiguration object, use the object of the ServiceDeskConfiguration.Builder class.

The methods of the ServiceDeskConfiguration.Builder object:

  • setUserName(name) is the username that a support specialist sees in a Pyrus ticket. If a user is logged into the app, you can pass his or her name, email, and other info to this method. It will help your support specialist understand who he or she is talking to and resolve the ticket more quickly.
  • setChatTitle(title) is the title of the chat window.
  • setWelcomeMessage(message) is the welcome message that the user sees in the chat.
  • setThemeColor(color) sets the color of the main elements of the chat interface.
  • setAvatarForSupport(drawableResID) sets an icon to use as a support specialist’s avatar. drawableResID is an ID of the resource of the avatar picture.
  • build() creates a ServiceDeskConfiguration class object.

new ServiceDeskConfiguration.Builder()
.setUserName("Ivan Petrov")
       .setChatTitle("Support CompanyName")
       .setWelcomeMessage("Hello! How can I help you?")
       .setThemeColor(Color.RED)
       .setAvatarForSupport(R.drawable.logo)
       .build())

Notifications about new messages

You can use push notifications to notify the user about new messages in the chat. This is the alternative option. It’s easier to implement, but notifications will be delayed and you won’t see a new message’s content. Enable push notifications

To receive notifications about new messages from a support specialist, implement the NewReplySubscriber interface and pass the implementation to the subscribeToReplies() of the PyrusServiceDesk class.

public class SampleActivity extends Activity implements NewReplySubscriber {
   @Override
   protected void onCreate(Bundle savedInstanceState) {
	  ...
       PyrusServiceDesk.subscribeToReplies(this);
	  ...
    }
@Override
protected void onDestroy() {
   ...
   PyrusServiceDesk.unsubscribeFromReplies(this);
   ...
}
   @Override
   public void onNewReply() {
       textView.setText("New unread messages");
   }
}

Enabling push notifications

You can use push notifications to inform the user about new messages in the chat. Here’s how it works:

When launching, your app communicates with Google’s push notification server to get its device token, which you then forward to your provider server. Your server includes that token with any notifications it sends.

To subscribe a user to notifications about new messages, register a push token by invoking setPushToken(token, callback) of the PyrusServiceDesk class.

The parameters of the setPushToken(token, callback) method:

  • token is a token that is registered in Pyrus. It sends notifications about new messages.
  • callback is an implementation of the SetPushTokenCallback interface. Its onResult() method will be evoked when the token registration is completed. It isn’t guaranteed that the onResult() method will be invoked in the same stream with setPushToken(token, callback).

SetPushTokenCallback contains the onResult(@Nullable Exception exception) method. Its exception parameter will be null if the registration is successful, otherwise it will return an error message.

Example:

public class SampleApp extends Application {

   @Override
   public void onCreate() {
       super.onCreate();
       PyrusServiceDesk.init(
               this,
               "my_app_id"
       );

       PyrusServiceDesk.setPushToken(
               "my_push_token",
               exception -> {
                   Log.d("SAMPLE_APP", exception.getMessage());
               });

   }
}

On the application server side, you should implement a webhook to receive notifications about new messages in the app chat. Add the webhook URL in the form settings in Pyrus.

When there is a new message from the support team, a POST request will be sent to the webhook URL. It contains:

ticket_id — the number of the task that the comment is added to.

token — a user's identifier, including:

  • user_id — user ID, which is passed with each request
  • app_id — mobile application/web chat identifier
  • device_id — device identifier
  • type — device type: “Android”

comment — information about the new comment:

  • comment_id — number of the new comment
  • body — comment text
  • is_inbound — always false, shows that the comment is from the support team

author — information about the author of the comment:

  • name — author's name
  • avatar_id — author's avatar identifier
  • avatar_color — the color of the author's avatar. Used if avatar_id is not specified.

created_at — the date and time when the comment was created.

attachments — description of the attached files:

  • id — file identificator
  • name — file name
  • size — file size in bytes

Setting up the chat menu

For an enhanced support experience, your users can send files without leaving the chat flow. Users can attach photos taken with the device camera or select images from gallery by default. To add support for other types of files, like configuration files, use the registerFileChooser() method of the PyrusServeDesk class.

PyrusServiceDesk.registerFileChooser(chooser), where chooser is an implementation of the FileChooser interface. To stop using the configured FileChooser, pass null to the method.

FileChooser methods:

  • getLabel() is the name of the corresponding menu option.
  • getIntent() returns an object of the Intent type, which is used to start the activity. The custom activity that will be invoked with Intent must return the result containing the URI to access the file. You can URI to the result using the intent.setData(uri) method.

Note: the scheme of the URI should be “content”. Otherwise the comment with the attached file won’t be sent.

public class SampleApp extends Application {
   @Override
   public void onCreate() {
       ...      
       PyrusServiceDesk.registerFileChooser(new FileChooser() {
           @NonNull
           @Override
           public String getLabel() {
               return "Send logs";
           }
           @NonNull
           @Override
           public Intent getIntent() {
               return new Intent(SampleApp.this, LogChooser.class);
           }
       });
   }
}

Types and methods description

PyrusServiceDesk

This is the main class for working with embeddable chat.

init

public static void init(@NonNull Application application, @NonNull String appId)

Initializes the embeddable Pyrus Service Desk module. You should invoke this method in [Application.onCreate].

Note: do it before other public methods are invoked, or else IllegalStateException will occur.

Parameters

appId App identificator in Pyrus.
application The app where the chat is embedded.

registerFileChooser

public static void registerFileChooser(@Nullable FileChooser fileChooser)

Specifies the source that will be added to the menu. The user can attach files to messages. The max size of the attached files should be up to [RequestUtils.MAX_FILE_SIZE_MEGABYTES]. Now it is 250 MB.

Parameters

fileChooser Starts the interface for selecting files. To disable it, pass null to the method.

setPushToken

public static void setPushToken(@NonNull String token, @NonNull SetPushTokenCallback callback)

Registers your push token. The callback [callback] can be invoked in a stream that is different from the stream where the [setPushToken] was invoked.

Parameters

callback A callback that is invoked when the token has been registered. If the token is successfully registered, the callback is made without error.
token The token to be registered.

start

public static void start(@NonNull Activity activity)

Starts the default PyrusServiceDesk interface.

Parameters

activity Starts the customized PyrusServiceDesk interface.

start

 public static void start(@NonNull Activity activity, @NonNull ServiceDeskConfiguration configuration)

Starts the PyrusServiceDesk interface.

Parameters

activity Starts the PyrusServiceDesk interface.
configuration The [ServiceDeskConfiguration] entity that configures the chat interface.

subscribeToReplies

public static void subscribeToReplies(@NonNull NewReplySubscriber subscriber)

Subscribes [subscriber] to notifications about new messages in the chat.

unsubscribeFromReplies

public static void unsubscribeFromReplies(@NonNull NewReplySubscriber subscriber)

Unsubscribes [subscriber] from notifications about new messages.

ServiceDeskConfiguration.Builder

public class Builder

Creates a custom chat [ServiceDeskConfiguration].

build

public ServiceDeskConfiguration build()

Creates a [ServiceDeskConfiguration] object.

setAvatarForSupport

public Builder setAvatarForSupport(@DrawableRes int drawableResId)

Specifies the identifier of the image resource that’s used as a support specialist’s avatar. By default, the standard icon is used with the color set when the **PyrusServiceDesk.start()** method is invoked. If the color isn’t specified, the background color is #008C8C.

Parameters

ID Image identifier.

setChatTitle

public Builder setChatTitle(@NonNull String title)

Contains the text for chat title. By default, it’s “Support”.

Parameters

title Contains the chat title.

setThemeColor

public Builder setThemeColor(@ColorInt int color)

Sets chat window color. By default, it’s #008C8C.

Parameters

color The color of the main elements.

setUserName

public Builder setUserName(@NonNull String userName)

The username (client’s name) that a support specialist sees in ticket in Pyrus. The name “Guest” is used by default. If a user is logged into the app, you can pass name, email address, and other info to this method.

Parameters

userName The name of a user.

setWelcomeMessage

public Builder setWelcomeMessage(@NonNull String message)

The first message that the user sees in the chat. If not specified, the chat will be displayed without a welcome message.

Parameters

message Welcome message.

NewReplySubscriber

public interface NewReplySubscriber

This interface implementation can be subscribed to notifications about new messages in the chat using the subscribeToReplies() method of the PyrusServiceDesk class.

onNewReply

void onNewReply()

Invoked when a new support message is received.

FileChooser

public interface FileChooser

To attach files to chat messages, implement the interface and pass it to [PyrusServiceDesk.registerFileChooser].

getIntent

Intent getIntent()

Used to start a file selection menu when a user clicks on the text option contained in [getLabel].

getLabel

String getLabel()

Text that appears in the menu for selecting the file source.

SetPushTokenCallback

public interface SetPushTokenCallback

A callback that is invoked when push token has been registered. Returning without exception means that the token has been successfully registered.

onResult

public void onResult(@Nullable Exception exception)

A method that is invoked when a push token has been registered.

Was this article helpful?

Yes, thanks! No, I have a question