# Telegram Gateway

Interact with the new [Telegram Gateway API](https://core.telegram.org/gateway/api)

## How to use?
You need to create a `telegram_gateway.TelegramGateway` object, pass in the API key from the Telegram Gateway admin panel.
After that, call one of the 4 methods available:

## sendVerificationMessage
Send a verification message with this method. If you used checkSendAbility before calling this, pass in the request_id to avoid being billed twice.

Example usage: `gateway.sendVerificationMessage('+xxxxxxxxxxxxxxx', code_length=8, request_id=sendAbilityResponse.request_id)`

## checkSendAbility
Check if you can send a verification code to a specific phone number. You will get billed, even if you don't send a verification code afterwards.

Example usage: `gateway.checkSendAbility('+xxxxxxxxxxxxxxx')`

This raises an error if you can't send a message to that phone number, so make sure you setup an exception handler, otherwise your production environment may crash after a user puts in an invalid phone number by mistake.

## checkVerificationStatus
Use this method to check the status of a verification message that was sent previously. If the code was generated by Telegram for you, you can also verify the correctness of the code entered by the user using this method.

You can call this even if you made the code yourself - it will allow you to track the conversion rate in the Telegram Gateway admin panel.

Example usage: `gateway.checkVerificationStatus(sendCodeResponse.request_id)`
Example usage (2): `gateway.checkVerificationStatus(sendCodeResponse.request_id, code=input('Enter the code: ')).verification_status.status == telegram_gateway.enums.VerificationResult.CODE_VALID`

## revokeVerificationMessage
Use this method to revoke a verification message that was sent previously. However, this does not guarantee that the message will be deleted. For example, it will not be removed if the recipient has already read it.

Example usage: `gateway.revokeVerificationMessage(sendCodeResponse.request_id)`

This will raise an exception if the server returns False, even if it doesn't return any actual error, be aware of that.

# Example code
Send a message, revoke after 5 seconds (using TTL):
```py
import telegram_gateway

gateway = telegram_gateway.TelegramGateway(input("API token: "))
gateway.sendVerificationMessage(input("Phone number: "), code_length=8, ttl=5)
```
Revoke explicitly using the revokeVerificationMessage method:
```py
import time

import telegram_gateway

gateway = telegram_gateway.TelegramGateway(input("API token: "))
response = gateway.sendVerificationMessage(input("Phone number: "), code_length=8)
time.sleep(5)
gateway.revokeVerificationMessage(response.request_id)
```
Send a code, then validate it:
```py
import telegram_gateway

gateway = telegram_gateway.TelegramGateway(input("API token: "))
# This works with both a Telegram provided code and your own code.
sendCodeResponse = gateway.sendVerificationMessage(input("Phone number"), code_length=8)
code = input("Enter code: ")
while True:
    response = gateway.checkVerificationStatus(sendCodeResponse.request_id, code=code)
    if response.verification_status.status in [telegram_gateway.enums.VerificationResult.EXPIRED, telegram_gateway.enums.VerificationResult.CODE_MAX_ATTEMPTS_EXCEEDED]:
        print("The code expired, or the maximum amount of attempts has been exceeded.")
        break
    if response.verification_status.status == telegram_gateway.enums.VerificationResult.CODE_VALID:
        print("You entered the correct code.")
        break
    print("You entered the wrong code, try again.")
```