Telegram Bot

The Aya Telegram Bot integrates Telegram with your Aya profile, enabling account linking, group invitations, and notification delivery.

Overview

Telegram Bot features:

Link Telegram account to Aya profile
Join community Telegram groups via membership
Receive bulletin digests in Telegram
Get mailbox notifications
Webhook and polling modes for deployment flexibility

The bot operates in two modes: webhook (production, real-time) and polling (development, pull-based).

Bot Setup

Finding the Bot

Search for @AyaBot on Telegram or use the direct link:

https://t.me/AyaBot

Linking Your Account

Start conversation with bot

Send /start command to @AyaBot

Bot responds with link code

Bot generates a unique 6-digit code valid for 5 minutes

Your verification code is: ABC123
Enter this code on Aya to link your account.
https://aya.is/settings/integrations

Enter code on Aya

Navigate to Settings → Integrations → TelegramEnter the 6-digit code

Account linked

Profile link created with verified badge
Telegram username becomes public ID
Link appears on your profile (if visibility allows)
Bot can now send you notifications

Linking is required for receiving bulletin digests via Telegram and joining community groups.

External Code System

Linking uses temporary external codes:

{
  "code": "ABC123",
  "external_system": "telegram",
  "properties": {
    "telegram_user_id": 123456789,
    "telegram_username": "alice"
  },
  "created_at": "2025-03-01T10:00:00Z",
  "expires_at": "2025-03-01T10:05:00Z",
  "consumed_at": null
}

Security Features:

Codes expire after 5 minutes
One-time use (consumed_at set on redemption)
Random 6-character alphanumeric
Stored with Telegram user metadata

Never share your verification code. It grants access to link your Telegram account to your Aya profile.

Profile Link Details

Linked Telegram appears on profile:

{
  "kind": "telegram",
  "remote_id": "123456789",
  "public_id": "alice",
  "uri": "https://t.me/alice",
  "is_verified": true,
  "is_managed": true,
  "visibility": "public",
  "title": "Telegram",
  "icon": "telegram"
}

Link Properties:

remote_id: Telegram user ID (used for bot messaging)
public_id: Telegram username (displayed publicly)
is_verified: Always true (verified via bot linking)
is_managed: True (system manages this link)

Community Group Integration

Setting Up Group for Community

Community/organization admins can link Telegram groups:

Create Telegram group

Create a new Telegram group for your community

Add @AyaBot as admin

Invite bot and promote to admin with permissions:

Invite users via link
Manage chat

Generate registration code

Use bot command:

/register [profile-slug]

Bot responds with 8-character code valid for 10 minutes

Navigate to community settings → Integrations → Telegram GroupsEnter registration code

Configure access control

Set minimum membership level required to join group:

Follower, Member, Contributor, Maintainer, Lead

Group linked

Telegram group resource created
Appears in community resources
Members with appropriate level receive invites

Group Registration Code

{
  "code": "XYZ78901",
  "external_system": "telegram",
  "properties": {
    "chat_id": -1001234567890,
    "chat_title": "Aya Dev Community"
  },
  "expires_at": "2025-03-01T10:10:00Z"
}

Member Invitations

When a user gains appropriate membership level:

Membership created/updated

User promoted to level that grants Telegram access

System checks eligibility

User has linked Telegram account
User’s membership level meets group requirement
User is member of appropriate teams (if team-restricted)

Invitation created

Bot generates unique invite link
Invitation envelope sent to user’s mailbox
Properties include group info and invite link

User receives invitation

Mailbox notification with:

Group name and description
Profile context
One-click join link

User accepts

Clicks invite link
Telegram opens with group preview
User joins group
Invitation marked accepted

Invitations are sent automatically. Users don’t need to request access - they receive invites when eligible.

Telegram Profile Link Visibility

Control who sees your Telegram link:

Public

Everyone sees your username

Followers

Only followers and above

Members

Only members of your communities

Use Cases:

Public: Open to DMs from anyone
Followers: Limit to engaged audience
Members: Private, community-only contact

Set link visibility when creating the link or update it in profile link settings.

Bot Commands

User Commands

/start Initiate bot conversation and get linking code

/start

Response:

Welcome to Aya Bot!

Your verification code is: ABC123

Enter this code on Aya to link your Telegram account:
https://aya.is/settings/integrations

Code expires in 5 minutes.

/link Get a new linking code (if previous expired)

/link

/status Check your linking status

/status

Response:

✅ Account linked
Profile: @alice (Alice Smith)
Linked: March 1, 2025

/unlink Unlink your Telegram account from Aya

/unlink

Unlinking removes your Telegram profile link and stops all Telegram notifications.

Admin Commands

/register [profile-slug] (Admin-only, used in groups) Generate registration code to link group to Aya profile

/register dev-community

Response:

Registration code for dev-community: XYZ78901

Enter this code on Aya to register this group:
https://aya.is/en/dev-community/settings/integrations

Code expires in 10 minutes.

Notification Delivery

Bulletin Digests

Receive content digests via Telegram:

Subscribe to profiles with Telegram channel
Choose frequency (daily, bi-daily, weekly)
Digests formatted with Markdown
Direct links to stories
Grouped by followed profile

See Bulletin Board for subscription setup. Example Digest:

📨 Your Weekly Digest - March 1, 2025

🏢 Acme Corp

• Product Launch - March 15
  "Announcing our revolutionary new product..."
  by Jane Doe
  🔗 Read more: https://aya.is/en/acme-corp/stories/...

• Q4 2024 Results
  "Record growth in all sectors..."
  by John Smith
  🔗 Read more: https://aya.is/en/acme-corp/stories/...

👥 Tech Community

• Monthly Meetup - March 10
  "Join us for talks on AI and machine learning"
  by Community Team
  🔗 Read more: https://aya.is/en/tech-community/stories/...

Mailbox Notifications

Receive mailbox alerts:

New message notifications
Invitation alerts
Real-time delivery (webhook mode)
Customizable notification settings

Example Notification:

📨 New message from Bob Jones

"Hey Alice, would love to collaborate on the new project!"

👉 Reply: https://aya.is/mailbox/conv123

Deployment Modes

Webhook Mode (Production)

How it works:

Telegram sends updates to configured webhook URL
Aya server receives and processes immediately
Real-time responses sent back to Telegram

Configuration:

TELEGRAM__BOT_TOKEN=your_bot_token_from_botfather
TELEGRAM__WEBHOOK_MODE=true
TELEGRAM__WEBHOOK_URL=https://api.aya.is/telegram/webhook
TELEGRAM__WEBHOOK_SECRET=random_secret_for_verification

Advantages:

Real-time message delivery
Lower latency
Efficient (no polling overhead)
Scales better

Polling Mode (Development)

How it works:

Aya server periodically asks Telegram for updates
Processes any new messages
Responds to Telegram API

Configuration:

TELEGRAM__BOT_TOKEN=your_bot_token_from_botfather
TELEGRAM__WEBHOOK_MODE=false
TELEGRAM__POLL_INTERVAL=2s

Advantages:

Simpler setup (no public URL needed)
Good for development
Works behind firewalls

Use webhook mode in production for best performance. Use polling mode for local development.

Privacy & Security

Data Stored

Aya stores minimal Telegram data:

Telegram user ID (for messaging)
Telegram username (for profile display)
Link creation timestamp
No message content stored

Bot Permissions

Bot requires:

Read messages (to process commands)
Send messages (to send notifications)
Invite users (for group management)

Bot cannot read messages in groups unless mentioned. It only processes direct commands.

Security Best Practices

For Users

Verify you’re messaging @AyaBot (check verified badge)
Don’t share verification codes
Unlink account if compromised
Review linked accounts regularly

For Community Admins

Only add bot to official community groups
Revoke bot admin if group is disbanded
Monitor group registrations
Document group purpose in resource description

Troubleshooting

Cannot link account

Ensure you’ve started conversation with @AyaBot
Check verification code hasn’t expired (5 min)
Verify code is entered correctly (case-sensitive)
Try generating new code with /link
Check you have Aya individual profile

Not receiving notifications

Verify account is linked (/status command)
Check you haven’t blocked @AyaBot
Ensure Telegram privacy settings allow bot messages
Review subscription settings on Aya
Check bot service status

Group registration fails

Verify bot is admin in group
Check registration code hasn’t expired (10 min)
Ensure you’re owner/lead of Aya profile
Try generating new code
Check group type (must be group, not channel)

Cannot join group

Verify you have appropriate membership level
Check your Telegram account is linked
Look for invitation in mailbox
Ensure invitation hasn’t expired
Contact community admins

API Integration

Developers can integrate Telegram features:

Link Telegram Account

curl -X POST https://api.aya.is/telegram/link \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "profile_id": "my-profile-id",
    "verification_code": "ABC123"
  }'

Send Telegram Notification

curl -X POST https://api.aya.is/telegram/notify \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "profile_id": "recipient-profile-id",
    "message": "Hello from API!"
  }'

Rate Limits

Linking

5 codes per hour per user

Commands

10 commands per minute per user

Notifications

100 notifications per hour per profile

Group Registration

3 registrations per hour per group

Exceeding rate limits results in temporary cooldown. Bot will notify you of cooldown period.

Best Practices

For Personal Use

Link account to receive digests
Set appropriate link visibility
Enable notifications for important communities
Use /status to verify linking periodically
Unlink if changing Telegram account

For Community Admins

Create dedicated group for community
Set clear group rules and description
Use membership levels to control access
Monitor group activity
Document group purpose in Aya resources
Consider multiple groups for sub-communities

For Developers

Use webhook mode in production
Implement webhook signature verification
Handle rate limits gracefully
Log bot interactions for debugging
Test in polling mode locally

Roadmap

Planned features:

Next Steps

Bulletin Board

Configure Telegram digests

Mailbox

Receive invitations via Telegram

Communities

Set up community Telegram groups

Profiles

Manage Telegram link visibility

User Features

Community Features

Integrations

​Overview

​Bot Setup

​Finding the Bot

​Linking Your Account

​External Code System

​Profile Link Details

​Community Group Integration

​Setting Up Group for Community

​Group Registration Code

​Member Invitations

​Telegram Profile Link Visibility

Public

Followers

Members

​Bot Commands

​User Commands

​Admin Commands

​Notification Delivery

​Bulletin Digests

​Mailbox Notifications

​Deployment Modes

​Webhook Mode (Production)

​Polling Mode (Development)

​Privacy & Security

​Data Stored

​Bot Permissions

​Security Best Practices

​Troubleshooting

​API Integration

​Link Telegram Account

​Send Telegram Notification

​Rate Limits

Linking

Commands

Notifications

Group Registration

​Best Practices

​Roadmap

​Next Steps

Bulletin Board

Mailbox

Communities

Profiles

Build docs developers (and LLMs) love

Overview

Bot Setup

Finding the Bot

Linking Your Account

External Code System

Profile Link Details

Community Group Integration

Setting Up Group for Community

Group Registration Code

Member Invitations

Telegram Profile Link Visibility

Bot Commands

User Commands

Admin Commands

Notification Delivery

Bulletin Digests

Mailbox Notifications

Deployment Modes

Webhook Mode (Production)

Polling Mode (Development)

Privacy & Security

Data Stored

Bot Permissions

Security Best Practices

Troubleshooting

API Integration

Link Telegram Account

Send Telegram Notification

Rate Limits

Best Practices

Roadmap

Next Steps