Telegram & Slack Setup

TaskView messaging integrations deliver task events to messengers. There are two levels of connection:

• Personal — a user links their own account and receives direct messages about their tasks (assigned, deadline, etc.).
• Project — an admin connects a group/channel, and events for that project are posted to it for the whole team.

The bot credentials are configured per instance (via environment variables), so the official TaskView SaaS ships an official bot and self-hosted installs supply their own — no code changes, only configuration.

Prerequisites

• TaskView API running and reachable over public HTTPS (messengers deliver updates/redirects to your API; localhost is not reachable from Telegram/Slack — use your production domain or a tunnel for local testing)
• PostgreSQL database with migrations applied
• .env.taskview file configured

Local testing tunnel: prefer cloudflared tunnel --url http://localhost:1401 — it gives a clean HTTPS URL with no interstitial. ngrok's free tier shows a "You are about to visit…" warning page that breaks the browser OAuth redirect (you can't inject the ngrok-skip-browser-warning header into Slack's redirect); if you must use ngrok free, open the tunnel URL once in your browser and click Visit Site first, or upgrade to a paid plan.

For Slack, the API base the frontend calls and SLACK_CALLBACK_URL must be the same HTTPS origin — the anti-CSRF nonce cookie is set on oauth/start and read on the callback, so a localhost start + tunnel callback will not work.

1. Database Migration

The migration creates the required tables (tasks.messaging_connections, tasks.messaging_link_tokens, tasks.messaging_identity_map) automatically. The migration container handles this on startup — no manual steps needed.

2. Telegram

2.1 Create a bot

1. Open @BotFather in Telegram
2. Send /newbot and follow the prompts
3. Copy the bot token (looks like 123456789:AA...) and note the bot username (without @)

2.2 Configure the bot for group commands

Project connections are completed by typing a command inside a group, so the bot must be allowed to read group messages:

1. In @BotFather, send /setprivacy → choose your bot → Disable (with privacy enabled, members must instead address the bot explicitly: /connect@your_bot <token>)
2. Send /setjoingroups → choose your bot → Enable

2.3 Environment variables

Add to .env.taskview:

TELEGRAM_BOT_TOKEN=123456789:AA-your-bot-token
TELEGRAM_BOT_USERNAME=your_bot            # without the leading @
TELEGRAM_WEBHOOK_SECRET=<random-secret>   # any long random string

Generate a webhook secret:

node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

The webhook secret is compared (in constant time) against the X-Telegram-Bot-Api-Secret-Token header on every inbound update, so only Telegram can reach the endpoint.

2.4 Register the webhook with Telegram

Tell Telegram where to deliver updates. Run once (replace the placeholders):

curl "https://api.telegram.org/bot<TELEGRAM_BOT_TOKEN>/setWebhook" \
  -d "url=https://<your-api-domain>/module/messaging/telegram/webhook" \
  -d "secret_token=<TELEGRAM_WEBHOOK_SECRET>"

Verify it took effect:

curl "https://api.telegram.org/bot<TELEGRAM_BOT_TOKEN>/getWebhookInfo"

url should point at your /module/messaging/telegram/webhook and pending_update_count should be 0.

2.5 Usage

Restart the API after setting the environment variables, then in TaskView open a project → right-click it in the sidebar → "Messengers".

Personal (Direct messages)

1. On the Personal tab, click Connect → Telegram → Get link
2. Click Open in Telegram and press Start in the bot chat
3. Your account is linked — you'll now get DMs about your tasks

Project (Group channel)

1. On the Project tab (requires the INTEGRATIONS_CAN_MANAGE permission), click Connect → Telegram → Get link
2. Click Add bot to group and pick the group, or add the bot manually
3. In that group, send the shown command: /connect <token>
4. The group is connected — project events are now posted there

You can toggle any connection on/off or disconnect it from the same page.

3. Slack

Slack uses per-instance OAuth credentials, mirroring the GitHub/GitLab integration model. Requires ENCRYPTION_KEY (tokens are stored AES-256-GCM encrypted).

3.1 Create and configure the Slack app

1. Create the app — go to api.slack.com/apps → Create New App → From scratch, give it a name and pick your workspace.
2. OAuth & Permissions → Redirect URLs — click Add New Redirect URL, enter exactly your SLACK_CALLBACK_URL, then Save URLs:

   https://<your-api-domain>/module/messaging/slack/oauth/callback
   

   
   Slack requires HTTPS — a plain http://localhost URL is rejected. Use your production domain or an HTTPS tunnel (see Prerequisites).
3. OAuth & Permissions → Scopes → Bot Token Scopes — add:
   • chat:write — required for personal direct messages
   • (only if personal DMs fail to open) im:write
4. Features → Incoming Webhooks → Activate Incoming Webhooks (On) — required for the project (channel) flow. This enables the incoming-webhook scope so that, during a project connect, Slack shows a channel picker and returns a webhook URL. Without it, project connections fail.
5. Basic Information → App Credentials — copy Client ID, Client Secret, and Signing Secret for the environment variables below.

You do NOT need Slash Commands, Event Subscriptions, or Interactivity — TaskView Slack is outbound-only for now.

If you change scopes after installing, reinstall the app (OAuth & Permissions → Reinstall to Workspace) so the new scopes take effect.

By default a Slack app is private to your workspace — only you can use it. It becomes available to other workspaces only if you enable Public Distribution (and, for the Marketplace, pass Slack's review). Self-hosted installs keep it private; the official SaaS uses one distributed app.

3.2 Environment variables

SLACK_CLIENT_ID=<your-client-id>
SLACK_CLIENT_SECRET=<your-client-secret>
SLACK_CALLBACK_URL=https://<your-api-domain>/module/messaging/slack/oauth/callback
SLACK_SIGNING_SECRET=<your-signing-secret>

SLACK_CALLBACK_URL must exactly match the Redirect URL configured in the Slack app.

3.3 Usage

Restart the API, then open Messengers in a project:

• Personal: Personal tab → Connect → Slack → Continue with Slack → authorize. The app then DMs you about your tasks.
• Project: Project tab (requires INTEGRATIONS_CAN_MANAGE) → Connect → Slack → Continue with Slack → pick the channel to post to during install. Project events are posted to that channel via an incoming webhook.

The official SaaS ships a distributed Slack app; self-hosted installs create their own app and supply these values. Per-workspace tokens (and the project incoming-webhook URL) are stored encrypted with ENCRYPTION_KEY.

4. Full .env.taskview Example

# ... existing vars ...

# Telegram messaging integration
TELEGRAM_BOT_TOKEN=123456789:AA-your-bot-token
TELEGRAM_BOT_USERNAME=your_bot
TELEGRAM_WEBHOOK_SECRET=a1b2c3d4e5f6...

# Slack messaging integration
SLACK_CLIENT_ID=
SLACK_CLIENT_SECRET=
SLACK_CALLBACK_URL=https://api.taskview.tech/module/messaging/slack/oauth/callback
SLACK_SIGNING_SECRET=

# Required for Slack (encrypted token storage), shared with SSO/other integrations
ENCRYPTION_KEY=a1b2c3d4e5f6...  # 64 hex characters

5. SaaS vs Self-Hosted

There is no code fork between the two — only the values of the environment variables differ. If the variables are unset, the integration simply does not appear until an admin configures it.

6. Production Notes

• Public HTTPS is mandatory for the inbound webhook. Update the setWebhook URL to your production domain.
• Re-run setWebhook whenever the API domain changes.
• TELEGRAM_WEBHOOK_SECRET: store securely, never commit to git.
• Group privacy: if /connect in a group does nothing, the bot's privacy mode is likely still enabled (see step 2.2).

7. Troubleshooting

The "Messengers" page shows a 503 / "This messenger is not configured on the server" → TELEGRAM_BOT_TOKEN or TELEGRAM_BOT_USERNAME is missing; the API was not restarted after setting them.

Pressing Start / sending /connect does nothing → The webhook is not registered or points at the wrong URL. Check getWebhookInfo (step 2.4) and confirm the API is reachable over public HTTPS.

/connect <token> in a group is ignored → The bot's privacy mode is enabled. Disable it (step 2.2), or use /connect@your_bot <token>.

"Link is invalid or expired" → Binding tokens are single-use and expire after 15 minutes. Generate a new one from the Connect dialog.

Notifications don't arrive after connecting → Confirm the connection is toggled on, and that you are actually assigned to the task. Project posts require an active project connection.