Virtual numbers for Telegram — in your bot, automatically

Documentation overview

Read these documents to connect your system to our servers and buy numbers automatically. Prices, stock and balance are exactly the same as in the bot. All amounts are in USD.

Base URL

Authentication

Send the key in the X-Api-Key header (recommended — keys in URLs end up in server logs) or as the api_key parameter. Never share your key; if it leaks, press ♻️ Change key in the bot.

Methods

All methods: GET (or POST) to the base URL with the action parameter.

{
  "ok": true,
  "balance": 12.5,
  "spent": 3.2,
  "currency": "USD",
  "api_usage": {"requests_today": 41, "limit": 5000, "remaining": 4959}
}

{
  "ok": true, "currency": "USD", "count": 182,
  "countries": [
    {"country": "BD", "dial": "880", "name": "Bangladesh", "price": 0.35, "stock": 2146},
    {"country": "KE", "dial": "254", "name": "Kenya", "price": 0.42, "stock": null}
  ]
}

{
  "ok": true,
  "id": 1532,
  "phone": "8801712345678",
  "country": "BD",
  "price": 0.35,
  "balance": 12.15
}

{"ok": true, "id": 1532, "phone": "8801712345678", "status": "wait", "expires_in": 1650}

{"ok": true, "id": 1532, "phone": "8801712345678", "status": "ok", "code": "52814", "password": "x7kq2"}

{
  "ok": true, "id": 1532, "phone": "8801712345678", "country": "BD",
  "price": 0.35, "status": "ok", "code": "52814", "password": null,
  "refunded": 0.0, "created_at": "2026-10-14 10:15:02"
}

{"ok": true, "callback": "https://example.com/hook"}

Callback

When a code arrives or a number is cancelled we send POST with JSON (fields as in getStatus + event: code / cancelled). Verify the X-Signature header: hex HMAC-SHA256 of the raw body with your API key. Answer with any 2xx — otherwise we retry up to 4 times. Handle it idempotently by id.

POST https://example.com/hook
Content-Type: application/json
X-Signature: 5f0c…e91a

{"event": "code", "ok": true, "id": 1532, "phone": "8801712345678", "country": "BD", "price": 0.35,
 "status": "ok", "code": "52814", "password": null, "refunded": 0.0, "created_at": "2026-10-14 10:15:02"}

Examples

Buy a number and wait for the code:

# 1) buy
curl -H "X-Api-Key: YOUR_API_KEY" "https://moonum-tg.com/?action=getNumber&country=BD&max_price=0.40&request_id=order-1001"

# 2) code (repeat every 5–10 s while status = wait)
curl -H "X-Api-Key: YOUR_API_KEY" "https://moonum-tg.com/?action=getCode&id=1532"

<?php
$key = 'YOUR_API_KEY';
function api(array $q) {
    global $key;
    $ctx = stream_context_create(['http' => ['header' => "X-Api-Key: $key\r\n"]]);
    return json_decode(file_get_contents('https://moonum-tg.com/?' . http_build_query($q), false, $ctx), true);
}

$n = api(['action' => 'getNumber', 'country' => 'BD', 'max_price' => 0.40, 'request_id' => 'order-1001']);
if (!$n['ok']) exit($n['error']);
echo "Number: {$n['phone']}\n";

do {
    sleep(7);
    $c = api(['action' => 'getCode', 'id' => $n['id']]);
} while ($c['ok'] && $c['status'] === 'wait');
echo $c['status'] === 'ok' ? "Code: {$c['code']}\n" : "No code\n";

import time, requests

API = 'https://moonum-tg.com/'
H = {'X-Api-Key': 'YOUR_API_KEY'}

n = requests.get(API, headers=H, params={'action': 'getNumber', 'country': 'BD',
                                        'max_price': 0.40, 'request_id': 'order-1001'}).json()
if not n['ok']:
    raise SystemExit(n['error'])
print('Number:', n['phone'])

while True:
    time.sleep(7)
    c = requests.get(API, headers=H, params={'action': 'getCode', 'id': n['id']}).json()
    if not c['ok'] or c['status'] != 'wait':
        break
print('Code:', c.get('code'))

Errors

On error: {"ok": false, "error": "CODE", "message": "..."} with a matching HTTP status.

Important rules

• If the code does not arrive within 30 minutes, the number is cancelled. The payment is not refunded — the number counts as delivered.
• If no number is issued at all, nothing is charged.
• Numbers may be frozen or banned by Telegram — this is not grounds for a refund.
• Using the API means you accept the bot's Terms of Use.