App management

An app is a self-contained IM environment: IM users, friends, groups, chat rooms, messages and files all belong to an app, and data is fully isolated between apps. Each app has its own AppKey, server credentials, IP allowlist, runtime policies and plan. We recommend separate apps for test and production.

See all of the tenant's apps under "Workbench → App management" in the menu, filtered by status (active, disabled) if you like. Every member can view apps; creating, editing, disabling and deleting them needs owner or admin.

At sign-up the system already created an app named demo for the new tenant; see Sign up. Use it directly for trying things out or development and testing, and create a separate app for production.

Current app

The app selector at the top of the console sets the current app, shown by display name and app_name. "Overview", "Plans" and "Audio/video billing" all show the current app; switching apps on any of them switches the others too. Switching apps inside app details opens the same tab of the chosen app.

The selector can't be cleared. When you open the console it selects the first app in the list, and keeps your choice as you move between pages.

Create an app

Click "Create app" next to the app selector at the top of the console and fill in:

Field	Description
App name (app_name)	The app's identifier: starts with a lowercase letter and uses lowercase letters, digits and -, 3 to 32 characters, such as chat-test or chat-prod. Unique within the tenant (demo is already taken at sign-up), and it can't be changed after creation or reused after deletion
Display name	A name that's easy to recognize, up to 128 characters; can be changed later
Description	Optional, up to 512 characters
Client sign-up	Whether users can sign up from the client themselves, off by default; see Client sign-up below

Apps are created in the tenant's default region. Each tenant can have up to 10 apps (deleted ones don't count); for more, complete business verification first.

New apps use the platform's default plan automatically and are billed from the day they're created; see Plans and bills.

Once created, the console opens the new app's details and shows "App created" with its app_key and first set of server credentials:

• app_key: used by clients to sign in; see AppKey below.
• client_id and client_secret: your server uses them to get an App Token. Save the client_secret in your server's secret management system, then click "I've saved the secret".

After that, copy the app_key and client_id from "Access credentials" on the Overview at any time; to see the client_secret again, click "View" and verify your identity again to show the full value. You can also rotate to a new one under "Server secret"; see Server credentials and IP allowlist.

AppKey

The AppKey joins the tenant's org_name and the app's app_name with #. It works as soon as the app is created and never changes:

1100250925#demo
└── org_name ┘└ app_name

Clients sign in with the AppKey; server REST API addresses use the two parts separately, such as https://api.example.com/1100250925/demo/users; see Integration overview. The app_key can be copied from the top of both the app list and app details.

Client sign-up

"Client sign-up" decides who can create IM users:

Option	Value	Description
Off (default)	authorized	Only your server, by calling the create user API, or the console can create IM users. Users can only use accounts you allow, which suits production
Open	open	Users can also sign up from the client, and anyone with the AppKey can register. Only recommended for test apps

App details

Click an app's name in the app list to open its details. The top shows the display name, app_name, status and app_key, with these tabs below:

Tab	Contents
Overview and settings	User and connection stats, app info, and editing, disabling and deleting the app
IM users, Groups, Messages, Chat rooms	Managing the app's data; see Users, groups, chat rooms and messages
Audio/video	Audio/video availability, call stats and the call list, ending calls; see Audio/video
File storage	Storage usage, and viewing, downloading, deleting and uploading files; see File storage
Push	Push credentials, notification templates and push stats; see Push settings
Callbacks	Callback endpoints, sync callbacks and the event catalog; see Callback settings
Content moderation	Moderation config, word lists, moderation items, platform actions, user violations and stats; see Content moderation settings
App policies	This app's runtime policies; see Runtime policies
Plan and usage	The current plan, quotas, plan change history and daily usage; see The app's plan and usage
Server secret, IP allowlist	See Server credentials and IP allowlist

App info in "Overview and settings":

Item	Description
Display name, description	Can be changed
app_id	The app ID; application in the response when getting an App Token is this value
Client sign-up	Open or off; can be changed
Region	Where the app's data lives; can't be changed after creation
Plan tier, messages per minute limit	Protective quotas the platform sets for the app, read-only; see Quotas and circuit breaking. The "plan tier" is unrelated to the billing plan
Created	When the app was created

For the user and connection stats at the top, see Users, groups, chat rooms and messages.

Edit an app

owner and admin click "Edit" in "Overview and settings" to change the display name, description and client sign-up. app_name and region can't be changed.

After switching client sign-up from open to off, clients can't register new users; users who already registered aren't affected.

Disable and enable

To stop an app serving for a while (such as a test app not in use, or after discovering leaked credentials), disable it. owner and admin click "Disable app" in "Overview and settings":

• All App Tokens and User Tokens the app issued stop working immediately, and online clients are disconnected.
• Servers calling OpenAPI with an old App Token get 401 unauthenticated, and getting a new App Token returns 403 app_unavailable; clients can't sign in.
• All the app's data is kept. In the console you can still edit the app and manage its server secret, IP allowlist and app policies.
• The app is still billed while disabled; see Billing rules.

Click "Enable app" to restore service. Servers need to get a new App Token; clients can keep going by renewing their tokens without signing in again, but users whose downtime exceeded the sign-in lifetime (7 days by default) must sign in again.

Delete an app

owner and admin click "Delete app" in "Overview and settings", confirm, and verify their identity again.

• The app disappears from the console immediately, all issued tokens stop working, and online clients are disconnected.
• All of the app's IM users, friends, groups, messages and files are permanently deleted in the background in batches.
• App Tokens issued before get 401 unauthenticated from OpenAPI with details.reason app_deleted; servers should then clear the saved credentials and stop retrying.
• This app_name can't be used for a new app, so clients still using the old AppKey never connect to a new app.
• The day of deletion is the app's last billing day.

Deletion can't be undone

Deleted data can't be recovered, and the app_name can't be used again. If you only want to stop using it for now, disable the app.

Quotas and circuit breaking

An app's resources have two kinds of limits:

• Plan quotas: limits on counts such as registered users, concurrent connections, total groups, members per group, storage, concurrent calls and chat rooms come from the app's plan, shown in "Plan and usage"; see Quotas.
• Protective quotas: a set of quotas the platform sets for each app so abnormal traffic doesn't affect the service, such as messages per minute and requests per second.

"Overview and settings" in the console shows two of the protective quotas, view-only:

Item	Description
Plan tier	The protective quota tier the platform assigned to the app, standard by default. It's only a label: the actual quota values follow the platform's settings, and it's unrelated to the billing plan
Messages per minute limit	The most messages the app can send per minute, 30000 by default. Messages from both clients and servers count, and server batch sends count per recipient. Beyond it, sending returns 429 rate_limited

Storage and chat rooms also each have a protective quota (1024 GB of storage and 10,000 chat rooms by default), and the smaller of the protective quota and the plan quota applies. The app's storage quota is shown under Storage usage in "File storage", and once full, new files can't be uploaded.

Server OpenAPI and client APIs also each have a requests-per-second limit, returning 429 rate_limited beyond it. When an app's traffic is abnormal, the platform may also rate-limit it, make it read-only (users can sign in and view, but not send messages or change data) or suspend it. For the exact rules and error codes, see Rate limits and app status. For more users, connections, storage and other plan quotas, change the plan; to raise protective quotas such as messages per minute, contact us.

RTC channels

"RTC channels" in app details lets you look up channels, members, sessions, stats and corrections, and take the actions your role allows; see RTC channel management. It's separate from the call list under "Audio/video", and the number of open channels and concurrent media are separate limits.