Checklists

Bot API 9.1 — July 2025

A checklist is a to-do list that lives inside a message. Everyone in the chat sees the same list, and — if the author allows it — everyone can tick items off or add their own. The message updates in place for all of them.

---

Sending one

A checklist is sent with send_checklist() and built from InputChecklist and InputChecklistTask:

from pyrogram.types import InputChecklist, InputChecklistTask

await app.send_checklist(
    chat_id="me",
    checklist=InputChecklist(
        title="Release 4.0",
        tasks=[
            InputChecklistTask(id=1, text="Bump the layer"),
            InputChecklistTask(id=2, text="Regenerate the docs"),
            InputChecklistTask(id=3, text="Tag and publish"),
        ],
        others_can_add_tasks=True,
        others_can_mark_tasks_as_done=True,
    ),
)

Task ids are yours to assign and must be unique within the checklist. They are how you refer to a task later, so keep them stable — reusing an id for different text is what makes a checklist edit look like a rewrite to everyone watching.

Ticking items off

await app.mark_checklist_tasks_as_done(
    chat_id="me",
    message_id=message_id,
    marked_as_done_task_ids=[1, 2],
    marked_as_not_done_task_ids=[3],
)

Both lists are keyword-only and either may be omitted. The method returns the message id of the service message Telegram posts about the change.

Adding and editing

add_checklist_tasks() appends without touching the rest:

await app.add_checklist_tasks(
    chat_id="me",
    message_id=message_id,
    tasks=[InputChecklistTask(id=4, text="Announce it")],
)

edit_message_checklist() replaces the whole checklist — title, tasks, permissions — with a new InputChecklist. Use it to rename or remove tasks; use add_checklist_tasks when you only want to append.

Reading one back

message.checklist holds a Checklist:

checklist = message.checklist

for task in checklist.tasks:
    done = "x" if task.completion_date else " "
    print(f"[{done}] {task.id} {task.text}")
    if task.completed_by:
        print(f"      by {task.completed_by.first_name}")

Note the two pairs of permission flags. others_can_add_tasks is what the author set; can_add_tasks is whether you may, which also accounts for who you are in that chat. Read the can_* pair before offering a button that would fail.

Gotchas

• add_checklist_tasks() and mark_checklist_tasks_as_done() are user-session methods. A bot can send and edit a checklist, but ticking items is something people do.

• A task has no boolean “done” field. Completion is completion_date being set, with completed_by naming who did it.

• Checklists cannot be mixed with media. The message is a checklist or it is not.