Sinch Client

The Sinch SDK is a product that makes adding voice and video calling to mobile apps easy. Continue reading this step-by-step guide now.

The SinchClient is the Sinch SDK entry point. it's used to configure the user’s and device’s capabilities, as well as to provide access to feature classes such as the CallController, AudioController and VideoController.

Create the SinchClient

Set up the Sinch client, using SinchClientBuilder:

val sinchClient = SinchClient.builder()
                   .applicationKey("<application key>")
                   .userId("<user id>")
  • The Application Key is obtained from the Sinch Developer Dashboard - Apps .
  • The User ID should uniquely identify the user on the particular device.
  • (The term Ocra in the hostname is just the name for the Sinch API that the SDK clients target)
  • The Push Configuration is a configuration object that allows Sinch SDK to send push messages notifying about incoming calls. See push noficiation section for more information about this feature.

Start the Sinch Client

Before starting the client, add a SinchClientListener:

sinchClient.addSinchClientListener(object: SinchClientListener() {

    override fun onClientStarted(client: SinchClient) { }
    override fun onClientFailed(client: SinchClient, error: SinchError) { }
    override fun onCredentialsRequired(clientRegistration: ClientRegistration) {
      // You have to implement this method, it can't be no-op.
    override fun onLogMessage(level: Int, area: String, message: String) { }


When starting the client (sinchClient.start()) the client will ask for a token via SinchClientListener.onCredentialsRequired(). See section Authentication & Authorization for the details.


All listener callbacks emitted from the Sinch SDK are invoked on the same thread that the call to is made on. If the invoking thread is not the main-thread, it needs to have an associated Looper.

Authorizing the Client / User

When the SinchClient is started with a given User ID it's required to provide an authorization token to register towards the Sinch backend. To authorize a client, implement SinchClientListener.onCredentialsRequired() that's cryptographically signed with the Application Secret.

The sample applications included in the Sinch SDK includes a class JWT that describes how to create the JWT and sign it with the Application Secret.

class MySinchClientListener: SinchClientListener() {

        override fun onCredentialsRequired(clientRegistration: ClientRegistration) {
            val jwt = JWT.create(APP_KEY, APP_SECRET, userName)

See section Authentication & Authorization for the details.


When deploying your application to production, don't embed the Application Secret in the application. The example above is only meant to show how to provide a signed JWT to the SinchClient. Implement the required functionality on your backend and fetch signed registration token when required.

Registering the user via UserController API

You can also register a user towards the Sinch backend via UserController API. This lightweight component provides a way to register the user without starting the SinchClient. You can also register push token for Managed Push to receive incoming calls even when the application is closed/in background. The UserController uses the very same authentication scheme as the SinchClient based on the signed JWT registration token that you provide in response to onCredentialsRequired() method of UserRegistrationCallback. The UserController provides better control over the registration process than the SinchClient by providing callbacks for each step of the registration.

Lifecycle management of a SinchClient instance

We recommend that you initiate the SinchClient, start it, but not terminate it, during the lifetime of the running application. That also implies that the SinchClient instance should be retained by the application code. It's best to keep the client instance alive and started unless there are reasons specific to your application.

The SinchClient can of course be completely stopped and also disposed.


Stopping / disposing of SinchClient won't affect receiving incoming calls if the user was previously registered towards the Sinch backend via UserController API. Upon receiving incoming call push notification instantiate and forward the push payload to the new SinchClient instance.

When the app is done using the SinchClient, it can be stopped and disposed using SinchClient.terminateGracefully().

Example of how to completely dispose the SinchClient:

sinchClient = null
We'd love to hear from you!
Rate this content:
Still have a question?
Ask the community.