---
title: "Verify Telegram social link"
method: POST
path: "/v1/account/social/verify/telegram"
tags: ["verification"]
---

# Verify Telegram social link

`POST /v1/account/social/verify/telegram`

Verify ownership of a Telegram social link via the Telegram Login Widget.

**Flow:**
1. Client shows the Telegram Login Widget (bot-based, one-click)
2. Widget returns user data (id, username, etc.) + HMAC-SHA256 hash
3. Client sends the full payload to this endpoint
4. API verifies the hash using SHA256(TELEGRAM_BOT_TOKEN) as the HMAC key
5. If the username matches the account's existing Telegram social link, it's marked as verified

**Prerequisites:**
- Account must have a Telegram social link already added (via `POST /v1/account/social-links`)
- User must have a Telegram username set

**Idempotent:** Calling this on an already-verified Telegram link returns success.

Authentication: `Authorization: Bearer <CLIENT_JWT>`

## Headers

- `authorization` string, nullable — Bearer JWT issued by Grove that identifies the account.

## Request body

- TelegramVerifyRequest — Request model for POST /v1/account/social/verify/telegram. Contains the data payload from the Telegram Login Widget. The hash field is an HMAC-SHA256 signature that proves the data came from Telegram (signed with SHA256 of the bot token).
  - `id` integer, required — Telegram user ID
  - `first_name` string, required — User's first name
  - `last_name` string, nullable — User's last name
  - `username` string, nullable — Telegram username (without @)
  - `photo_url` string, nullable — URL of user's profile photo
  - `auth_date` integer, required — Unix timestamp when authentication was performed
  - `hash` string, required — HMAC-SHA256 hash for data verification

## Response `200`

Successful Response

- TelegramVerifyResponse — Response model for POST /v1/account/social/verify/telegram.
  - `verified` boolean, required — Whether the Telegram link is now verified
  - `platform` string — Platform that was verified
  - `username` string, required — Telegram username that was verified
  - `verification_method` string, required — Method used for verification

## Other responses

- `400` — Invalid hash, expired auth, no Telegram link, or username mismatch
- `401` — Missing or invalid Grove JWT
- `422` — Validation Error
- `500` — Telegram bot token not configured

---

[API](https://skmtc.net/grove/apis/grove-api.md) · [All operations](https://skmtc.net/grove/apis/grove-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/grove/grove-api/revisions/f286b48a8105/schema)