setBusinessAccountUsername

Returns: TrueOfficial docs ↗

Changes the username of a managed business account. Requires the can_change_username business bot right. Returns True on success.

Parameters

business_connection_idStringRequired

Unique identifier of the business connection

usernameStringOptionalminLen 0maxLen 32

The new value of the username for the business account; 0-32 characters

Returns

On success, True is returned.

GramIO Usage

// Set the username when a business connection is established
bot.on("business_connection", async (ctx) => {
  if (ctx.canEditUsername && ctx.isEnabled) {
    await bot.api.setBusinessAccountUsername({
      business_connection_id: ctx.id,
      username: "myshop_support",
    });
  }
});

// Change username from a business message command
bot.on("business_message", async (ctx) => {
  if (ctx.text?.startsWith("/setusername") && ctx.businessConnectionId) {
    const newUsername = ctx.text.slice(13).trim();
    await bot.api.setBusinessAccountUsername({
      business_connection_id: ctx.businessConnectionId,
      username: newUsername || undefined, // pass undefined to clear
    });
    await ctx.send(newUsername ? `Username set to @${newUsername}` : "Username cleared.");
  }
});

// Remove the username (make the account accessible only by ID)
await bot.api.setBusinessAccountUsername({
  business_connection_id: "your_business_connection_id",
  // username omitted — removes the current username
});

Errors

Code	Error	Cause
400	Bad Request: USERNAME_INVALID	username contains invalid characters — only letters, digits, and underscores (5–32 chars) are allowed; cannot start with a digit
400	Bad Request: USERNAME_OCCUPIED	The username is already taken by another account — choose a different one
400	Bad Request: username is too long	username exceeds 32 characters — shorten it
400	Bad Request: BUSINESS_CONNECTION_INVALID	The business_connection_id is invalid or revoked — re-fetch from the business_connection event
403	Forbidden: not enough rights	Bot lacks can_change_username business right — check ctx.canEditUsername before calling
429	Too Many Requests: retry after N	Rate limit hit — check retry_after, use auto-retry plugin

TIP

Use GramIO's auto-retry plugin to handle 429 errors automatically.

Tips & Gotchas

• Omitting username removes it. To clear the current username, omit the field or pass undefined. After removal, the account is accessible only via its numeric ID or by sharing a direct link.
• Username format rules. Must be 5–32 characters, contain only letters (a–z, A–Z), digits (0–9), or underscores (_), and must not start with a digit.
• Username availability. There is no "check availability" method — if the username is taken, you'll get USERNAME_OCCUPIED. Build a retry UI or fallback in your bot.
• Check canEditUsername before calling. The bot must have can_change_username right. Verify with ctx.canEditUsername when handling business_connection events.
• business_connection_id must be current. Retrieve from ctx.id in business_connection handlers, or ctx.businessConnectionId in business_message handlers.

See Also

• setBusinessAccountName — change the business account's display name
• setBusinessAccountBio — change the bio
• setBusinessAccountProfilePhoto — change the profile photo
• BusinessConnection — business connection object with rights (canEditUsername, isEnabled, etc.)