Authenticating Users

If your software or application has an existing user authentication method then you can optionally federate those identities with Smooch by issuing a JSON web token (JWT). A JWT is required to protect the identity and data of these users. This option requires your app to be connected to your own secure web service. There are JWT libraries available supporting a wide variety of popular languages and platforms.

First, you must assign a userId to each of your users. The userId will uniquely identify your users within Smooch and the JWTs you issue serve as a signed proof that your software or app has successfully authenticated that user.

To log in with a JWT:

  1. Generate a secret key pair for your Smooch app. You can do this from the Smooch dashboard under the Settings tab.

  2. Implement server side code to sign new JWTs using the key ID and secret provided. The JWT header must specify the key ID (kid). The JWT payload must include a scope claim of appUser and a userId claim which you’ve assigned to the app user. Make sure the userId field is formatted as a String. If you use numeric ids, the userId must be a String representation of the number - using a number directly will result in an invalid auth error.

    A node.js sample is provided below using jsonwebtoken >= 6.0.0

    var jwt = require('jsonwebtoken');
    var KEY_ID = '55e9f9bf7a0ce5ca2d429c17';
    var SECRET = 'BFJJ88naxc5PZNAMU9KpBNTR';
    
    var signJwt = function(userId) {
        return jwt.sign({
            scope: 'appUser',
            userId: userId
        },
        SECRET,
        {
            header: {
                alg: 'HS256',
                typ: 'JWT',
                kid: KEY_ID
            }
        });
    }
    
  3. Issue a JWT for each user. You should tie-in the generation and delivery of this JWT with any existing user login process used by your app.

  4. Initialize Smooch in your website or app. See instructions for Web, iOS and Android.

  5. Call Smooch.login with your userId and jwt:

    Web (Javascript):

    Smooch.login("user-id", "jwt")
        .then(function() {
            // Your code after login is complete
        });
    

    iOS (Objective-C):

    [Smooch login:@"user-id" jwt:@"jwt" completionHandler:^(NSError * _Nullable error, NSDictionary * _Nullable userInfo) {
        // Your code after login is complete
    }];
    

    iOS (Swift):

    Smooch.login("user-id", jwt:"jwt") { ( error:Error? , userInfo:[AnyHashable : Any]?) in
        // Your code after login is complete
    }
    

    Android (Java):

    Smooch.login("user-id", "jwt", new SmoochCallback() {
        @Override
        public void run(Response response) {
            // Your code after login is complete
        }
    });
    

Users on multiple clients

You may have a single user logging in as the same userId from multiple clients. For example, they have your app installed on both their iPhone and their iPad. You might also have Smooch integrated in both your mobile app as well as on your web site.

Once a user has been logged in to Smooch, they will see the same conversation across each of these clients.

Omitting the userId

Smooch will work perfectly fine without a userId. Profile information can still be included, and the user can take advantage of all rich messaging features, but the user will only be able to access the conversation from the client they’re currently using. Without a userId, if the same individual opens Smooch on a new client, or runs your web app in an incognito browser session, they will see a newly created empty conversation when they open Smooch, and on the business side they will be represented as two distinct appUsers. This will happen even if you specify the same profile information in both cases.

A userId can also be omitted at first and added at a later time. If you deploy an update to your app that assigns an existing user with a new userId that they didn’t have before, any existing conversation history they have will be preserved and their messages will start being synchronized across all clients where that userId is being used. This is particularly useful if a user opens Smooch and starts a conversation before having logged in to your app or website.

Switching users

If your app allows a shared client to switch between multiple user identities you can call the login API multiple times to switch between different userIds.

Logging out

Your app may have a logout function which brings users back to a login screen. In this case you would want to revert Smooch to a pre-login state. You can do this by calling the logout API.

Calling logout will disconnect your user from any userId they were previously logged in with and it will remove any conversation history stored on the client. Logging out will not disable Smooch. While logged out, the user is free to start a new conversation but they will show up as a different appUserId on the business end.

Web (Javascript):

Smooch.logout()
    .then(function() {
        // Your code after logout is complete
    });

iOS (Objective-C):

[Smooch logoutWithCompletionHandler:^(NSError * _Nullable error, NSDictionary * _Nullable userInfo) {
    // Your code after logout is complete
}];

iOS (Swift):

Smooch.logout { (error:Error? , userInfo:[AnyHashable : Any]?) in
    // Your code after logout is complete
}

Android (Java):

Smooch.logout(new SmoochCallback() {
    @Override
    public void run(Response response) {
        // Handle logout result
    }
});