---
title: "Link Telegram"
method: POST
path: "/api/connections/telegram/link"
tags: ["connections"]
---

# Link Telegram

`POST /api/connections/telegram/link`

## Request

- Base URL: `https://api.heymetra.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.heymetra.com/api/connections/telegram/link`
- Auth: none declared

Hand back a one-time deep link the customer taps in their own bot.

Telegram has no OAuth, so ownership of a chat is proved by the customer
sending the bot a code only this tenant could have been given. The webhook
consumes it and records the chat id on the connection.

## Headers

- `authorization` string, nullable
- `x-workspace-id` string, nullable

## Response `200`

Successful Response

- TelegramInviteOut: A one-time invite the customer redeems in Telegram. The deep link only helps someone who has Telegram on the machine they are reading this on. The bot name and the raw command cover everyone else: they open Telegram on their phone and type it.
  - `deep_link` string, required
  - `bot_username` string, required
  - `command` string, required
  - `expires_in` integer, required

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/heymetra/apis/heymetra-api.md) · [All operations](https://skmtc.dev/heymetra/apis/heymetra-api/llms.txt) · [OpenAPI document](https://skmtc.dev/heymetra/apis/heymetra-api/revisions/877b0f87d6d0?raw)