From 45f23521f27706614d7a3a4cc0ce15c0b37fda44 Mon Sep 17 00:00:00 2001 From: GitHub Action Date: Sat, 5 Oct 2024 13:43:35 +0000 Subject: [PATCH] Update content of files --- .../gateway/verification-tutorial.html | 42 ++++++++++++------- 1 file changed, 27 insertions(+), 15 deletions(-) diff --git a/data/web/core.telegram.org/gateway/verification-tutorial.html b/data/web/core.telegram.org/gateway/verification-tutorial.html index 9d0c94a264..bc53e38087 100644 --- a/data/web/core.telegram.org/gateway/verification-tutorial.html +++ b/data/web/core.telegram.org/gateway/verification-tutorial.html @@ -109,31 +109,41 @@ def post_request_status(endpoint, json_body): return None

Sending Auth Codes

-

TLDR: Pass a phone number (E.164 format) to this method as a dry run – if you don’t get an error, pass the request_id you just obtained to this method to send an auth code to the user.

+

TLDR: Pass a phone number (E.164 format) to this method to directly send an auth code to the user. If you need a dry run to verify your code can be delivered, use this method.

-

To send an authorization code, we’ll first use the checkSendAbility method to verify that the user we want to target can receive messages on Telegram.

-
endpoint = 'checkSendAbility'
-json_body = {
-    'phone_number': PHONE # E.164 format
-}
-result = post_request_status(endpoint, json_body)
-if result:
-    request_id = result.get('request_id')
-    print(f"Request ID: {request_id}")
-
-

If the method returns an error and the user cannot be contacted, you will not be charged. If the method instead indicates that the user can be contacted, you will be automatically charged in advance for the price of a message regardless of whether you eventually send one. If you do send a message, use the request_id returned by this method to avoid paying the message fee again.

-
-

Assuming the outcome was positive and the user can be contacted, we can send them a code generated by Telegram with the sendVerificationMessage method:

+

To send the user a code generated by Telegram, you can use the sendVerificationMessage method:

endpoint = 'sendVerificationMessage'
+
 json_body = {
-    'request_id': request_id,      # Reuse to avoid paying the fee again
     'phone_number': PHONE,         # Must be the one tied to request_id
     'code_length': 6,              # Ignored if you specify your own 'code'
     'ttl': 60,                     # 1 minute
     'payload': 'my_payload_here',  # Not shown to users
     'callback_url': 'https://my.webhook.here/auth'
 }
+
 result = post_request_status(endpoint, json_body)
+
+

If the method returns an error (e.g., because the user cannot receive codes), you will not be charged. On success, it will return a RequestStatus object.

+
+

You can optionally specify the sender_username parameter, designating a verified channel you own as the one from which the code will be sent to the user. When sending codes to yourself for testing purposes, the channel does not need to be verified.

+

Checking that codes can be delivered

+

Before sending, you can also optionally use the checkSendAbility method to verify that the user you want to target can receive messages on Telegram. This is especially useful when you generated a code yourself but need to check that it can be delivered before sending it out to the user through the Gateway API.

+
endpoint = 'checkSendAbility'
+
+json_body = {
+    'phone_number': PHONE # E.164 format
+}
+
+result = post_request_status(endpoint, json_body)
+
+if result:
+    request_id = result.get('request_id')
+    print(f"Request ID: {request_id}")
+
+

If the method returns an error (e.g., because the user cannot receive codes), you will not be charged. If the method instead indicates that the user can be contacted, you will be automatically charged in advance for the price of a message regardless of whether you eventually send one.

+
+

If the check succeeds and you ultimately decide to send a message, use the request_id returned by the checkSendAbility method to avoid paying the message fee again.

Revoking Codes

You can optionally revoke codes even before they expire by passing the relevant request_id to the revokeVerificationMessage method. Messages which were already read will not be deleted.

@@ -142,10 +152,12 @@ result = post_request_status(endpoint, json_body)

Checking the Authorization Status

If you let Telegram generate a code for you (i.e., you did not provide a code param in your request), you can use the checkVerificationStatus method to verify the OTP submitted by your user.

endpoint = 'checkVerificationStatus'
+
 json_body = {
     'request_id': request_id, # Relevant request id
     'code': CODE,             # The code the user entered in your app
 }
+
 result = post_request_status(endpoint, json_body)
 
 # Assuming the request was successful