getUserProfileAudios

Returns: UserProfileAudiosOfficial docs ↗

Use this method to get a list of profile audios for a user. Returns a UserProfileAudios object.

Parameters

user_idIntegerRequired

Unique identifier of the target user

offsetIntegerOptional

Sequential number of the first audio to be returned. By default, all audios are returned.

limitIntegerOptional Default: 100min 1max 100

Limits the number of audios to be retrieved. Values between 1-100 are accepted. Defaults to 100.

Returns

On success, the UserProfileAudios object is returned.

GramIO Usage

// Get all profile audios for a user:
const result = await bot.api.getUserProfileAudios({
  user_id: 12345678,
});

console.log(`User has ${result.total_count} profile audio(s)`);

// Check if a user has set a profile audio in a message handler:
bot.command("audio", async (ctx) => {
  if (!ctx.from) return;

  const result = await bot.api.getUserProfileAudios({
    user_id: ctx.from.id,
    limit: 1,
  });

  if (result.total_count === 0) {
    return ctx.send("You haven't set a profile audio yet.");
  }

  await ctx.send(`You have ${result.total_count} profile audio(s).`);
});

// Paginate through profile audios in batches of 10:
const page1 = await bot.api.getUserProfileAudios({
  user_id: 12345678,
  offset: 0,
  limit: 10,
});

// Fetch next page if more audios exist:
if (page1.total_count > 10) {
  const page2 = await bot.api.getUserProfileAudios({
    user_id: 12345678,
    offset: 10,
    limit: 10,
  });
  console.log("Second page audio count:", page2.audios.length);
}

Errors

Code	Error	Cause
400	Bad Request: user not found	The user_id doesn't correspond to a known Telegram user
400	Bad Request: chat not found	User is inaccessible (never interacted with the bot and no shared chat)
429	Too Many Requests: retry after N	Rate limit hit — check retry_after and back off

TIP

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

Tips & Gotchas

• Not all users have profile audios. Profile audio is a Telegram Premium feature — total_count will be 0 for users who haven't set one. Always check before processing.
• offset is an integer (sequential position). Unlike getUserGifts, pagination here uses a numeric offset — pass 0 for the first audio, 10 for the eleventh, etc.
• total_count reflects all available audios, not just the current page. Use it to calculate whether more pages exist (total_count > offset + limit).
• Requires the user to have interacted with the bot or share a mutual chat — otherwise Telegram may return a "user not found" error.
• Added as part of the profile audio feature. This method mirrors getUserProfilePhotos in structure but for audio files set as profile backgrounds.

See Also

• UserProfileAudios — return type with total_count and audios array
• getUserProfilePhotos — analogous method for profile photos