{"id":15045031,"url":"https://github.com/cjongseok/mtproto","last_synced_at":"2026-02-27T09:09:33.497Z","repository":{"id":57500310,"uuid":"111369375","full_name":"cjongseok/mtproto","owner":"cjongseok","description":"Telegram MTProto and its proxy (over gRPC) in Go (golang). API Layer: 71","archived":false,"fork":false,"pushed_at":"2018-12-31T02:51:04.000Z","size":2062,"stargazers_count":150,"open_issues_count":7,"forks_count":20,"subscribers_count":17,"default_branch":"master","last_synced_at":"2025-04-07T03:51:23.479Z","etag":null,"topics":["go","golang","grpc","mtproto","proxy","telegram"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cjongseok.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-11-20T06:14:02.000Z","updated_at":"2025-02-11T21:33:42.000Z","dependencies_parsed_at":"2022-08-30T20:42:18.105Z","dependency_job_id":null,"html_url":"https://github.com/cjongseok/mtproto","commit_stats":null,"previous_names":[],"tags_count":17,"template":false,"template_full_name":null,"purl":"pkg:github/cjongseok/mtproto","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cjongseok%2Fmtproto","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cjongseok%2Fmtproto/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cjongseok%2Fmtproto/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cjongseok%2Fmtproto/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cjongseok","download_url":"https://codeload.github.com/cjongseok/mtproto/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cjongseok%2Fmtproto/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":261232654,"owners_count":23128166,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["go","golang","grpc","mtproto","proxy","telegram"],"created_at":"2024-09-24T20:51:22.144Z","updated_at":"2026-02-27T09:09:28.476Z","avatar_url":"https://github.com/cjongseok.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"MTProto\n===\nTelegram MTProto and proxy (over gRPC) in Go (golang).\nTelegram API layer: ***71***\n\n## Quick start\n```sh\n# It is vendored in 'dep'. Refer to https://github.com/golang/dep for 'dep' installation.\ndep ensure\n\n# Run simple shell with your Telegram API id, hash, and, server address with your phone number.\n# If you don't have Telegram API stuffs, get them from 'https://my.telegram.org/apps'.\ngo run examples/simpleshell/main.go \u003cAPIID\u003e \u003cAPIHASH\u003e \u003cPHONE\u003e \u003cIP\u003e \u003cPORT\u003e\n\n# Then you can see 'Enter code:' message\n# Telegram sends you an authentication code. Check it on your mobile or desktop app and put it.\nEnter code: \u003cYOUR_CODE\u003e\n\n# Now signed-in. Let's get your recent dialogs. \n# You can see them in JSON.\n$ dialogs\n....\n\n# Quit the shell.\n$ exit\n\n# You can find 'credentials.json' file which keeps your MTProto secerets.\nls -al credentials.json\n\n# You can check if the scerets correct by sign-in with it.\ngo run examples/simpleshell/main.go  credentials.json\n```\n\n## Usage\nYou can find the real code at [simpleshell](https://github.com/cjongseok/mtproto/blob/master/examples/simpleshell/main.go).\n### Sign-in with key\n```go\n// Mew MTProto manager\nconfig, _ := mtproto.NewConfiguration(appVersion, deviceModel, systemVersion, language, 0, 0, \"credentials.json\")\nmanager, _ := mtproto.NewManager(config)\n\n// Sign-in by key\nmconn, _ := manager.LoadAuthentication()\n```\n### Sign-in without key\n```go\n// New MTProto manager\nconfig, _ := mtproto.NewConfiguration(appVersion, deviceModel, systemVersion, language, 0, 0, \"new-credentials.json\")\nmanager, _ := mtproto.NewManager(config)\n\n// Request to send an authentication code\n// It needs your phone number and Telegram API stuffs you can check in https://my.telegram.org/apps \nmconn, sentCode, err := manager.NewAuthentication(phoneNumber, apiID, apiHash, ip, port)\n\n// Get the code from user input\nfmt.Scanf(\"%s\", \u0026code)\n\n// Sign-in and generate the new key\n_, err = mconn.SignIn(phoneNumber, code, sentCode.GetValue().PhoneCodeHash)\n```\n### Telegram RPC in Protocol Buffer\ncjongseok/mtproto implements [TL-schema](https://core.telegram.org/schema) [functions](https://github.com/cjongseok/mtproto/blob/142b7f31f963a074dac9dd6759e0ae054e4a894c/compiler/scheme-71.tl#L951) in [Protocol Buffer](https://developers.google.com/protocol-buffers/). These are declared in [types.tl.proto](https://github.com/cjongseok/mtproto/blob/142b7f31f963a074dac9dd6759e0ae054e4a894c/types.tl.proto#L6385) as RPCs, and implemented in Go at [procs.tl.go](https://github.com/cjongseok/mtproto/blob/master/procs.tl.go). With the same interface, you can call functions not only in direct connection to the Telegram server, but also over a mtproto proxy.\n\nLet's have two direct call examples, [messages.getDialogs](https://github.com/cjongseok/mtproto/blob/142b7f31f963a074dac9dd6759e0ae054e4a894c/compiler/scheme-71.tl#L1025) and [messages.sendMessage](https://github.com/cjongseok/mtproto/blob/142b7f31f963a074dac9dd6759e0ae054e4a894c/compiler/scheme-71.tl#L1033).\n#### Get dialogs\n```go\n// New RPC caller with a connection to Telegram server. \n// By alternating mconn with a proxy connection, you can call same functions over proxy. It is covered later.\ncaller := mtproto.RPCaller{mconn}\n\n// New input peer\n// In Telegram DSL, Predicates inherit a Type.\n// Here we create a Predicate, InputPeerEmpty whose parent is InputPeer.\n// More details about these types are covered later.\nemptyPeer := \u0026mtproto.TypeInputPeer{\u0026mtproto.TypeInputPeer_InputPeerEmpty{\u0026mtproto.PredInputPeerEmpty{}}\n\n// Query to Telegram\ndialogs, _ := caller.MessagesGetDialogs(context.Background(), \u0026mtproto.ReqMessagesGetDialogs{\n    OffsetDate: 0,\n    OffsetId: \t0,\n    OffsetPeer: emptyPeer,\n    Limit: \t\t1,\n})\n```\n#### Send a message to a channel\n```go\n// New RPC caller with a connection to Telegram server. \ncaller := mtproto.RPCaller{mconn}\n\n// New input peer\n// Create a Predicate, InputPeerChannel, wraped by its parent Type, InputPeer.\nchannelPeer := \u0026mtproto.TypeInputPeer{\u0026mtproto.TypeInputPeer_InputPeerChannel{\n    \u0026mtproto.PredInputPeerChannel{\n        yourChannelId, yourChannelHash,\n    }}}\n\n// Send a request to Telegram\ncaller.MessagesSendMessage(context.Background(), \u0026mtproto.ReqMessagesSendMessage{\n    Peer:      channelPeer,\n    Message:   \"Hello MTProto\",\n    RandomId:  rand.Int63(),\n})\n```\n\n## How mtproto is impelemented in Protocol Buffer\n### Types\nTelegram's mtproto has three kinds of types, Type, Predicate, and Method. A Type is a kind of a data structure interface which has no fields, and a Predicate implements a Type. In the above case, mtproto.[PredInputPeerChannel](https://github.com/cjongseok/mtproto/blob/142b7f31f963a074dac9dd6759e0ae054e4a894c/types.tl.proto#L3046) is a Predicate of a Type mtproto.[TypeInputPeer](https://github.com/cjongseok/mtproto/blob/142b7f31f963a074dac9dd6759e0ae054e4a894c/types.tl.proto#L19). gRPC recommends to implement this kind of polymorphism with [Oneof](https://developers.google.com/protocol-buffers/docs/proto3#oneof), so [InputPeer](https://github.com/cjongseok/mtproto/blob/142b7f31f963a074dac9dd6759e0ae054e4a894c/compiler/scheme-71.tl#L38) is defined in Protocol Buffer as below:\n```protobuf\n// types.tl.proto:19\nmessage TypeInputPeer {\n\toneof Value {\n\t\tPredInputPeerEmpty InputPeerEmpty = 1;\n\t\tPredInputPeerSelf InputPeerSelf = 2;\n\t\tPredInputPeerChat InputPeerChat = 3;\n\t\tPredInputPeerUser InputPeerUser = 4;\n\t\tPredInputPeerChannel InputPeerChannel = 5;\n    }\n}\n```\nThe use of gRPC Oneof in Go is complex, because Go does not allow hierarchical relations among types, e.g., inheritance. I believe, however, gRPC guys did their best and it would be the best implementation of such polymorphism in Go with RPC. For more details about the use of OneOf in Go, please refer to [this document](https://developers.google.com/protocol-buffers/docs/reference/go-generated#oneof).\n\n### Methods\nMtproto methods have a namespace as you can see in [TL-schema](https://github.com/cjongseok/mtproto/blob/142b7f31f963a074dac9dd6759e0ae054e4a894c/compiler/scheme-71.tl#L951), e.g., auth, account, users, ... . Instead of managing these namespaces as separate [Protocol Buffer services](https://developers.google.com/protocol-buffers/docs/proto3#services), these are integrated into one Protocol Buffer Service, [Mtproto](https://github.com/cjongseok/mtproto/blob/142b7f31f963a074dac9dd6759e0ae054e4a894c/types.tl.proto#L6385), and namesapces are remained as method name prefixes. In the above example, the original name of [MessagesSendMessage](https://github.com/cjongseok/mtproto/blob/142b7f31f963a074dac9dd6759e0ae054e4a894c/types.tl.proto#L6425) is [messages.sendMessage](https://github.com/cjongseok/mtproto/blob/142b7f31f963a074dac9dd6759e0ae054e4a894c/compiler/scheme-71.tl#L1033).\n\nIn the original schema, a method can have multiple parameters. These paremeters are declared into a new data structure in Protocol Buffer whose name starts with 'Req'. For example, [messages.sendMessage](https://github.com/cjongseok/mtproto/blob/142b7f31f963a074dac9dd6759e0ae054e4a894c/compiler/scheme-71.tl#L1033) requires many parameters, and these are transformed into [ReqMessagesSendMessage](https://github.com/cjongseok/mtproto/blob/142b7f31f963a074dac9dd6759e0ae054e4a894c/types.tl.proto#L5165) in [MessagesSendMessage](https://github.com/cjongseok/mtproto/blob/142b7f31f963a074dac9dd6759e0ae054e4a894c/types.tl.proto#L6425).\n\n# Proxy\nYou can use the proxy in two purposes:\n* MTProto session sharing: Many proxy clients can use the same MTProto session on the proxy server.\n* MTProto in other languages: The proxy enables various languages on its client side, since it uses gRPC.\n\n## Server\n### As a stand-alone daemon\n[mtprotod](https://github.com/cjongseok/mtproto/tree/master/mtprotod) is a stand-alone proxy daemon containing Telegram MTProto implementation in Go.\n\n#### Quick Start\n```bash\n# start mtprotod at port 11011\ndocker run \\\n-p 11011: 11011 \\\n-v /your/mtproto/secrets/directory:/opt \\\ncjongseok/mtprotod start  \\\n--port 11011 \\\n--addr \u003cYour_Telegram_server_address\u003e \\\n--apiid \u003cYour_Telegram_api_id\u003e \\\n--apihash \u003cYour_Telegram_api_hash\u003e \\\n--phone \u003cYour_Telegram_phone_number\u003e \\\n--secrets /opt/\u003cYour_MTProto_secrets_file_name\u003e\n\n# At mtproto/proxy, let's get dialogs through over the proxy\ndep ensure\ngo test proxy/proxy_test.go --run TestDialogs\n```\n\n#### Build \u0026 Run\n```bash\n# In mtproto directory\ndep ensure\ngo run mtprotod/main.go start \\\n--addr \u003cYour_Telegram_server_address\u003e \\\n--apiid \u003cYour_Telegram_api_id\u003e \\\n--apihash \u003cYour_Telegram_api_hash\u003e \\\n--phone \u003cYour_Telegram_phone_number\u003e \\\n--port \u003cProxy_port\u003e \\\n--secrets /opt/\u003cYour_MTProto_secrets_file_name\u003e\n```\n\n### As a part of Go application\nUse mtproto/proxy package.\n```go\n// New proxy server\nconfig, _ := mtproto.NewConfiguration(apiId, apiHash, appVersion, deviceModel, systemVersion, language, 0, 0, key)\nserver = proxy.NewServer(port)\n\n// Start the server\nserver.Start(config, phone)\n```\n## Client in Go\n```go\n// New proxy client\nclient, _ := proxy.NewClient(proxyAddr)\n\n// Telegram RPC over proxy. It is same with the previous 'Get dialogs' but the RPC caller\nemptyPeer := \u0026mtproto.TypeInputPeer{\u0026mtproto.TypeInputPeer_InputPeerEmpty{\u0026mtproto.PredInputPeerEmpty{}}\ndialogs, err := client.MessagesGetDialogs(context.Background(), \u0026mtproto.ReqMessagesGetDialogs{\n    OffsetDate: 0,\n    OffsetId:   0,\n    OffsetPeer: emptyPeer,\n    Limit:      1,\n})\n```\n## Client in Python\nSee [py](https://github.com/cjongseok/mtproto/tree/master/py).\n## Client in other languages\nBy compiling [types.tl.proto](https://github.com/cjongseok/mtproto/tree/master/types.tl.proto) and [proxy/tl_update.proto](https://github.com/cjongseok/mtproto/tree/master/proxy/tl_update.proto), \nyou can create clients in your preferred language.\u003cbr\u003e\nFor this, you need to install [Protocol Buffer](https://developers.google.com/protocol-buffers/) together with gRPC library of the target language.\nThen you can compile Protocol Buffer files with this kind of command lines:\n* [Go](https://github.com/cjongseok/mtproto/blob/master/compiler/build.sh)\n* [Python](https://github.com/cjongseok/mtproto/blob/master/compiler/build_py.sh)\n\nYou can find these command lines for other languages in [gRPC tutorial](https://grpc.io/docs/).\n\n\u003c!--\n### Types and Predicates\n### X and !X\n\n## Tools\n### Keygen\n### Dumplayer\n\n## Compiler\n--\u003e\n\n\n## Acknowledgement\n* https://github.com/sdidyk/mtproto: It is the backend of most MTProto Go implementations.\nI referred its MTProto schema compiler, (de)serializer, handshaking, and encryption.\n* https://github.com/shelomentsevd/mtproto: I referred its layer 65 implementation and API wrappers.\n* https://github.com/ronaksoft/mtproto: I referred its backend changes for layer 71.\n\n\n## License\nApache 2.0\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcjongseok%2Fmtproto","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcjongseok%2Fmtproto","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcjongseok%2Fmtproto/lists"}