verifyUser

Returns: TrueOfficial docs ↗

Verifies a user on behalf of the organization which is represented by the bot. Returns True on success.

Parameters

user_idIntegerRequired

Unique identifier of the target user

custom_descriptionStringOptionalminLen 0maxLen 70

Custom description for the verification; 0-70 characters. Must be empty if the organization isn't allowed to provide a custom verification description.

Returns

On success, True is returned.

GramIO Usage

// Verify a user by their numeric ID
await bot.api.verifyUser({
    user_id: 123456789,
});

// Verify a user with a custom description
await bot.api.verifyUser({
    user_id: 123456789,
    custom_description: "Verified member",
});

// Verify a user from a message context
bot.command("verify", async (ctx) => {
    const replyMsg = ctx.replyMessage;
    if (!replyMsg?.from) return ctx.reply("Reply to a user's message.");

    await bot.api.verifyUser({
        user_id: replyMsg.from.id,
        custom_description: "Verified by admin",
    });

    await ctx.reply(`User ${replyMsg.from.id} has been verified.`);
});

// Remove user verification
await bot.api.removeUserVerification({
    user_id: 123456789,
});

Errors

Code	Error	Cause
400	Bad Request: USER_NOT_FOUND	user_id is invalid or the user has never interacted with the bot
400	Bad Request: custom description not allowed	Your organization isn't authorized to provide custom descriptions — omit the field or pass an empty string
400	Bad Request: user can't be verified	The target user cannot be verified in the current context (e.g. bots cannot be verified)
403	Forbidden: not enough rights	The bot hasn't been granted third-party verification permissions by Telegram

Tips & Gotchas

• Only bots with explicit Telegram approval can use this method. Third-party verification is not available to arbitrary bots — your organization must be approved at telegram.org/verify.
• custom_description is 0–70 characters. If your organization is not permitted to set custom descriptions, pass an empty string or omit the field — otherwise the call returns an error.
• The user must have started a conversation with the bot. Telegram needs to resolve the user_id, so the user must have at least sent a message to the bot previously.
• To update the description, call verifyUser again. Re-calling with a new description replaces the existing one.
• To remove the verification badge, call removeUserVerification. Verification is not permanent and can be revoked at any time.

See Also

• removeUserVerification
• verifyChat
• removeChatVerification