<metaproperty="description"content="The Gateway API is an HTTP-based interface created for developers looking to deliver automated messages, such as verification codes, to users who registered their phone number on Telegram.">
<metaproperty="og:description"content="The Gateway API is an HTTP-based interface created for developers looking to deliver automated messages, such as verification codes, to users who registered their phone number on Telegram.">
<p>The Gateway API is an HTTP-based interface created for developers looking to deliver automated messages, such as verification codes, to users who registered their phone number on Telegram. </p>
<p>This page outlines the full API documentation for developers. For more information on the API and the features it offers, see our <ahref="https://core.telegram.org/gateway">Verification Platform Overview</a> and <ahref="https://core.telegram.org/gateway/verification-tutorial">Gateway API Tutorial</a>.</p>
<p>All queries to the Telegram Gateway API must be served over HTTPS and need to be presented in this form: <code>https://gatewayapi.telegram.org/METHOD_NAME</code>. Like this for example:</p>
<p>The response contains a JSON object, which always has a Boolean field <code>ok</code>. If <code>ok</code> equals <em>true</em>, the request was successful, and the result of the query can be found in the <code>result</code> field. In case of an unsuccessful request, <code>ok</code> equals <em>false</em>, and the error is explained in the <code>error</code> field (e.g. ACCESS_TOKEN_INVALID).</p>
<ul>
<li>All methods in the Gateway API are case-insensitive.</li>
<p>We support <strong>GET</strong> and <strong>POST</strong> HTTP methods. Use either <ahref="https://en.wikipedia.org/wiki/Query_string">URL query string</a> or <em>application/json</em> or <em>application/x-www-form-urlencoded</em> for passing parameters in Telegram Gateway API requests.<br>On successful call, a JSON object containing the result will be returned.</p>
<p>Use this method to send a verification message. Charges will apply according to the pricing plan for each successful message delivery. Note that this method is always free of charge when used to send codes to your own phone number. On success, returns a <ahref="#requeststatus">RequestStatus</a> object.</p>
<tableclass="table">
<thead>
<tr>
<th>Parameter</th>
<th>Type</th>
<th>Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>phone_number</td>
<td>String</td>
<td>Yes</td>
<td>The phone number to which you want to send a verification message, in the <ahref="https://en.wikipedia.org/wiki/E.164">E.164</a> format.</td>
</tr>
<tr>
<td>request_id</td>
<td>String</td>
<td>Optional</td>
<td>The unique identifier of a previous request from <ahref="#checksendability">checkSendAbility</a>. If provided, this request will be free of charge.</td>
</tr>
<tr>
<td>sender_username</td>
<td>String</td>
<td>Optional</td>
<td>Username of the Telegram channel from which the code will be sent. The specified channel, if any, must be <ahref="https://telegram.org/verify">verified</a> and owned by the same account who owns the Gateway API token.</td>
</tr>
<tr>
<td>code</td>
<td>String</td>
<td>Optional</td>
<td>The verification code. Use this parameter if you want to set the verification code yourself. Only fully numeric strings between 4 and 8 characters in length are supported. If this parameter is set, <em>code_length</em> is ignored.</td>
</tr>
<tr>
<td>code_length</td>
<td>Integer</td>
<td>Optional</td>
<td>The length of the verification code if Telegram needs to generate it for you. Supported values are from 4 to 8. This is only relevant if you are not using the <em>code</em> parameter to set your own code. Use the <ahref="#checkverificationstatus">checkVerificationStatus</a> method with the <em>code</em> parameter to verify the code entered by the user.</td>
<td>Time-to-live (in seconds) before the message expires and is deleted. The message will not be deleted if it has already been read. If not specified, the message will not be deleted. Supported values are from 60 to 86400.</td>
<p>Use this method to check the ability to send a verification message to the specified phone number. If the ability to send is confirmed, a fee will apply according to the pricing plan. After checking, you can send a verification message using the <ahref="#sendverificationmessage">sendVerificationMessage</a> method, providing the <em>request_id</em> from this response.</p>
<p>Within the scope of a <em>request_id</em>, only one fee can be charged. Calling <ahref="#sendverificationmessage">sendVerificationMessage</a> once with the returned <em>request_id</em> will be free of charge, while repeated calls will result in an error. Conversely, calls that don't include a <em>request_id</em> will spawn new requests and incur the respective fees accordingly. Note that this method is always free of charge when used to send codes to your own phone number.</p>
<p>In case the message can be sent, returns a <ahref="#requeststatus">RequestStatus</a> object. Otherwise, an appropriate error will be returned. </p>
<tableclass="table">
<thead>
<tr>
<th>Parameter</th>
<th>Type</th>
<th>Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>phone_number</td>
<td>String</td>
<td>Yes</td>
<td>The phone number for which you want to check our ability to send a verification message, in the <ahref="https://en.wikipedia.org/wiki/E.164">E.164</a> format.</td>
<p>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. Even if you set the code yourself, it is recommended to call this method after the user has successfully entered the code, passing the correct code in the <em>code</em> parameter, so that we can track the conversion rate of your verifications. On success, returns a <ahref="#requeststatus">RequestStatus</a> object.</p>
<tableclass="table">
<thead>
<tr>
<th>Parameter</th>
<th>Type</th>
<th>Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>request_id</td>
<td>String</td>
<td>Yes</td>
<td>The unique identifier of the verification request whose status you want to check.</td>
</tr>
<tr>
<td>code</td>
<td>String</td>
<td>Optional</td>
<td>The code entered by the user. If provided, the method checks if the code is valid for the relevant request.</td>
<p>Use this method to revoke a verification message that was sent previously. Returns <em>True</em> if the revocation request was received. 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.</p>
<tableclass="table">
<thead>
<tr>
<th>Parameter</th>
<th>Type</th>
<th>Required</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>request_id</td>
<td>String</td>
<td>Yes</td>
<td>The unique identifier of the request whose verification message you want to revoke.</td>
<p>This object represents the status of a verification message request.</p>
<tableclass="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>request_id</td>
<td>String</td>
<td>Unique identifier of the verification request.</td>
</tr>
<tr>
<td>phone_number</td>
<td>String</td>
<td>The phone number to which the verification code was sent, in the <ahref="https://en.wikipedia.org/wiki/E.164">E.164</a> format.</td>
</tr>
<tr>
<td>request_cost</td>
<td>Float</td>
<td>Total request cost incurred by either <ahref="#checksendability">checkSendAbility</a> or <ahref="#sendverificationmessage">sendVerificationMessage</a>.</td>
</tr>
<tr>
<td>remaining_balance</td>
<td>Float</td>
<td><em>Optional.</em> Remaining balance in credits. Returned only in response to a request that incurs a charge.</td>
<p>This object represents the delivery status of a message.</p>
<tableclass="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>status</td>
<td>String</td>
<td>The current status of the message. One of the following:<br>- <strong>sent</strong>– the message has been sent to the recipient's device(s),<br>- <strong>read</strong>– the message has been read by the recipient,<br>- <strong>revoked</strong>– the message has been revoked.</td>
</tr>
<tr>
<td>updated_at</td>
<td>Integer</td>
<td>The timestamp when the status was last updated.</td>
<p>This object represents the verification status of a code.</p>
<tableclass="table">
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>status</td>
<td>String</td>
<td>The current status of the verification process. One of the following:<br>- <strong>code_valid</strong>– the code entered by the user is correct,<br>- <strong>code_invalid</strong>– the code entered by the user is incorrect,<br>- <strong>code_max_attempts_exceeded</strong>– the maximum number of attempts to enter the code has been exceeded,<br>- <strong>expired</strong>– the code has expired and can no longer be used for verification.</td>
</tr>
<tr>
<td>updated_at</td>
<td>Integer</td>
<td>The timestamp for this particular status. Represents the time when the status was last updated.</td>
</tr>
<tr>
<td>code_entered</td>
<td>String</td>
<td><em>Optional.</em> The code entered by the user.</td>
<p>The Telegram Gateway API can send delivery reports to a user-specified callback URL. When you include a <code>callback_url</code> parameter in your request, the API will send an HTTP POST request to that URL containing the delivery report for the message. The payload of the POST request will be a JSON object representing the <ahref="#requeststatus">RequestStatus</a> object.</p>
<p>Your URL must respond with HTTP status code <code>200</code> to acknowledge receipt of the report. Any other status code will be considered a failure, and the service will retry sending the same report up to 10 times with increasing delays between attempts. If all retries fail, the report will be considered lost.</p>
<p>All reports submitted to your <code>callback_url</code>, if you provided one, will also contain the following headers:</p>
<ul>
<li><code>X-Request-Timestamp</code>– A Unix timestamp indicating when the server submitted the report.</li>
<li><code>X-Request-Signature</code>– A server-generated signature needed to authenticate the report on your end.</li>
</ul>
<p>You can confirm the origin and verify the integrity of the reports you receive by comparing the signature contained in the <code>X-Request-Signature</code> header with the hexadecimal representation of the <ahref="https://en.wikipedia.org/wiki/Hash-based_message_authentication_code">HMAC-SHA-256</a> signature of the <strong>data-check-string</strong> with the <ahref="https://en.wikipedia.org/wiki/SHA-2">SHA256</a> hash of the API token shown in your Gateway account settings.</p>
<p>The <strong>data-check-string</strong> is a concatenation of the report timestamp as provided by the <code>X-Request-Timestamp</code> header, a <ahref="https://en.wikipedia.org/wiki/Newline">line feed character</a> ('\n', 0x0A) used as separator and the raw post body of the HTTP request.</p>
if (hex(HMAC_SHA256(data_check_string, secret_key)) == X-Request-Signature) {
// data is from Telegram
}</code></pre>
<blockquote>
<p>To prevent the use of outdated data, you should additionally check the <code>X-Request-Timestamp</code> header, which contains a Unix timestamp of when the relevant report was submitted by the server.</p>
</blockquote>
</div>
</div>
</div>
</div>
<divclass="footer_wrap">
<divclass="footer_columns_wrap footer_desktop">
<divclass="footer_column footer_column_telegram">
<h5>Telegram</h5>
<divclass="footer_telegram_description"></div>
Telegram is a cloud-based mobile and desktop messaging app with a focus on security and speed.
