Integrations

Telegram Integration

Support customers via Telegram bots

Create a Telegram bot to handle support requests. Customers message your bot, and Keva creates tickets and responds directly in the chat.

Prerequisites

  • A Telegram account
  • A bot created via BotFather

Setup

1. Create a Telegram Bot

  1. Open Telegram and message @BotFather
  2. Send /newbot and follow the prompts
  3. Note your Bot Token (format: 123456789:ABCdefGHI...)

2. Connect to Keva

Go to Settings > Integrations > Telegram and enter:

  • Bot Token: From BotFather
  • Webhook Secret: A random string you choose

3. Set Up Webhook

curl -X POST "https://api.telegram.org/bot<TOKEN>/setWebhook" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://app.keva.support/api/webhooks/telegram?bot_id=<CONNECTOR_ID>",
    "secret_token": "<YOUR_SECRET>"
  }'

4. Subscribe to Chats

Go to Settings > Channels, click Add Telegram Bot, and configure:

  • Private chats: Use * as channel ID for all private messages
  • Group chats: Use the specific group chat ID

Configuration Options

Create Ticket On

SettingBehavior
New threadNew messages in private chats; non-replies in groups
Any messageEvery message creates or updates a ticket
MentionOnly when bot is @mentioned (best for groups)

Routing

  • Workspace: Route to a specific workspace
  • Default Priority: Set initial priority
  • Auto-assign: Assign to AI or specific agent

Chat Types

TypeDescription
private1-on-1 with bot (primary support channel)
groupGroup chat with bot
supergroupLarge group with admin features

How It Works

  1. Customer messages your bot
  2. Telegram sends update to webhook
  3. Secret token header validated
  4. Keva creates ticket from message
  5. AI processes and drafts response
  6. Reply sent via Telegram Bot API
  7. Customer sees response in same chat

Conversation Threading

Conversations threaded by Telegram chat ID:

  • Private chats: One thread per user
  • Groups: One thread per group
  • Closed tickets: New messages create new tickets

Customer Identification

Telegram provides:

  • User ID: Unique numeric ID
  • Username: @username (if set)
  • First/Last Name: Display name

Email generated as {user_id}@telegram.keva.local.

Getting Group Chat ID

  1. Add bot to the group
  2. Send a message in the group
  3. Check webhook payload for chat.id

Or use: curl "https://api.telegram.org/bot<TOKEN>/getUpdates"

Group IDs are negative (e.g., -1001234567890).

Troubleshooting

Webhook not receiving: Verify with getWebhookInfo, check HTTPS URL, confirm bot_id parameter.

Secret token failing: Check header X-Telegram-Bot-Api-Secret-Token, re-register webhook if needed.

Bot not responding: Test with getMe API, verify subscription active, check ticket created.

Group messages ignored: Verify group chat ID, check "Create Ticket On" setting, ensure bot has read permission.

Security

  • Secret token header validation
  • Timing-safe token comparison
  • Bot tokens encrypted at rest
  • Bot messages automatically filtered
  • All updates logged in audit trail