openapi: 3.0.0 info: title: Mautrix-Telegram provisioning version: 0.11.3 description: The provisioning API for Mautrix-Telegram, the Matrix-Telegram puppeting/relaybot bridge. license: name: AGPLv3 url: https://github.com/mautrix/telegram/blob/master/LICENSE externalDocs: description: Provisioning API docs on docs.mau.fi url: https://docs.mau.fi/bridges/python/telegram/provisioning-api.html tags: - name: User info - name: Authentication - name: Bridging - name: Misc paths: /v1/bridge: get: operationId: get_bridge summary: Get the bridge's information tags: [Misc] responses: 200: description: The bridge information content: application/json: schema: type: object properties: relaybot_username: type: string description: The relay bot's username on Telegram /v1/portal/{room_id}: get: operationId: get_portal summary: Get the bridging status and info of the connected Telegram chat tags: [Bridging] responses: 200: description: Room is bridged content: application/json: schema: $ref: "#/components/schemas/PortalInfo" 400: $ref: "#/components/responses/BadRequest" 404: description: Unknown portal content: application/json: schema: type: object title: Error properties: errcode: type: string title: Error code description: A machine-readable error code enum: - portal_not_found error: $ref: "#/components/schemas/HumanReadableError" parameters: - name: room_id in: path description: The Matrix ID of the room whose bridging status to get required: true schema: type: string pattern: "![^/]+" - name: user_id in: query description: Optional Matrix user ID to check if the user has permissions to do bridging. required: false schema: type: string /v1/portal/{chat_id}: get: operationId: get_portal_by_tgid summary: Get the bridging status and info of the connected Telegram chat tags: [Bridging] responses: 200: description: Chat is bridged content: application/json: schema: $ref: "#/components/schemas/PortalInfo" 400: description: Invalid Telegram chat ID content: application/json: schema: type: object title: Error properties: errcode: type: string title: Error code description: A machine-readable error code enum: - tgid_invalid error: $ref: "#/components/schemas/HumanReadableError" 404: description: Unknown portal content: application/json: schema: type: object title: Error properties: errcode: type: string title: Error code description: A machine-readable error code enum: - portal_not_found error: $ref: "#/components/schemas/HumanReadableError" parameters: - name: chat_id in: path description: The Matrix ID of the room whose bridging status to get required: true schema: type: integer pattern: -[0-9]+ - name: user_id in: query description: Optional Matrix user ID to check if the user has permissions to do bridging. required: false schema: type: string /v1/portal/{room_id}/connect/{chat_id}: post: operationId: connect_portal summary: Connect an existing Telegram chat to the given room tags: [Bridging] parameters: - name: room_id in: path description: The Matrix ID of the room to which the Telegram chat should be connected required: true schema: type: string - name: chat_id in: path description: The ID of the Telegram chat to connect required: true schema: type: integer pattern: -[0-9]+ - name: force in: query description: Set to force bridging by unbridging or deleting existing portal rooms. required: false schema: type: string enum: - delete - unbridge - name: user_id in: query description: Optional Matrix user ID to check if the user has permissions to do the bridging. required: false schema: type: string responses: 200: description: Telegram chat was already bridged to given room. 202: description: Room bridging initiated 400: $ref: "#/components/responses/BadRequest" 403: description: "Given user doesn't have permission to bridge the room, or the bridge bot is not in the room" content: application/json: schema: type: object title: Error properties: errcode: type: string title: Error code description: A machine-readable error code enum: - not_enough_permissions - bot_not_in_room - bot_not_in_chat - not_logged_in error: $ref: "#/components/schemas/HumanReadableError" 409: description: Matrix room or Telegram chat is already bridged to another chat/room content: application/json: schema: type: object title: Error properties: errcode: type: string title: Error code description: A machine-readable error code example: _already_bridged enum: - room_already_bridged - chat_already_bridged error: $ref: "#/components/schemas/HumanReadableError" /v1/portal/{room_id}/create: post: operationId: create_portal summary: Create a new Telegram chat for the given room tags: [Bridging] responses: 201: description: Telegram chat created content: application/json: schema: type: object properties: chat_id: type: integer 400: $ref: "#/components/responses/BadRequest" 403: description: "Given user isn't logged in with a real account or doesn't have permission to bridge the room, or the bridge bot is not in the room" content: application/json: schema: type: object title: Error properties: errcode: type: string title: Error code description: A machine-readable error code enum: - not_logged_in_real_account - not_enough_permissions - bot_not_in_room error: $ref: "#/components/schemas/HumanReadableError" 409: description: Room is already bridged content: application/json: schema: type: object title: Error properties: errcode: type: string title: Error code description: A machine-readable error code enum: - room_already_bridged error: $ref: "#/components/schemas/HumanReadableError" parameters: - name: room_id in: path description: The Matrix ID of the room whose bridging status to get required: true schema: type: string - name: user_id in: query description: Matrix user to create the chat as. required: true schema: type: string requestBody: content: application/json: schema: type: object required: [type] properties: type: description: The type of chat to create type: string example: supergroup enum: - chat - supergroup - channel title: description: Title for the new chat type: string example: Mautrix-Telegram Bridge about: description: About text for the new chat type: string example: Discussion about mautrix-telegram required: true /v1/portal/{room_id}/disconnect: post: operationId: disconnect_portal summary: Disconnect the Telegram chat from the room tags: [Bridging] responses: 202: description: Room unbridging initiated 400: $ref: "#/components/responses/BadRequest" 403: $ref: "#/components/responses/PermissionError" 404: description: Unknown portal content: application/json: schema: type: object title: Error properties: errcode: type: string title: Error code description: A machine-readable error code enum: - portal_not_found error: $ref: "#/components/schemas/HumanReadableError" parameters: - name: room_id in: path description: The Matrix ID of the room whose bridging status to get required: true schema: type: string - name: user_id in: query description: Optional Matrix user ID to check if the user has permissions to do the bridging. required: false schema: type: string - name: delete in: query description: Whether or not to delete the room completely (kick all users instead of just Telegram puppets) required: false schema: type: boolean default: false - name: sync in: query description: Whether or not to wait for the unbridging to be completed before responding. **Could cause timeouts in large rooms** required: false schema: type: boolean default: false /v1/user/{user_id}: get: operationId: get_me summary: Get the info of the Telegram user the given Matrix user is logged in as tags: [User info] responses: 200: description: User found content: application/json: schema: $ref: "#/components/schemas/UserInfo" 400: $ref: "#/components/responses/BadRequest" 403: $ref: "#/components/responses/NotWhitelistedError" 500: $ref: "#/components/responses/UnknownError" parameters: - name: user_id in: path description: The Matrix ID of the user who to log in as required: true schema: type: string /v1/user/{user_id}/chats: get: operationId: get_chats summary: Get the list of Telegram chats the given Matrix user has access to tags: [User info] responses: 200: description: User is logged in content: application/json: schema: $ref: "#/components/schemas/UserChats" 400: $ref: "#/components/responses/BadRequest" 403: description: User is not logged in or not whitelisted content: application/json: schema: type: object title: Error properties: errcode: type: string title: Error code description: A machine-readable error code enum: - not_logged_in - mxid_not_whitelisted error: $ref: "#/components/schemas/HumanReadableError" 500: $ref: "#/components/responses/UnknownError" parameters: - name: user_id in: path description: The Matrix ID of the user who to log in as required: true schema: type: string /v1/user/{user_id}/contacts: get: operationId: get_contacts summary: Get the user's Telegram contacts tags: [User info] responses: 200: description: Found contact list content: application/json: schema: $ref: "#/components/schemas/UserContacts" 403: description: User is not logged in or not whitelisted content: application/json: schema: type: object title: Error properties: errcode: type: string title: Error code description: A machine-readable error code enum: - not_logged_in - mxid_not_whitelisted error: $ref: "#/components/schemas/HumanReadableError" 500: $ref: "#/components/responses/UnknownError" parameters: - name: user_id in: path description: The Matrix ID of the user who to log in as required: true schema: type: string /v1/user/{user_id}/pm/{identifier}: post: operationId: start_dm summary: Start a direct chat with a Telegram user. tags: [Bridging] responses: 200: description: A portal already existed content: application/json: schema: $ref: "#/components/schemas/StartedChat" 201: description: A portal was created content: application/json: schema: $ref: "#/components/schemas/StartedChat" 403: description: User is not logged in or not whitelisted content: application/json: schema: type: object title: Error properties: errcode: type: string title: Error code description: A machine-readable error code enum: - not_logged_in - mxid_not_whitelisted error: $ref: "#/components/schemas/HumanReadableError" 500: $ref: "#/components/responses/UnknownError" parameters: - name: user_id in: path description: The Matrix ID of the user who to log in as required: true schema: type: string - name: identifier in: path description: The Telegram identifier of the user to start a private chat with. Username, phone number or internal ID. required: true schema: anyOf: - type: string description: Telegram username (no prefix) or international phone number (starting with +) example: tguser - type: integer description: Internal Telegram user ID example: 987654321 /v1/user/{user_id}/login/bot_token: post: operationId: post_bot_token summary: Log in with a bot token tags: [Authentication] responses: 200: description: Login successful content: application/json: schema: $ref: "#/components/schemas/AuthSuccess" 400: $ref: "#/components/responses/BadRequest" 401: description: Invalid or expired bot token or invalid shared secret content: application/json: schema: type: object title: Error properties: errcode: type: string title: Error code description: A machine-readable error code example: bot_token_ enum: - bot_token_invalid - bot_token_expired - shared_secret_invalid error: $ref: "#/components/schemas/HumanReadableError" 403: $ref: "#/components/responses/NotWhitelistedError" 409: $ref: "#/components/responses/AlreadyLoggedInError" 500: $ref: "#/components/responses/UnknownError" parameters: - name: user_id in: path description: The Matrix ID of the user who to log in as required: true schema: type: string requestBody: content: application/json: schema: type: object properties: token: type: string description: The access token of the bot to log in as example: 297900271:IXjeGEcAN61zHnjPgkWnYWyvVp9K4ulHBEv required: true /v1/user/{user_id}/login/request_code: post: operationId: post_login_phone summary: Request a phone code from Telegram tags: [Authentication] responses: 200: description: Code requested successfully content: application/json: schema: $ref: "#/components/schemas/AuthSuccess" 400: description: Invalid phone number or JSON content: application/json: schema: type: object title: Error properties: errcode: type: string title: Error code description: A machine-readable error code example: machine_readable_error enum: - phone_number_invalid - json_invalid error: $ref: "#/components/schemas/HumanReadableError" 401: description: Invalid shared secret content: application/json: schema: type: object title: Error properties: errcode: type: string title: Error code description: A machine-readable error code enum: - shared_secret_invalid error: $ref: "#/components/schemas/HumanReadableError" 403: description: Matrix ID is not whitelisted or phone number is banned or has forbidden 3rd party apps content: application/json: schema: type: object title: Error properties: errcode: type: string title: Error code description: A machine-readable error code example: machine_readable_error enum: - mxid_not_whitelisted - phone_number_banned - phone_number_app_signup_forbidden error: $ref: "#/components/schemas/HumanReadableError" 404: description: Unregistered phone number content: application/json: schema: type: object title: Error properties: errcode: type: string title: Error code description: A machine-readable error code enum: - phone_number_unoccupied error: $ref: "#/components/schemas/HumanReadableError" 409: $ref: "#/components/responses/AlreadyLoggedInError" 429: description: Phone number has been temporarily blocked for flooding content: application/json: schema: type: object title: Error properties: errcode: type: string title: Error code description: A machine-readable error code enum: - flood_wait - phone_number_flood error: $ref: "#/components/schemas/HumanReadableError" 500: $ref: "#/components/responses/UnknownError" parameters: - name: user_id in: path description: The Matrix ID of the user who to log in as required: true schema: type: string requestBody: content: application/json: schema: type: object properties: phone: type: string description: The phone number to log in as. example: "+123456789" required: true /v1/user/{user_id}/login/send_code: post: operationId: post_login_code summary: Send the login code tags: [Authentication] responses: 200: description: Login successful content: application/json: schema: $ref: "#/components/schemas/AuthSuccess" 202: description: Correct code, but two-factor authentication is enabled content: application/json: schema: $ref: "#/components/schemas/AuthSuccess" 400: $ref: "#/components/responses/BadRequest" 401: description: Invalid phone code or shared secret content: application/json: schema: type: object title: Error properties: errcode: type: string title: Error code description: A machine-readable error code enum: - phone_code_invalid - shared_secret_invalid error: $ref: "#/components/schemas/HumanReadableError" 403: description: Matrix ID not whitelisted or phone code expired content: application/json: schema: type: object title: Error properties: errcode: type: string title: Error code description: A machine-readable error code example: machine_readable_error enum: - mxid_not_whitelisted - phone_code_expired error: $ref: "#/components/schemas/HumanReadableError" 409: $ref: "#/components/responses/AlreadyLoggedInError" 500: $ref: "#/components/responses/UnknownError" parameters: - name: user_id in: path description: The Matrix ID of the user who to log in as required: true schema: type: string requestBody: content: application/json: schema: type: object properties: code: type: integer description: The phone code from Telegram. format: int32 example: 123456 required: true /v1/user/{user_id}/login/send_password: post: operationId: post_login_password summary: Send the two-factor auth password tags: [Authentication] responses: 200: description: Login successful content: application/json: schema: $ref: "#/components/schemas/AuthSuccess" 400: description: Missing password or invalid JSON content: application/json: schema: type: object title: Error properties: errcode: type: string title: Error code description: A machine-readable error code example: _empty enum: - password_empty - json_invalid error: $ref: "#/components/schemas/HumanReadableError" 401: description: Incorrect password or invalid shared secret content: application/json: schema: type: object title: Error properties: errcode: type: string title: Error code description: A machine-readable error code enum: - password_invalid - shared_secret_invalid error: $ref: "#/components/schemas/HumanReadableError" 403: $ref: "#/components/responses/NotWhitelistedError" 409: $ref: "#/components/responses/AlreadyLoggedInError" 500: $ref: "#/components/responses/UnknownError" parameters: - name: user_id in: path description: The Matrix ID of the user who to log in as required: true schema: type: string requestBody: content: application/json: schema: type: object properties: password: type: string description: The two-factor auth password format: password example: hunter2 required: true /v1/user/{user_id}/logout: post: operationId: logout summary: Log out tags: - Authentication responses: 200: description: Logout successful 403: description: User was not logged in content: application/json: schema: type: object title: Error properties: errcode: type: string title: Error code description: A machine-readable error code enum: - not_logged_in error: $ref: "#/components/schemas/HumanReadableError" 500: $ref: "#/components/responses/UnknownError" parameters: - name: user_id in: path description: The Matrix ID of the user who to log out as required: true schema: type: string security: - Bearer: [] servers: - url: /_matrix/provision components: responses: NotWhitelistedError: description: Matrix ID not whitelisted for puppeting content: application/json: schema: type: object title: Error properties: errcode: type: string title: Error code description: A machine-readable error code enum: - mxid_not_whitelisted error: $ref: "#/components/schemas/HumanReadableError" AlreadyLoggedInError: description: The Matrix user is already logged in content: application/json: schema: type: object properties: state: type: string enum: - logged-in username: type: string description: The Telegram username the user is logged in as. phone: type: string description: The phone number of the account the user is logged into. BadRequest: description: Invalid JSON. content: application/json: schema: type: object title: Error properties: errcode: type: string title: Error code description: A machine-readable error code enum: - json_invalid - mxid_empty - body_value_missing - body_value_invalid error: $ref: "#/components/schemas/HumanReadableError" UnknownError: description: Unknown error content: application/json: schema: type: object title: UnknownError properties: errcode: type: string title: Error code description: A machine-readable error code enum: - unknown_error - unhandled_error error: type: string title: Error description: A human-readable description of the error example: Internal server error while . PermissionError: description: The given Matrix user doesn't have the permissions to do that. content: application/json: schema: type: object title: Error properties: errcode: type: string title: Error code description: A machine-readable error code example: not_enough_permissions enum: - not_enough_permissions error: $ref: "#/components/schemas/HumanReadableError" securitySchemes: Bearer: description: Required authentication for all endpoints name: Authorization in: header type: apiKey schemas: UserInfo: type: object properties: mxid: type: string example: "@usern:example.com" permissions: type: string example: user enum: - none - relaybot - user - full - admin telegram: type: object properties: id: type: integer example: 123456789 username: type: string example: username first_name: type: string example: Usern last_name: type: string example: A. phone: type: string example: 123456789 is_bot: type: boolean example: false UserChats: type: array items: type: object properties: id: type: integer example: -123456789 description: A bot API style chat ID. title: type: string UserContactInfo: type: object properties: name: type: string description: The displayname of the Telegram user. example: Telegram User username: type: string description: The username of the Telegram user. example: tguser phone: type: string description: The phone number of the Telegram user. example: +123456789 is_bot: type: boolean description: Whether the Telegram user is a bot or a normal user. example: false avatar_url: type: string description: The Matrix avatar URL for the Telegram user's ghost. example: mxc://example.com/abcdef123456 UserContacts: type: object properties: "": $ref: "#/components/schemas/UserContactInfo" # TODO use this when SwaggerUI supports OpenAPI 3.1 #patternProperties: # "^[0-9]+$": # $ref: "#/components/schemas/UserContactInfo" StartedChat: type: object properties: room_id: type: string description: The Matrix room ID. example: "!foo:example.com" just_created: type: boolean description: True if the portal was just created for this request. example: false id: type: integer description: The Telegram user ID. example: 987654321 contact_info: $ref: "#/components/schemas/UserContactInfo" PortalInfo: type: object properties: mxid: type: string example: "!foo:example.com" chat_id: type: integer example: -100123456789 peer_type: type: string enum: - user - chat - channel megagroup: type: boolean username: type: string title: type: string about: type: string can_unbridge: type: boolean description: If a user ID was provided with the request, this will indicate whether or not the user can unbridge the room. AuthSuccess: type: object properties: state: type: string description: The state/next step after the successful operation. enum: - code - request - password - token - logged-in username: type: string description: The Telegram username the user is logged in as. Only applicable if state=logged-in phone: type: string description: The phone number of the account the user logged into. Only applicable if state=logged-in HumanReadableError: type: string description: A human-readable description of the error example: A human-readable description of the error