wehub-resource-sync
6ede33ccdb
Build and Push Docker Images / create_manifest (web, surfsense-web, , cpu) (push) Has been cancelled
Build and Push Docker Images / finalize_release (push) Has been cancelled
Obsidian Plugin Lint / lint (push) Has been cancelled
Build and Push Docker Images / build (./surfsense_web, cpu, ./surfsense_web/Dockerfile, web, surfsense-web, ubuntu-24.04-arm, linux/arm64, arm64, , runner, false, cpu) (push) Has been cancelled
Build and Push Docker Images / build (./surfsense_web, cpu, ./surfsense_web/Dockerfile, web, surfsense-web, ubuntu-latest, linux/amd64, amd64, , runner, false, cpu) (push) Has been cancelled
Build and Push Docker Images / compute_version (push) Has been cancelled
Build and Push Docker Images / build (./surfsense_backend, cpu, ./surfsense_backend/Dockerfile, backend, surfsense-backend, ubuntu-24.04-arm, linux/arm64, arm64, , production, false, cpu) (push) Has been cancelled
Build and Push Docker Images / build (./surfsense_backend, cpu, ./surfsense_backend/Dockerfile, backend, surfsense-backend, ubuntu-latest, linux/amd64, amd64, , production, false, cpu) (push) Has been cancelled
Build and Push Docker Images / build (./surfsense_backend, cu126, ./surfsense_backend/Dockerfile, backend, surfsense-backend, ubuntu-24.04-arm, linux/arm64, arm64, -cuda126, production, true, cuda126) (push) Has been cancelled
Build and Push Docker Images / build (./surfsense_backend, cu126, ./surfsense_backend/Dockerfile, backend, surfsense-backend, ubuntu-latest, linux/amd64, amd64, -cuda126, production, true, cuda126) (push) Has been cancelled
Build and Push Docker Images / build (./surfsense_backend, cu128, ./surfsense_backend/Dockerfile, backend, surfsense-backend, ubuntu-24.04-arm, linux/arm64, arm64, -cuda, production, true, cuda) (push) Has been cancelled
Build and Push Docker Images / build (./surfsense_backend, cu128, ./surfsense_backend/Dockerfile, backend, surfsense-backend, ubuntu-latest, linux/amd64, amd64, -cuda, production, true, cuda) (push) Has been cancelled
Build and Push Docker Images / verify_digests (push) Has been cancelled
Build and Push Docker Images / create_manifest (backend, surfsense-backend, , cpu) (push) Has been cancelled
Build and Push Docker Images / create_manifest (backend, surfsense-backend, -cuda, cuda) (push) Has been cancelled
Build and Push Docker Images / create_manifest (backend, surfsense-backend, -cuda126, cuda126) (push) Has been cancelled
63 lines
1.8 KiB
Plaintext
63 lines
1.8 KiB
Plaintext
---
|
|
title: Telegram
|
|
description: Enable SurfSense chat from Telegram
|
|
---
|
|
|
|
# Telegram Messaging Channel
|
|
|
|
Telegram lets users chat with the SurfSense agent from a Telegram bot. Users pair
|
|
their Telegram chat from **User Settings > Messaging Channels**.
|
|
|
|
## Environment Variables
|
|
|
|
For Docker installs, add these to `docker/.env`. For manual installs, add them to
|
|
`surfsense_backend/.env`.
|
|
|
|
```bash
|
|
TELEGRAM_SHARED_BOT_TOKEN=123456:bot-token-from-botfather
|
|
TELEGRAM_SHARED_BOT_USERNAME=your_bot_username
|
|
TELEGRAM_WEBHOOK_SECRET=generate-a-long-random-secret
|
|
GATEWAY_BASE_URL=https://api.example.com
|
|
GATEWAY_TELEGRAM_INTAKE_MODE=webhook
|
|
```
|
|
|
|
`TELEGRAM_WEBHOOK_SECRET` must be 1-256 characters and contain only `A-Z`, `a-z`,
|
|
`0-9`, `_`, or `-`.
|
|
|
|
## Intake Modes
|
|
|
|
| Mode | Use when |
|
|
| --- | --- |
|
|
| `webhook` | Production or any deployment with a public HTTPS backend URL |
|
|
| `longpoll` | Single-replica self-host installs that cannot expose a public HTTPS webhook |
|
|
| `disabled` | You do not want Telegram intake enabled |
|
|
|
|
For SaaS-style or multi-replica deployments, use `webhook`. Long polling should
|
|
only run in a single backend process.
|
|
|
|
## Webhook URL
|
|
|
|
Telegram webhooks use this shape:
|
|
|
|
```text
|
|
${GATEWAY_BASE_URL}/api/v1/gateway/webhooks/telegram/{account_id}
|
|
```
|
|
|
|
After deploying the backend, register the webhook:
|
|
|
|
```bash
|
|
cd surfsense_backend
|
|
uv run python scripts/register_webhook.py
|
|
```
|
|
|
|
If switching a bot from long polling to webhooks, delete any existing Telegram
|
|
webhook or pending `getUpdates` session before relying on the new mode.
|
|
|
|
## Pairing Flow
|
|
|
|
1. The user opens **User Settings > Messaging Channels**.
|
|
2. The user starts Telegram pairing.
|
|
3. SurfSense provides a pairing code or bot link.
|
|
4. The user sends the pairing command to the Telegram bot.
|
|
5. SurfSense binds that Telegram chat to the selected workspace.
|