Routee Telegram API

The Routee Telegram API enables any service to send authorization codes through Telegram instead of traditional SMS, offering a more affordable, secure, and reliable alternative.

Base URL https://connect.routee.net/telegram

Available resources

https://docs.routee.net/reference/perform-a-lookup-enquiry-for-a-mobile-number-copy

https://docs.routee.net/reference/send-verification-message

https://docs.routee.net/reference/revoke-verification-message

https://docs.routee.net/reference/check-verification-status

Send Verification Message [/]

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 free of charge when used to send codes to your own phone number.

Endpoint API Reference: - LINK HERE

Request Attributes

• phone_number (string, required) - The phone number in E.164 format (e.g., +391234567890).
• request_id (string, optional) - Unique identifier from the checkSendAbility method.
• sender_username (string, optional) - Username of the Telegram channel.
• code (string, optional) - Custom verification code (4-8 numeric characters).
• code_length (number, optional) - Length of the generated verification code (4-8).
• callback_url (string, optional) - HTTPS URL to receive delivery reports.
• payload (string, optional) - Custom payload (0-128 bytes).
• ttl (number, optional) - Time-to-live in seconds (60-86400).

Check Send Ability [/checkSendAbility]

Before sending a message, you can optionally use the checkSendAbility method to verify if the user you’re targeting can receive messages on Telegram. This is helpful when you’ve generated a code but want to confirm it can be delivered before using the Routee API to send it.

If the method confirms that the user can receive messages, you will be charged in advance for one message, even if you don’t end up sending it. However, if the method returns an error (e.g., because the user cannot receive codes), you won’t be charged.

If the check is successful and you decide to send the message, make sure to use the request_id provided by the checkSendAbility method to avoid being charged again for the same message.

Request Attributes

• phone_number (string, required) - The phone number in E.164 format (e.g., +306974444444).

Response Attributes

• request_id (string, optional) - Unique identifier from the checkSendAbility method.

Revoke Verification Message [/revokeVerificationMessage]

Use this method to revoke a verification message that was sent previously. Returns True 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.

Request Attributes

• request_id (string, optional) - Unique identifier from the checkSendAbility method.

Check Verification Status [/checkVerificationStatus]

Use this method to check the status of a verification message that was sent earlier. If the code was generated by Telegram, you can also verify if the code entered by the user is correct. Even if you set the code manually, it’s recommended to call this method after the user successfully enters the code. Pass the correct code in the code parameter so we can track the conversion rate of your verifications.

On success, the method will return a RequestStatus object.

Endpoint API Reference: - LINK HERE

Request Attributes

• request_id (string, required) - The unique identifier of the verification request whose status you want to check.
• code (string, optional) - The code entered by the user. If provided, the method checks if the code is valid for the relevant request.

Reporting - Webhooks

The Routee Telegram API can send delivery reports to a callback URL that you specify. When you include the callback_url parameter in your request, the API will send an HTTP POST request to that URL with the delivery report for the message. The payload of the POST request will contain a JSON object representing the RequestStatus object.

Your URL must respond with an HTTP status code 200 to confirm receipt of the report. Any other status code will be treated as a failure, and the service will attempt to resend the report up to 10 times with increasing delays. If all attempts fail, the report will be considered lost.

Checking Report Integrity

If you provided a callback_url, all reports sent to it will include the following headers:
• X-Request-Timestamp – A Unix timestamp indicating when the server submitted the report.
• X-Request-Signature – A server-generated signature used to authenticate the report on your end.

To verify the integrity and origin of the report, compare the signature in the X-Request-Signature header with the hexadecimal representation of the HMAC-SHA-256 signature. This signature is created from the following data:
1. The timestamp from the X-Request-Timestamp header.
2. A newline character (\n, 0x0A) as a separator.
3. The raw body of the HTTP POST request.

You can use the SHA256 hash of the API token from your Gateway account settings to generate this signature.

Payload Example:

{
  "request_id": "String",
  "phone_number": "String",
  "request_cost": "Float",
  "remaining_balance": "Float",
  "delivery_status": "DeliveryStatus",
  "verification_status": "VerificationStatus",
  "payload": "String"
}

List of Available Objects for Routee Telegram API

All types used in the Routee telegram API responses are represented as JSON objects. It is safe to use 32-bit signed integers for storing all Integer fields unless otherwise noted.

Optional fields may not be returned when irrelevant.

RequestStatus Object

This object represents the status of a verification message request.

• request_id (String): Unique identifier of the verification request.
• phone_number (String): The phone number to which the verification code was sent, in the E.164 format.
• request_cost (Float): Total request cost incurred by either checkSendAbility or sendVerificationMessage.
• remaining_balance (Float, Optional): Remaining balance in credits. Returned only in response to a request that incurs a charge.
• delivery_status (DeliveryStatus, Optional): The current message delivery status. Returned only if a verification message was sent to the user.
• verification_status (VerificationStatus, Optional): The current status of the verification process.
• payload (String, Optional): Custom payload if it was provided in the request (0-256 bytes).

DeliveryStatus Object

This object represents the delivery status of a message.

• status (String): The current status of the message. One of the following:
  • sent: The message has been sent to the recipient's device(s).
  • read: The message has been read by the recipient.
  • revoked: The message has been revoked.
• updated_at (Integer): The timestamp when the status was last updated.

VerificationStatus Object

This object represents the verification status of a code.

• status (String): The current status of the verification process. One of the following:
  • code_valid: The code entered by the user is correct.
  • code_invalid: The code entered by the user is incorrect.
  • code_max_attempts_exceeded: The maximum number of attempts to enter the code has been exceeded.
  • expired: The code has expired and can no longer be used for verification.
• updated_at (Integer): The timestamp for this particular status. Represents the time when the status was last updated.
• code_entered (String, Optional): The code entered by the user.