setBusinessAccountName

Returns: TrueOfficial docs ↗

Changes the first and last name of a managed business account. Requires the can_change_name business bot right. Returns True on success.

Parameters

business_connection_idStringRequired

Unique identifier of the business connection

first_nameStringRequiredminLen 1maxLen 64

The new value of the first name for the business account; 1-64 characters

last_nameStringOptionalminLen 0maxLen 64

The new value of the last name for the business account; 0-64 characters

Returns

On success, True is returned.

GramIO Usage

// Set the display name when a business connection is established
bot.on("business_connection", async (ctx) => {
  if (ctx.canEditName && ctx.isEnabled) {
    await bot.api.setBusinessAccountName({
      business_connection_id: ctx.id,
      first_name: "Acme",
      last_name: "Support",
    });
  }
});

// Update name from a business message handler
bot.on("business_message", async (ctx) => {
  if (ctx.text?.startsWith("/rename") && ctx.businessConnectionId) {
    const newName = ctx.text.slice(8).trim(); // e.g. "/rename NewShop"
    await bot.api.setBusinessAccountName({
      business_connection_id: ctx.businessConnectionId,
      first_name: newName,
      // last_name omitted — clears the last name
    });
    await ctx.send(`Name updated to: ${newName}`);
  }
});

// Set only a first name (no last name)
await bot.api.setBusinessAccountName({
  business_connection_id: "your_business_connection_id",
  first_name: "My Online Store",
});

Errors

Code	Error	Cause
400	Bad Request: first_name is empty	first_name is required and must be 1–64 characters — never send an empty string
400	Bad Request: first_name is too long	first_name exceeds 64 characters — truncate before calling
400	Bad Request: last_name is too long	last_name exceeds 64 characters — truncate before calling
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_name business right — check ctx.canEditName 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

• first_name is required and must be 1–64 characters. Unlike the bio, you cannot omit or clear the first name — it always needs a non-empty value.
• Omitting last_name clears it. If the account currently has a last name and you don't pass last_name, it will be removed.
• Check canEditName before calling. The bot must have can_change_name right. Verify with ctx.canEditName when handling business_connection events.
• Name changes are visible immediately in Telegram. Be careful with automated renames — avoid changing the name too frequently or users may become confused.
• business_connection_id must be current. Retrieve from ctx.id in business_connection handlers, or ctx.businessConnectionId in business_message handlers.

See Also

• setBusinessAccountBio — change the business account's bio
• setBusinessAccountUsername — change the business account's username
• setBusinessAccountProfilePhoto — change the profile photo
• BusinessConnection — business connection object with rights (canEditName, isEnabled, etc.)