setBusinessAccountProfilePhoto

Returns: True📎 Accepts files Official docs ↗

Changes the profile photo of a managed business account. Requires the can_edit_profile_photo business bot right. Returns True on success.

Parameters

business_connection_idStringRequired

Unique identifier of the business connection

photoInputProfilePhotoRequired

The new profile photo to set

is_publicBooleanOptional

Pass True to set the public photo, which will be visible even if the main photo is hidden by the business account's privacy settings. An account can have only one public photo.

Returns

On success, True is returned.

GramIO Usage

// Set a static JPEG profile photo when a business connection is established
bot.on("business_connection", async (ctx) => {
  if (ctx.canEditProfilePhoto && ctx.isEnabled) {
    await bot.api.setBusinessAccountProfilePhoto({
      business_connection_id: ctx.id,
      photo: {
        type: "static",
        photo: await MediaUpload.path("./assets/business-avatar.jpg"),
      },
    });
  }
});

// Set an animated MPEG4 profile photo
bot.on("business_connection", async (ctx) => {
  if (ctx.canEditProfilePhoto && ctx.isEnabled) {
    await bot.api.setBusinessAccountProfilePhoto({
      business_connection_id: ctx.id,
      photo: {
        type: "animated",
        animation: await MediaUpload.path("./assets/business-avatar.mp4"),
        main_frame_timestamp: 0.5, // frame used as static preview (seconds)
      },
    });
  }
});

// Set the public photo (visible even when main photo is hidden by privacy settings)
await bot.api.setBusinessAccountProfilePhoto({
  business_connection_id: "your_business_connection_id",
  photo: {
    type: "static",
    photo: await MediaUpload.url("https://example.com/logo.jpg"),
  },
  is_public: true,
});

Errors

Code	Error	Cause
400	`Bad Request: PHOTO_INVALID_DIMENSIONS`	Image dimensions are too large or too small — use a square image, ideally 640×640 px
400	`Bad Request: wrong file identifier/HTTP URL specified`	Photo must be uploaded as a new file; `file_id` reuse is not supported for profile photos
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_edit_profile_photo` right — check `ctx.canEditProfilePhoto` 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

Profile photos cannot be reused via file_id. Unlike other media, profile photos must always be uploaded as new files. Use MediaUpload.path(), MediaUpload.url(), or MediaUpload.buffer() — never a cached file_id string.
Static photos must be JPEG. Telegram only accepts .jpg/.jpeg format for InputProfilePhotoStatic. PNG or WebP will be rejected.
Animated photos must be MPEG4. Use .mp4 files for InputProfilePhotoAnimated. The main_frame_timestamp (in seconds) determines which frame is shown as the still preview; defaults to 0.0.
Only one public photo at a time. Passing is_public: true replaces any existing public photo. The public photo is visible regardless of the account's privacy settings.
Check canEditProfilePhoto before calling. The bot must have can_edit_profile_photo right. Verify with ctx.canEditProfilePhoto in business_connection handlers.
Use removeBusinessAccountProfilePhoto to delete. There is no way to "unset" the photo via this method — use the dedicated remove method instead.

setBusinessAccountProfilePhoto ​

Parameters ​

Returns ​

GramIO Usage ​

Errors ​

Tips & Gotchas ​

See Also ​