---
title: "Connect a Telegram channel (notification-channel-routing-telegram, v1.126)"
method: POST
path: "/agent/v1/notifications/channels/telegram"
tags: ["Agent"]
---

# Connect a Telegram channel (notification-channel-routing-telegram, v1.126)

`POST /agent/v1/notifications/channels/telegram`

## Request

- Base URL: `https://api.run402.com`
- URL: `https://api.run402.com/agent/v1/notifications/channels/telegram`
- Auth: API key in header `SIGN-IN-WITH-X`

operator_passkey assurance AND a verified contact email (bindings are addressed to the verified email). operator_passkey is satisfied by the wallet contact's passkey binding OR by a passkey-fresh, same-client control-plane session sent as `Authorization: Bearer` beside `SIGN-IN-WITH-X`, whose principal holds the contact's verified email (one person, one passkey). Creates a pending binding and returns a single-use, 15-minute deep link for a dedicated customer-facing notification bot (never the internal ops bot); the binding activates when the owner taps the link in Telegram and the bot's inbound update resolves the code. No bot token or credential is ever asked for or returned. 503s until the platform's Telegram notification bot is provisioned (docs/runbooks/telegram-notify-bot.md).

## Headers

- `SIGN-IN-WITH-X` string, required

## Request body

- object
  - `label` string: Optional human name for this chat, e.g. "kysigned prod".

## Response `201`

Pending binding created

- object
  - `binding_id` string, uuid
  - `status` 'pending'
  - `connect_url` string: t.me/<bot>?start=<code> — private chat, 15-minute single-use code.
  - `connect_group_url` string: t.me/<bot>?startgroup=<code> — same code, group chat.
  - `code_expires_at` string, date-time
  - `label` string, nullable
  - `next_actions` object[]: open_telegram_connect_url is domain-specific (style.md: the core vocabulary has no 'go tap this external link' verb — mirrors write-approval.ts's open_confirm_url for the same shape). poll points GET .../channels to observe pending -> active.
    - `type` 'open_telegram_connect_url' | 'poll'
    - `method` string
    - `path` string
    - `why` string

## Other responses

- `400`: label is not a non-empty string of at most 64 characters (VALIDATION_FAILED)
- `403`: operator_passkey assurance not met (FORBIDDEN) — `CONTACT_PASSKEY_REQUIRED` names `run402 login`; `STEP_UP_REQUIRED` names `--step-up` when the session's passkey proof is stale
- `404`: No agent contact registered for this wallet — register via POST /agent/v1/contact first (RESOURCE_NOT_FOUND)
- `412`: Contact email exists but is not verified (CONTACT_EMAIL_NOT_VERIFIED) — verify via POST /agent/v1/contact before binding a channel
- `503`: The Telegram notification channel is not provisioned on this deployment (TELEGRAM_CHANNEL_NOT_CONFIGURED)

---

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