Mesibo Backend APIs - User Management

Before your users can use mesibo services, mesibo need to know about your users so that mesibo can enable real-time messaging, calls, and conference between them.

mesibo identifies each user by a unique random string, called address. The address can be anything, for example, phone number, email address, your enterprise user ID, etc. You need to create a mesibo user for each of your app users.

mesibo will generate an authentication token when you create a user. This user token is also called the access token. You need to send this token to your apps so that your app can initialize mesibo Mesibo Real-time APIs using this token. Refer to the Get Started tutorial to learn more about it.

mesibo backend user-management APIs allow you to create and edit users and able to generate access tokens. You can anytime add, edit or delete users or access tokens using backend APIs as explained below.

Adding a User

To add a user and to generate a user access token, you need to send the following JSON request to the backend API. You can use the same API to regenerate the token:

{
  "op":"useradd",
  "token": "ptlk9hdel1gqxf3p0s15f5f5gtusldej18tl794suzit",
  "user": {
	"address":"xyz@example.com",
	"name":"User Name",

  	"token": {
		"appid": "com.example.mesiboapp",
		"expiry": 525600
  	}
  }
}

Following are the request parameters, some of them are OPTIONAL.

Basic Parameters

Following are the request parameters, most of them are OPTIONAL unless the Default value is mentioned as Mandatory.

Token Generation Parameters

You need to use the following parameters when generating or regenerating user access token. The generated token is restricted to an application that corresponds to the appid provided in the request. The token can contain up to 256 characters.

For Android, appid is the package name declared in the AndroidManifest.xml file or google-services.json.

For iOS, this is the Bundle ID declared in the Xcode project.

The generated token will only work for the app with that specific package name or Bundle ID.

For platforms other than Android and iOS, you can input any non-numeric, dot-separated string (e.g., com.yourdomain.yourapp). This exact string must also be used for the setAppName function and should be in lowercase.

The Mesibo client-side API offers the getAppIdForAccessToken convenience function to get the App ID associated with the app.

Additional v2 Token Format Parameters

The mesibo API v2.5.2 and above supports a new, more secure user token format (v2). You should use the v2 format to benefit from additional security and features described below. From January 1st, 2025, the v2 token format will be the default for all new tokens generated.

If any platform is specified in the request, the token will be valid only on those platforms. If no platform is specified, the token will be valid on all supported platforms. You can specify multiple platforms. However, it is recommended to restrict the token to the required platforms only.

With the v2 format, appid is optional for all supported platforms except Android and iOS. For Android, You can also use package instead of appid which also restricts token on Android. Similarly, for iOS, you can use bundle instead of appid.

User Permissions Parameters

You need to use the following parameters only if you need to set custom permissions for the user.

User Profile Parameters

You need to use the following parameters only if you are setting profile information from the backend. Generally, the profile information is set by the user/apps using real-time profile APIs.

User Contacts Parameters

You need to use the following parameters only if you are adding or modifying contacts for the user. Generally, the contact information is set by the user/apps using real-time contact sync APIs.

If the request is successful, the response will be like,

{ 
  "user": {
	"uid":123,
	"address":"xyz@example.com",
	"token":"79a818d76fe45fb5a3ac395a0a98251c3db2eetb7b0d4aa0"
  },
  "op":"useradd",
  "result":true
}

where,

• user.address = User address that was sent in the request
• user.uid = Numerical unique user ID generated by the backend. You can use this UID instead of the address in other requests.
• user.token = Access token which you should use in the real-time API

You should save user information (UID, Address, Access Token, etc.) from the response to your database so that you can access them later. If you do not save them and instead call mesibo backend API every time you need them, your app will be slow, and you may be charged for excessive backend API usage (refer to the Backend API Invocations on the Pricing page).

Modifying a User

To edit an existing user, send the following JSON request to the backend API. You need to use the address or the UID obtained from the useradd operation.

{
  "op":"userset",
  "token": "ptlk9hdel1gqxf3p0s15f5f5gtusldej18tl794suzit",
  "user": {
	"uid":123,
        
	"profile": {
		"name":"User Name",
		"image":"https://example.com/image.jpg",
		"description":"Some description",
  	}
  }
}

The userset request is the same as the useradd request. The only difference is that the user MUST already exist for the userset request to succeed. The request will fail if the user does not exist.

The request and response parameters are the same as the ones in useradd operation.

Deleting a User

Delete an existing user using address or UID obtained from the useradd operation. You should either pass address or UID and not both.

{
  "op":"userdel",
  "token": "ptlk9hdel1gqxf3p0s15f5f5gtusldej18tl794suzit",
  "user": {
	"uid":123
  }
}

If you are using the multi-device login feature and want to delete all users linked to the user you are deleting, you can pass the additional parameter linked set to true. Otherwise, only the specified user will be deleted. Note that, if the user being deleted is the parent user, all linked users will be deleted regardless of the presence or value of the linked parameter.

{
  "op":"userdel",
  "token": "ptlk9hdel1gqxf3p0s15f5f5gtusldej18tl794suzit",
  "user": {
	"uid":123
    "linked": true
  }
}

If the request is successful, the response will be like,

{ 
  "user": { 
	  "uid":123 
  },
  "op":"userdel",
  "result":true
}

Delete a User Access Token

Delete an existing user access token without deleting a user. The user will be logged-out but mesibo will store all received messages for the user. Those messages will be delivered when the user logs in the next time with a new token.

To delete the user token, send userset request with user.token.remove parameter:

{
  "op":"userset",
  "token": "ptlk9hdel1gqxf3p0s15f5f5gtusldej18tl794suzit",
  "user": {
	"uid":123

  	"token": {
		"remove": true
  	}
  }
}

Get Users (on-premise hosted backend only)

Get users using an address or a UID. You can use a pattern to get matching users.

On Cloud, this API is only for development purposes only, and hence it is rate-limited and a maximum of 20 users will be returned. The reason is that many mesibo customers have millions of users and it is not practical to retrieve them. You should store your users locally instead of obtaining from the mesibo. You MUST not use this API in production and excessive use can be blocked. However, no such limitations apply for on-premise.

To get users, send usersget request with address or uid parameter and the count. You can also send empty request (without address or uid).

{
  "op":"usersget",
  "token": "ptlk9hdel1gqxf3p0s15f5f5gtusldej18tl794suzit",
  "count": 50
  "user": {
	"uid":123
  }
}

You can also use '*' wildcards in address field to get multiple users matching the pattern, for example,

{
  "op":"usersget",
  "token": "ptlk9hdel1gqxf3p0s15f5f5gtusldej18tl794suzit",
  "count": 50
  "user": {
	"address": "hello*"
  }
}