Using the Pyrus SDK for Android, you can embed chat in your mobile app. 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.4.5' }
To let users attach files to messages, grant access to the camera and gallery.
"android.permission.WRITE_EXTERNAL_STORAGE" "android.permission.CAMERA"
The Pyrus Mobile Chat library can be authorized in one of two ways: anonymously, or externally.
Anonymous authorization makes implementation easier, as the chat is tied to a device. On an authorized device a user can participate in the chat without entering any login info.
The biggest disadvantage of anonymous authorization is that if you use the mobile app on another device, you cannot see the previous chat.
If you want the chat history to be accessible to the same user on multiple devices, you have to set up external authorization. To do this, you have to turn on a web service that tells the system a user has access to the chat.
Please note that anonymous and external authorization are mutually exclusive. If you switch the Pyrus Mobile Chat library from anonymous to external, the previous chat, which was conducted in anonymous authorization mode, will become invisible to mobile app users.
In external authorization mode the Pyrus backend does not decide on its own whether a user has access to a chat; it asks a special authorization service, which you have to turn on. Here’s how this works:
1. The user logs in on a mobile app, and then receives a pair (userID, securityKey) from your backend. The Pyrus Mobile Chat library and the Pyrus backend do not participate at this stage.
2. When initializing the Pyrus Mobile Chat library, the userID and securityKey definitions are given as parameters.
3. From then on, whenever any request is sent to the backend (for example, a request for a chat history, or when a user comment is being sent), the Pyrus Mobile Chat library automatically also sends the Pyrus backend these parameters (userID, securityKey).
3.1. Before processing the request, the Pyrus backend verifies your access rights. That’s what it sends the pair (userID, securityKey) to your authorization web service for.
3.2. The authorization web service and your backend communicate to authenticate the parameters (userID, securityKey), and they send the results of that check back to the Pyrus backend.
3.3. Upon receipt of confirmation from the authorization service, the Pyrus backend processes the request: it sends the chat history, saves the user’s comments, etc.
The authorization service URL has to be indicated in the form the mobile chat is connected to. To make sure it is, go into the settings of the selected form, and, in the Extensions section, select Mobile app chat.
Then, on the page that opens, enter the URL in the appropriate field.
When starting the app, invoke the init() method of the PyrusServiceDesk class.
The parameters of the init() method:
These parameters are used only for external authorization.
public class SampleApp extends Application { @Override public void onCreate() { super.onCreate(); PyrusServiceDesk.init( application: this, appId: "your_app_id" ); } }
public class SampleApp extends Application { @Override public void onCreate() { super.onCreate(); PyrusServiceDesk.init( application: this, appId: "your_app_id", userId: "id_of_current_user", securityKey: "secrutity_key_of_that_user" ); } }
If you send the parameter userId=nil, then anonymous authorization turns on. This is connected to a device, not to a user.
To launch the user interface, invoke the start() method of the PyrusServiceDesk class.
The start(activity) method launches the default user interface:
To configure the chat appearance, use the start(activity,configuration) method:
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:
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.
If you're using the Pyrus Mobile Chat library on multiple devices, which you can do in external authorization mode, it's useful for your mobile app to know which new comments have already been read on another device. In this case, the library calls the onNewReply function with a hasUnreadComments parameter equal to false. If the chat is open, the function will not be called even if new comments appear.
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(hasUnreadComments: Bool) { 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:
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:
comment — information about the new comment:
author — information about the author of the comment:
created_at — the date and time when the comment was created.
attachments — description of the attached files:
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:
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)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. |
@ @objc static public func createWith(_ clientId: String?, userId: String, securityKey: String)pre>Parameters
userID: | User ID line in the external system. Must stay the same for single user. |
securityKey: | The user identification line user_id in the external system. Can change for single user, if the system allows it. |
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. |
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. |
public static void start(@NonNull Activity activity)
Starts the default PyrusServiceDesk interface.
Parameters
activity | Starts the customized PyrusServiceDesk interface. |
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. |
public static void subscribeToReplies(@NonNull NewReplySubscriber subscriber)
Subscribes [subscriber] to notifications about new messages in the chat.
public static void unsubscribeFromReplies(@NonNull NewReplySubscriber subscriber)
Unsubscribes [subscriber] from notifications about new messages.
<div class="api__head"> <h2 class="sectionedit2"> onAuthorizationFailed </h2> </div> <div class="api__table-wrapper collapsing-data dont-show"> <p> Is entered when the securityKey and userID parameters have failed the authentication. </p>
</html>
public class Builder
Creates a custom chat [ServiceDeskConfiguration].
public ServiceDeskConfiguration build()
Creates a [ServiceDeskConfiguration] object.
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)
Contains the text for chat title. By default, it’s “Support”.
Parameters
title | Contains the chat title. |
public Builder setThemeColor(@ColorInt int color)
Sets chat window color. By default, it’s #008C8C.
Parameters
color | The color of the main elements. |
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. |
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. |
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(hasUnreadComments: Bool)
Invoked when a new support message is received.
public interface FileChooser
To attach files to chat messages, implement the interface and pass it to [PyrusServiceDesk.registerFileChooser].
Intent getIntent()
Used to start a file selection menu when a user clicks on the text option contained in [getLabel].
String getLabel()
Text that appears in the menu for selecting the file source.
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)
A method that is invoked when a push token has been registered.
Receives the command HTTP POST with the parameters:
The expected response: