Token-Based Authentication

There is a token-based authentication mechanism that allows a user who is logged in to your mobile application to securely activate the device they are logged in to in the Diyalog system. A user who has activated dialogue can now chat, make voice or video calls, and receive messages sent from your backoffice applications via that device.

In order to perform token-based authentication for Dialog activation from your mobile application, you must first configure the Diyalog SDK and create the Dialog Instance once your application is opened. You can find details for these processes in the How to use Dialog, Configuration and Styling documents.

DOMAIN CUSTOMER USER#

The general flow of the token-based authentication mechanism of the Diyalog system for customers is tried to be shown in the following diagram.

As explained in the flow above, in order to initiate Diyalog activation on that device for the user who is logged in to your mobile application, you are expected to generate a random token specific to Diyalog in your backend server. Your mobile application should receive this token and give it to the methods detailed below to DiyalogSDK. DiyalogSDK receives this token and sends it to its own server, and the Diyalog server will validate this token by calling your checkauthtoken API that you will provide, and will activate the user on that device after verification.

You can activate Diyalog in your mobile application with two different methods. The first of these is to use the method we call the background method, and the other is to use the method we call the frontend method. The background method activates Diyalog in the background, gives you the result, and then closes the Diyalog server connections. The other method activates the user via Diyalog and keeps the connections to server open. This second method should be used if Diyalog screens will be opened directly after the user activation. If Dialog screens will not be opened directly to the user and the user will use Diyalog screens later when desired, the background method should be used.

Regardless of which method is used, after your user logs into your application on your system, you are expected to generate a token to authenticate your user on your system and give this token to the method you call so that Diyalog can authenticate your user via your servers. Diyalog will receive this token and send it to its own server, and Diyalog server will send this token to the API detailed in the checkauthtoken document below and expected to be implemented on your servers to perform the verification. After verification, the user is created in the Diyalog system and the user is bound with the device.

a. Background method

With this method, your user will be registered securely to the Diyalog system. After registration, a session will be created in the SDK then the SDK will close its connections with the server.

Method Definition :

@objc open func startTokenAuthInBackground(
    dlgToken: String, 
    deviceID: String, 
    customerID: String, 
    customerName: String, 
    customerPhone: String = "0", 
    customerEmail: String = "", 
    result: @escaping (Bool, TokenAuthError?) -> Void)

Usage :

DiyalogEngine.diyalogInstance().startTokenAuthInBackground(
    dlgToken: "<Token generated on your server>", 
    deviceID: "<device id corralated with token>", 
    customerID: "<customerId>", 
    customerName: "<Full name of the customer>", 
    customerPhone: "<Optional - Customer phone number>", 
    customerEmail: "<Optional - Customer email address>") { (success, errorMessage) in

        if(success)
        {
            print("Success")
        }else{
            //print("there is an error")
            print("there is an error \(String(describing: errorMessage?.errorCode))")
        }

    }

Parameters :

Parameter Name	Type	Description	Mandatory
dlgToken	String	Token generated for logged in user for Diyalog auth	Yes
deviceID	String	Unique device id corralated with token	Yes
customerID	String	Customer Id of the user	Yes
customerName	String	Name of the user	Yes
customerPhone	String	Phone number of the user	No
customerEmail	String	Email address of the user	No

The method runs asynchronously and its result is returned in the completion/callback function result.

result :

Parameter Name	Type	Description	Values
success	Boolean	It returns activation success or nor.	true : Success false: failed
error	TokenAuthError	Failure detail if activation is failed.	Instance of TokenAuthError

b. Foreground method

This method is different from the background method, if Diyalog messaging screens will be opened and used immediately after Diyalog activation, you can use this method. This method was added to prevent delays during the establishment of the Diyalog server connection with the client.

If Diyalog screens will not be opened after activation, you should not use this method. Because a connection will remain open in the Diyalog system unnecessarily.

Method Definition :

@objc open func startTokenAuthForOpenDlg(
    dlgToken: String, 
    deviceID: String, 
    customerID: String, 
    customerName: String, 
    customerPhone: String = "0", 
    customerEmail: String = "", 
    result: @escaping (Bool, TokenAuthError?) -> Void)

Usage :

DiyalogEngine.diyalogInstance().startTokenAuthForOpenDlg(
    dlgToken: "<Token generated on your server>", 
    deviceID: "<device id corralated with token>", 
    customerID: "<customerId>", 
    customerName: "<Full name of the customer>", 
    customerPhone: "<Optional - Customer phone number>", 
    customerEmail: "<Optional - Customer email address>") { (success, errorMessage) in

        if(success)
        {
            print("Success")
        }else{
            //print("there is an error")
            print("there is an error \(String(describing: errorMessage?.errorCode))")
        }

    }

Parameters :

Parameter Name	Type	Description	Mandatory
dlgToken	String	Token generated for logged in user for Diyalog auth	Yes
deviceID	String	Unique device id corralated with token	Yes
customerID	String	Customer Id of the user	Yes
customerName	String	Name of the user	Yes
customerPhone	String	Phone number of the user	No
customerEmail	String	Email address of the user	No

The method runs asynchronously and its result is returned in the completion/callback function result.

result :

Parameter Name	Type	Description	Values
success	Boolean	It returns activation success or nor.	true : Success false: failed
error	TokenAuthError	Failure detail if activation is failed.	Instance of TokenAuthError

DOMAIN STAFF USER#

a. Foreground method For staff user registration client need to call below method with necessary information. After successfully register on server it will create session in Diyalog SDK and can start messaging. Using below method if user already created session in Diyalog SDK, then it will directly open that session and user can start messaging.

   DiyalogEngine.diyalogInstance().startDomainUserTokenAuth( context,  dlgToken,   sessionId,
                                         userId,
                                         userName,
                                         userPhone,
                                         userEmail);

context - Activity context dlgToken - Main application server will return Diyalog Token when user will login into main application sessionId – Staff user's sessionId userId - Staff user's UserID UserName - Staff user's UserName userPhone - Staff user's PhoneNumber(Optional) userEmail - Staff user's EmailID (Optional)

b. Background method When staff user will call background method then it will be register on server and after successfully register, it will create session into sdk. And when user will click on Diyalog chat icon from main application to open sdk, it will directly open that session. user does not wait for register. And In background method if there is any failure then it will pass error message into failure callback.

 DiyalogEngine.diyalogInstance().startDomainUserTokenAuthInBackground(context,  dlgToken,   sessionId, userId,
                                         userName, userPhone, userEmail, new TokenAuthResponse() {
                    @Override
                    public boolean success() {
                        Log.e("Auth In Bakground","==>> Success ");
                        return false;
                    }

                    @Override
                    public String failure(String errorMsg) {
                        Log.e("Auth In Bakground","==>> Error: "+errorMsg);
                        return null;
                    }
                }) ;

Get Active sessions#

User can get all sessions list those already registered in diyalog SDK. This method will be use for both Domain customer user and staff user.

ArrayList<AccountVo> sessionList = DiyalogEngine.diyalogInstance().getActiveSessions();
                

This method will return list of saved session from sdk. It will contain userInfo as below:

ApplicationUserID
AuthID
UserName
User Image.

Messaging from specific User#

User can start messaging from specific user. If session already saved into Diyalog SDK then user can start messaging with thier UserID.

DiyalogEngine.diyalogInstance().startMessagingWithUserId(context,customerId);

context - Activity context customerId - domain customer id

This method will be use for both Domain customer user and staff user.

TokenAuthError#

@objc open class TokenAuthError: NSObject {

    @objc open var errorCode: String    = ""
    @objc open var errorMsg: String     = ""

    init(_ errorCode: String, _ errorMsg: String) {
        self.errorCode = errorCode
        self.errorMsg = errorMsg
    }
}

In cases where activation fails, the following errorCode and errorMsg values are returned.

errorCode	errorMsg (English)	errorMsg (Turkish)	Meaning
DLGEXCPINP_DVCID	You must need to pass deviceId.	deviceId parametresi dolu olmalıdır.	You did not provide the deviceId parameter to the method correctly.
DLGEXCPINP_CSTID	You must need to pass customer Id.	customerId parametresi dolu olmalıdır.	You did not provide the customerId parameter to the method correctly.
DLGEXCPINP_CSTNM	You must need to pass customer name.	customerName parametresi dolu olmalıdır.	You did not provide the customerName parameter to the method correctly.
DLGEXCPINP_TKN	You must need to pass diyalog token.	diyalogToken parametresi dolu olmalıdır.	You did not provide the diyalogToken parameter to the method correctly.
DLGEXCPSRV_INVLDNM	Customer id is invalid.	Müşteri no hatalı	Customer Id is not found in the system.
DLGEXCPSRV_FRBDNCST	Forbidden customer.	Yasaklı müşteri.	Provided customer is forbidden to use Diyalog.
DLGEXCPSRV_TXHSHEXP	transactionHash has expired.	transactionHash bilgisinin süresi geçmiş.	This error occurs if the internal transaction hash information created in the Diyalog system has been used before. This error may occur when the same activation request is called more than once. It is not expected to occur.
DLGEXCPSRV_TKNNOTVLD	dlgToken is not validated by auth server.	dlgToken otorizasyon sunucusu tarafından doğrulanmadı.	This error occurs when your token is not verified by the token verification service.
DLGEXCPSRV_AUTHSRVERR	Internal failure in Auth server.	Otorizasyon sunucusu internal hata.	This error indicates that an internal server error response returned from your token verification service.
DLGEXCPSRV_BADREQ	The request rejected by auth server.	Otorizasyon sunucusu isteği kabul etmedi.	This error indicates that an bad request response was returned from your token verification service.
DLGEXCPSRV_TKNEXP	dlgToken is expired.	dlgToken süresi dolmuş	This error is the error code returned by your token verification service when the token has expired.
DLGEXCPSRV_TKNINVLD	dlgToken is invalid.	Geçersiz dlgToken.	Token is not validated by your token verification service.
DLGEXCPSRV_DVCIDINVLD	Invalid device id.	Geçersiz cihaz id.	Device id is not found by your token verification service.
DLGEXCPSRV_SIDINVLD	Invalid session id.	Geçersiz session id.	Session Id is not found by your token verification service.
DLGEXCPSRV_AUTHSRVINACC	Token authorisation server is not accessible.	Token otorizasyon sunucusuna erişim yok.	Your token verification service is not responding.
DLGEXCPSRV_INTERR	message in RpcException	message in RpcException	This is rpc exception of the the Diyalog Server.
DLGEXCPINP_SESID	You must need to pass session Id.	Oturum kimliğini geçmeniz gerekiyor.	You did not provide the sessionId parameter to the method correctly.
DLGEXCPINP_USRID	You must need to pass user Id.	Kullanıcı kimliğini geçmeniz gerekiyor.	You did not provide the userId parameter to the method correctly.
DLGEXCPINP_USRNM	You must need to pass user name.	Kullanıcı adını geçmeniz gerekiyor.	You did not provide the userName parameter to the method correctly.
DLGEXCPSRV_CONNERR	Unable to connect.	Unable to connect. Please check that you are connected to the Internet.	This error occurs when Diyalog SDK is not connected to the Diyalog server due to network or endpoint configuration error.