> ## Documentation Index > Fetch the complete documentation index at: https://docs.otpbay.com/llms.txt > Use this file to discover all available pages before exploring further. # Send a Telegram code > Sends a one-time code to the Telegram account registered to `to`. Pass your own `code`, or leave it out and Telegram generates one with the code length from your Telegram settings. If Telegram doesn't deliver the code before it expires, the charge is refunded. ## OpenAPI ````yaml api-reference/openapi.yaml POST /messages/telegram openapi: 3.1.0 info: title: OTPBay API version: 1.0.0 description: >- Send one-time passwords over Telegram and SMS, verify the codes your users enter, and send transactional SMS from your own sender ID. contact: name: OTPBay support email: hello@otpbay.com servers: - url: https://api.otpbay.com/v1 description: Production security: - bearerAuth: [] tags: - name: Project description: The project that owns the API key. - name: Verify description: >- Send a code and check it. OTPBay generates the code and falls back from Telegram to SMS. - name: SMS description: Send any text message from one of your approved sender IDs. - name: Telegram description: Send a one-time code to a Telegram account through the Telegram Gateway. paths: /messages/telegram: post: tags: - Telegram summary: Send a Telegram code description: >- Sends a one-time code to the Telegram account registered to `to`. Pass your own `code`, or leave it out and Telegram generates one with the code length from your Telegram settings. If Telegram doesn't deliver the code before it expires, the charge is refunded. operationId: sendTelegramCode requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SendTelegramRequest' example: to: '+14155552671' metadata: user_id: usr_1042 responses: '201': description: The code was handed to Telegram. content: application/json: schema: $ref: '#/components/schemas/TelegramMessage' example: sid: TG6650c52ad3e4f5a6b7c8d9e0 status: sent verification_status: null to: '+14155552671' code_length: 6 cost: '0.02' date_created: '2026-09-26T10:22:40.011Z' expires_at: '2026-09-26T10:27:40.011Z' delivered_at: null verified_at: null metadata: user_id: usr_1042 '400': $ref: '#/components/responses/InvalidJson' '401': $ref: '#/components/responses/Unauthorized' '402': $ref: '#/components/responses/InsufficientBalance' '403': $ref: '#/components/responses/ChannelDisabled' '422': description: >- `INVALID_REQUEST_BODY` or `TELEGRAM_REJECTED` (for example, the number has no Telegram account). content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: TELEGRAM_REJECTED message: Telegram rejected the request (PHONE_NUMBER_NOT_FOUND). '503': description: >- `TELEGRAM_UNAVAILABLE` or `TELEGRAM_NOT_CONFIGURED` — try again later. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: TELEGRAM_UNAVAILABLE message: Telegram is unavailable right now. Try again later. components: schemas: SendTelegramRequest: type: object required: - to additionalProperties: false properties: to: $ref: '#/components/schemas/PhoneNumber' code: type: string pattern: ^\d{4,8}$ description: >- Code to send, 4–8 digits. Leave it out and Telegram generates a code with the code length from your Telegram settings; then check it with Verify a Telegram code. example: '482913' metadata: $ref: '#/components/schemas/Metadata' callback: $ref: '#/components/schemas/CallbackUrl' TelegramMessage: type: object required: - sid - status - verification_status - to - code_length - cost - date_created - expires_at - delivered_at - verified_at - metadata properties: sid: type: string pattern: ^TG[a-f0-9]{24}$ description: Unique Telegram code ID. example: TG6650c52ad3e4f5a6b7c8d9e0 status: type: string enum: - sending - sent - delivered - read - expired - revoked - failed description: >- Delivery status reported by Telegram. `failed` means the code never reached Telegram. verification_status: type: - string - 'null' enum: - code_valid - code_invalid - code_max_attempts_exceeded - expired - null description: Result of the latest code check, or `null` before the first check. to: $ref: '#/components/schemas/PhoneNumber' code_length: type: integer description: Number of digits in the code. example: 6 cost: allOf: - $ref: '#/components/schemas/Money' description: What this code currently costs. `0.00` after a refund. example: '0.02' date_created: type: string format: date-time expires_at: type: string format: date-time delivered_at: type: - string - 'null' format: date-time verified_at: type: - string - 'null' format: date-time metadata: $ref: '#/components/schemas/Metadata' last_error: type: string description: Why the code couldn't be sent. Only present when there is one. Error: type: object required: - error properties: error: type: object required: - code - message properties: code: type: string description: >- Stable, machine-readable error code. Branch on this, not on `message`. example: INSUFFICIENT_BALANCE message: type: string description: Human-readable explanation. The wording can change. example: Insufficient balance for this verification. PhoneNumber: type: string description: >- Destination phone number in international format. OTPBay normalizes it to E.164, so `+1 (415) 555-2671` becomes `+14155552671`. example: '+14155552671' Metadata: type: object description: >- Your own key-value data, returned in responses and webhooks. At most 32 keys of 1–64 characters. Values are strings (up to 512 characters), numbers or booleans. maxProperties: 32 additionalProperties: oneOf: - type: string maxLength: 512 - type: number - type: boolean example: user_id: usr_1042 CallbackUrl: type: string format: uri maxLength: 2048 description: >- Public `http` or `https` URL that receives [status webhooks](/webhooks). Localhost, private and link-local addresses are rejected. Defaults to the channel's default callback from project settings. example: https://example.com/webhooks/otpbay Money: type: string pattern: ^\d+\.\d{2}$ description: Amount in US dollars as a decimal string. example: '0.02' responses: InvalidJson: description: '`INVALID_JSON` or `INVALID_E164`.' content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: INVALID_JSON message: Invalid JSON body Unauthorized: description: '`MISSING_API_KEY` or `INVALID_API_KEY`.' content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: INVALID_API_KEY message: Invalid API key. InsufficientBalance: description: '`INSUFFICIENT_BALANCE` — top up your project balance.' content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: INSUFFICIENT_BALANCE message: Insufficient balance for this SMS destination. ChannelDisabled: description: >- `CHANNEL_DISABLED` — the channel is turned off in project settings, or `IP_NOT_ALLOWED`. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: CHANNEL_DISABLED message: SMS is turned off for this project. securitySchemes: bearerAuth: type: http scheme: bearer description: >- Your project API key, sent as `Authorization: Bearer otp_live_...`. Create keys on the **API Keys** page of the dashboard. ````