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.

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.

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"

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"
       );
   }
}

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
       );
   }
}

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())

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");
   }
}

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

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);
           }
       });
   }
}

This is the main class for working with embeddable chat.

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

public static void registerFileChooser(@Nullable FileChooser fileChooser)

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

public static void start(@NonNull Activity activity)

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

public static void subscribeToReplies(@NonNull NewReplySubscriber subscriber)

public static void unsubscribeFromReplies(@NonNull NewReplySubscriber subscriber)

public class Builder

Creates a custom chat [ServiceDeskConfiguration].

public ServiceDeskConfiguration build()

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.

public Builder setChatTitle(@NonNull String title)

public Builder setThemeColor(@ColorInt int color)

public Builder setUserName(@NonNull String userName)

public Builder setWelcomeMessage(@NonNull String message)

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.

void onNewReply()

public interface FileChooser

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

Intent getIntent()

String getLabel()

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.

public void onResult(@Nullable Exception exception)