py-tgcalls

2.2.12 verified Fri May 01 auth: no python

Async client API for Telegram Calls, enabling voice chat functionality in Telegram bots and clients. Current version 2.2.12, requires Python >=3.10. Released regularly via PyPI.

pip install py-tgcalls

Common errors

error pytgcalls.exceptions.AlreadyJoinedError: Already joined to the group call ↓

cause Calling join_group_call when already in a call without leaving first.

fix

Call await py_tgcalls.leave_group_call(chat_id) before joining again.

error AttributeError: module 'pytgcalls' has no attribute 'GroupCallFactory' ↓

cause Using v1 API (GroupCallFactory) with py-tgcalls v2.

fix

Upgrade code to use PyTgCalls class. Remove GroupCallFactory and use PyTgCalls(app).

error TypeError: Object of type 'MediaStream' is not JSON serializable ↓

cause Passing MediaStream to something that expects a dict, e.g., as a message reply.

fix

Do not serialize MediaStream directly. Use it only with join_group_call or change_stream.

Warnings

breaking v2.0 dropped GroupCallFactory and changed the entire API. Old v1 code using GroupCallFactory will not work. ↓

fix Migrate to PyTgCalls class. See migration guide in GitHub README.

breaking MediaStream replaces InputAudioStream and InputVideoStream. These old classes are removed in v2. ↓

fix Use MediaStream from pytgcalls.types.

gotcha Initializing PyTgCalls with a client that is not logged in or not started will cause runtime errors. ↓

fix Ensure the Pyrogram/Telethon client is started before starting PyTgCalls.

Imports

pytgcalls
wrong
```
from py_tgcalls import PyTgCalls
```
correct
```
from pytgcalls import PyTgCalls
```
Hyphen in package name, but import uses underscore

MediaStream

wrong

from pytgcalls import MediaStream

correct

from pytgcalls.types import MediaStream

MediaStream is in pytgcalls.types submodule

GroupCallFactory

wrong

GroupCallFactory is deprecated in v2; use PyTgCalls directly

correct

from pytgcalls import GroupCallFactory

GroupCallFactory removed in v2

Quickstart

Basic usage: start a voice chat in a group using Pyrogram and py-tgcalls.

import asyncio
from pyrogram import Client
from pytgcalls import PyTgCalls
from pytgcalls.types import MediaStream

app = Client('my_account', api_id=12345, api_hash='abcdef')
py_tgcalls = PyTgCalls(app)

async def main():
    await py_tgcalls.start()
    await py_tgcalls.join_group_call(
        -1001234567890,
        MediaStream(
            'https://example.com/audio.ogg',
        )
    )
    await asyncio.Event().wait()

app.run(main())