GetOTP Documentation

Telegram OTP

The Telegram OTP allows you to perform OTP via Telegram.

Request for Telegram OTP API

To request for Telegram OTP, make a POST request to our OTP endpoint.

https://api.otp.dev/v1/verifications

With the following Basic HTTP verification method:

Description	Required	Data Type	Example
Your API Key	Yes	String	mtbi2w4hlendfpxa1igthcu5p6mzxf7k

Note

Grab your API key from this page

With the following parameters:

Name	Description	Required	Data Type	Example
channel	The channel of verification message 'telegram'	Yes	String	telegram
phone	Phone number as digits without spaces or special characters, beginning with the country dialing code	Yes	String	60123456789
code_length	The length of the code, which falls within the range of 4 to 8 characters.	At least one of the following is required: 'code_length' or 'code'.	String	4
code	The 'code' field accepts only digits and must be between 4 to 8 characters in length.	At least one of the following is required: 'code_length' or 'code'.	String	1234
ttl_in_seconds	For 'TELEGRAM' channel ttl(time to live) must be between 60 to 86400 seconds, default is 60 seconds	No	Number	70
number_formatting	Defaults to true. If provided, leading 0 after the country code and before the network code will be removed.	No	Boolean	True
payload	The value provided with this parameter will be sent back to the client through the Webhook URL. Length ≤ 500	No	String	Telegram Payload

Note

Notes on the phone parameter:

You must provide a phone number as digits without spaces or special characters, beginning with the country dialing code.

Examples

Below is an example request using cURL:

curl --request POST \
     --url https://api.otp.dev/v1/verifications \
     --header 'X-OTP-Key: {YOUR_API_KEY}' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
    "data": {
        "channel": "telegram",
        "phone": "60123456789",
        "code_length": 5
    }
}
'

The response would be a JSON structure, returned with HTTP 200 Codestatus code:

{
  "account_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "message_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "phone": "60123456789",
  "create_date": "2025-09-11 05:43:58",
  "expire_date": "2025-09-11 07:43:58"
}

Response data details:

Name	Description	Data Type	Example
account_id	The unique identifier of the account	String	731873df-a1c7-4be6-8ad8-e530abd717d4
message_id	The unique identifier of the message	String	34d18fb8-31e8-4f42-97ff-a8009f232280
phone	Recipient's phone number	String	60123456789
create_date	Creation date of the verification in UTC, formatted as yyyy-mm-dd hh:mm:ss	String	2025-09-11 05:43:58
expire_date	Expiration date of the verification in UTC, formatted as yyyy-mm-dd hh:mm:ss	String	2025-09-11 07:43:58

If there is an error with the API call, you will receive a JSON response with 400+ status code, error code and message.

{
  "errors": [{
    "timestamp": "2025-09-11 05:49:48",
    "path": "/v1/verifications",
    "method": "POST",
    "status": 400,
    "message": "Invalid code length",
    "code": "1623"
  }]
}

Please refer to this table for details:

Error Code	Description	HTTP Code
1523	Invalid recipient number(s)	400
1621	'phone' is missing	400
1623	Invalid code length.The code length should be minimum 4 and maximum 8.	400
1629	Provide either 'data.code' or 'data.code_length' but not both	400
1631	When 'data.channel' is not VOICE 'data.code' must be valid and 4 to 8 characters long	400
1632	'data.code' should be numeric if provided	400
1640	data.ttl_in_seconds' must be numeric	400
1648	'data.phone' must be E164 format for the telegram channel	400
1649	'data.ttl_in_seconds' must be between 60 and 86400 seconds for Telegram	400
1705	Invalid payload	400