Skip to main content
connic

Telegram Personal Assistant

Multimodal Telegram assistant that processes text, images, voice, video, and documents. Searches the web, saves notes and knowledge, and schedules follow-up reminders with persistent sessions.

Talk to Sales
Install with the CLI
connic init my-project --templates=telegram-personal-assistant
Difficulty
Beginner
Works with
Telegram
Source
GitHub
Publisher
By connic

What the template does

A multimodal personal assistant living inside Telegram that handles text, images, voice memos, audio, video, and documents. Middleware injects the current UTC time into each message for schedule calculations and routes replies back via chat ID. Persistent sessions keyed by chat ID maintain conversation history across messages. The agent searches the web for real-time information, reads full pages, saves and retrieves quick notes via the database, stores longer-form knowledge for semantic retrieval, and schedules follow-up reminders using trigger_agent_at with relative delays up to 7 days. Replies are formatted with Telegram HTML tags and sent via the outbound connector.

Architecture
Telegram (inbound)
telegram-assistant
Persistent Session
Web Search
Notes Database
Retrieval
Scheduled Trigger
Telegram (outbound)
Personal assistant with reminders
A chatbot that retains preferences, saves notes, answers questions with web search, and schedules follow-up reminders up to 7 days ahead.
Team knowledge bot
Deploy in a group chat to collect and recall team knowledge, meeting notes, and reference material across conversations.
Research companion
Search the web, read full pages, store findings in the retrieval, and retrieve them later with natural language queries.

Every file lands in your project

connic init copies these files into your codebase, where you change them like the rest of your code.

agents/telegram-personal-assistant/telegram-assistant.yaml

LLM agent with its model, prompt and tools.

version: "1.0"

name: telegram-assistant
type: llm
model: connic/gpt-5.6-terra
description: "A Telegram personal assistant for text, images, and documents with persistent memory"

system_prompt: |
  You are a personal assistant living inside Telegram. Your goal is to be as
  helpful as possible and answer every question to the best of your ability.

  ## Multimodal Input

  Users can send text, images, and supported documents. Process them naturally:

  - **Text messages**: Answer questions, have conversations, help with tasks.
  - **Images / Photos**: Describe what you see, read text in images (OCR),
    analyze charts, identify objects, answer questions about the image.
  - **Documents / Files**: Read PDFs, spreadsheets, code files, etc. Summarize
    content, answer questions about it, or extract specific information.

  When you receive media without accompanying text, proactively describe or
  analyze the content and ask how you can help with it. When media comes with
  a caption or follow-up text, use that as the primary question/instruction
  about the media.

  ## Capabilities

  - **Web search**: Look up anything on the internet. Use it for current events,
    facts, prices, documentation, weather, how-to guides, etc. Always search
    when the user asks about something that may require up-to-date information.
  - **Notes**: Save and retrieve personal notes. The user might say "remember
    that my dentist appointment is on Thursday" or "what did I save about the
    project?" Save immediately when asked, confirm briefly.
  - **Retrieval**: Store and query longer-form information like articles,
    meeting summaries, or reference material the user wants to keep.
  - **Scheduled follow-ups**: You can schedule yourself to come back later
    using schedule_followup. Use it when the user says things like "remind me
    in 2 hours", "check on X tomorrow", or "follow up on this later".
    Convert time expressions to a delay dict with keys d (days), h (hours),
    m (minutes), s (seconds). Maximum: 7 days ahead.
    The current time is injected at the start of your input. Use it to
    calculate the correct relative delay from now to the target time.
    Example: if it is 14:00 UTC and the user says "tomorrow at 8 AM UTC",
    the delay is {{"h": 18}} (18 hours from now), NOT {{"d": 1, "h": 8}}.
  - **Scheduled delivery**: When your input payload contains a "message" field
    (from a previously scheduled follow-up), deliver that message to the user
    naturally. You are picking up a task your past self scheduled.

  ## Behavioral Rules

  1. Always try your best to answer. If you are unsure, say so but still give
     your best attempt. Use web search to fill knowledge gaps.
  2. Keep replies concise for chat (1-4 sentences) unless the user asks for
     detail or the question genuinely requires a longer answer.
  3. When the user asks you to remember, save, or note something, you must call
     save_note before replying, then confirm briefly. Never tell the user you
     saved it unless you actually called save_note in this turn.
  4. When the user asks "what do I have saved about X?", search both notes
     (find_notes) and Retrieval (search_knowledge).
  5. For web searches, summarize the findings clearly. Do not dump raw results.
  6. When storing knowledge, pick a descriptive entry_id so it can be updated later.
  7. Never include JSON, chat_id, or any technical wrapper in your replies.
  8. Match the user's language. If they write in German, reply in German. If
     English, reply in English.

  ## Telegram Formatting (HTML only)

  - <b>bold</b> for emphasis
  - <i>italic</i> for light emphasis
  - <code>inline code</code> for technical terms
  - <pre>code blocks</pre> for multi-line code

  Do not use markdown formatting (asterisks, underscores). Only use the HTML
  tags listed above.

temperature: 0.2
max_iterations: 15
timeout: 120

session:
  key: context.telegram_chat_id

# Chats run for months; compact old session history instead of hitting context limits.
context_compression:
  enabled: true
  keep_recent_messages: 10
  session_history:
    interval: 8
    keep_recent_runs: 2

tools:
  - web_search
  - web_read_page
  - assistant_tools.save_note
  - assistant_tools.find_notes
  - assistant_tools.delete_note
  - assistant_tools.search_knowledge
  - assistant_tools.remember_knowledge
  - assistant_tools.schedule_followup
tools/assistant_tools.py

Functions the agents call as tools.

"""Personal assistant tools - notes via database, knowledge via RAG."""

from connic.tools import db_insert, db_find, db_delete, retrieval_query, retrieval_store, trigger_agent_at

NOTES_COLLECTION = "notes"
KNOWLEDGE_NAMESPACE = "personal"


async def save_note(title: str, content: str) -> dict:
    """Save a personal note. Use for quick facts, reminders, and things the user wants to remember.

    Args:
        title: Short label for the note (e.g. "dentist appointment", "wifi password").
        content: The note body. Include all relevant details.

    Returns:
        The saved note document.
    """
    result = await db_insert(NOTES_COLLECTION, {
        "title": title,
        "content": content,
    })
    return result["inserted"][0]


async def find_notes(query: str = "") -> list[dict]:
    """Search saved notes. Returns up to 20 matching notes ordered by most recent.

    Args:
        query: Search term to filter by title. Leave empty to list all recent notes.

    Returns:
        List of matching note documents.
    """
    filter_dict = {}
    if query.strip():
        filter_dict = {"title": {"$regex": query}}

    result = await db_find(
        NOTES_COLLECTION,
        filter=filter_dict,
        sort={"_created_at": -1},
        limit=20,
    )
    return result.get("documents", [])


async def delete_note(note_id: str) -> dict:
    """Delete a note by its ID.

    Args:
        note_id: The _id of the note to delete (from find_notes results).

    Returns:
        Deletion result.
    """
    return await db_delete(NOTES_COLLECTION, filter={"_id": note_id})


async def search_knowledge(query: str) -> list[dict]:
    """Search personal Retrieval for longer-form stored information.

    Use this for articles, meeting summaries, reference material, or anything
    the user stored with remember_knowledge.

    Args:
        query: Describe what you're looking for (e.g. "meeting notes from last week").

    Returns:
        List of matching knowledge entries with content and relevance score.
    """
    result = await retrieval_query(query, namespace=KNOWLEDGE_NAMESPACE, max_results=5)
    return result.get("results", [])


async def remember_knowledge(content: str, entry_id: str | None = None) -> dict:
    """Store information in personal Retrieval for later retrieval.

    Best for longer content like summaries, articles, how-tos, or reference
    material. For short facts and reminders, use save_note instead.

    Args:
        content: The information to store. Be descriptive so it can be found later.
        entry_id: Optional stable ID for updates (e.g. "project-roadmap"). If an
                  entry with this ID exists, it will be replaced.

    Returns:
        Store result with entry_id.
    """
    return await retrieval_store(
        content, namespace=KNOWLEDGE_NAMESPACE, entry_id=entry_id
    )


AGENT_NAME = "telegram-assistant"


async def schedule_followup(task: str, delay: dict, context: dict) -> dict:
    """Schedule the assistant to follow up later with a reminder or task.

    Use when the user asks to be reminded about something, or wants you to
    check/do something at a later time (e.g. "remind me in 2 hours",
    "check the weather tomorrow morning").

    Args:
        task: What you should do when the scheduled time arrives. Be specific
              so your future self knows exactly what to tell the user.
        delay: When to follow up, as a relative offset from now. Dict with keys
               d (days), h (hours), m (minutes), s (seconds). At least one required.
               Calculate from the current time provided in your input.

    Returns:
        Confirmation with the scheduled time.
    """
    chat_id = context["telegram_chat_id"]

    result = await trigger_agent_at(
        agent_name=AGENT_NAME,
        payload={"chat_id": chat_id, "message": task},
        delay=delay,
    )

    return {
        "scheduled": True,
        "scheduled_at": result.get("scheduled_at"),
        "task": task,
    }
middleware/telegram-assistant.py

Runs before and after the agent with the same name.

"""Middleware for telegram-assistant.

Before:
  Puts the chat_id from the connector payload into context so the session
  key (context.telegram_chat_id) resolves correctly.
  Injects the current UTC time so the agent can calculate relative delays.

After:
  Wraps the agent reply in {"chat_id": ..., "text": "..."} for the outbound
  Telegram connector.
"""
import json
from datetime import datetime, timezone
from typing import Any


async def before(content: dict[str, Any], context: dict[str, Any]) -> dict[str, Any]:
    payload = context.get("payload") or {}
    chat_id = payload.get("chat_id") if isinstance(payload, dict) else None
    context["telegram_chat_id"] = chat_id

    now = datetime.now(timezone.utc)
    time_part = {"text": f"[Current time: {now.strftime('%Y-%m-%d %H:%M UTC (%A)')}]"}
    content["parts"].insert(0, time_part)

    return content


async def after(response: str, context: dict[str, Any]) -> str:
    chat_id = context.get("telegram_chat_id")
    return json.dumps({"chat_id": chat_id, "text": response.strip()})
tests/telegram-assistant.yaml

5 test cases for connic test.

version: "1.0"

# The six assistant_tools are mocked so no database, Retrieval data, or
# scheduled trigger is touched. web_search and web_read_page are predefined and
# run for real, so strict_mocks is omitted. Each payload carries the top-level
# chat_id the before() middleware extracts into the session key; the after()
# middleware wraps the reply as {"chat_id": ..., "text": ...}, so cases assert on
# the wrapped output structure only.
defaults:
  runs: 1
  timeout_s: 120
  mocks: assistant_mocks

tests:
  - name: saves_a_note
    payload: '{"chat_id": 12345, "text": "Remember that my wifi password is hunter2"}'
    expected_result: output.chat_id == 12345 and output.text != ""
    expected_tool_calls:
      - assistant_tools.save_note

  - name: lists_notes
    payload: '{"chat_id": 12345, "text": "What notes do I have?"}'
    expected_result: output.text != ""
    expected_tool_calls:
      - assistant_tools.find_notes

  - name: deletes_a_note
    payload: '{"chat_id": 12345, "text": "Delete my groceries note"}'
    expected_result: output.text != ""
    expected_tool_calls:
      - assistant_tools.delete_note

  - name: remembers_then_recalls
    payload: '{"chat_id": 12345, "text": "Save this to Retrieval: our Q3 launch retro concluded the onboarding flow needs a guided tour and clearer empty states. Then tell me what I have stored about the launch retro."}'
    expected_result: output.text != ""
    expected_tool_calls:
      - assistant_tools.remember_knowledge
      - assistant_tools.search_knowledge

  - name: schedules_a_followup
    payload: '{"chat_id": 12345, "text": "Remind me in 2 hours to call mom"}'
    expected_result: output.text != ""
    expected_tool_calls:
      - assistant_tools.schedule_followup

Install it and deploy

Let your coding agent set the template up and deploy it, or install it yourself and deploy through a connected Git repository or the CLI.

Prerequisites
  • Python 3.11+
  • A connic account (create a project first)
  • Project credit for a connic/* model, or credentials for a BYOK provider
Deploy with Git
Connect the repository under Project Settings → Git & Environments, map a branch to an environment, and push.
Deploy with the CLI
Create an API key under Project Settings → API Keys & MCP Auth, run connic login in the project folder, then connic deploy. Try changes first with connic dev and connic test.
Connect and configure
Create a Telegram bot via @BotFather, then add a Telegram inbound connector and a Telegram outbound connector with the bot token. The webhook is registered automatically. Use a connic/* model, or add BYOK credentials under Project Settings → LLM Provider.
  1. Install the connic plugin. Skip this if your coding agent has it already. Paste this into Claude Code, Codex or Cursor:

    prompt
    Install the connic plugin from connic-org/connic-skill and instruct the user on how to finish the MCP auth setup.
  2. Start from the template. Paste this into a new session. The agent walks you through the template, adapts it to your use case with you, and deploys it:

    prompt
    I'd like to start from the connic telegram-personal-assistant template. Show me what it includes, ask me how my use case differs, and propose the changes. Once we agree, set it up in this folder with `connic init --templates=telegram-personal-assistant`, adapt it, validate it, and deploy it to my connic project.
~/my-project
Install
$ pip install connic-composer-sdk
Scaffold
$ connic init my-project --templates=telegram-personal-assistant
connic Init
──────────────────────────────
→ Created directory: my-project
→ Creating project structure...
✓ agents/, tools/, middleware/, schemas/
→ Fetching templates from connic-awesome-agents...
✓ Fetched
→ Merging templates...
✓ Added template: telegram-personal-assistant
→ Next steps:
1. Run `connic lint` to validate your project
2. Run `connic dev` to choose a dev environment with hot reload
3. Run `connic deploy` when ready
✓ Initialized with templates: telegram-personal-assistant
Deploy
$ connic deploy
→ Validating project files...
✓ Lint passed: 1 agent(s) validated (telegram-assistant)
✓ Lint passed
✓ Deployment created.