SMSTwins Integration API

# Recommended
Authorization: ApiKey sk_live_...

# Compatible with OAuth2/Bearer clients
Authorization: Bearer sk_live_...

# Alternative header (Postman, many HTTP libraries)
X-API-Key: sk_live_...

# Simple API scripts only
GET /simple?action=balance&api_key=sk_live_...

GET /countries
GET /countries?withStock=true     # include availableCount per country

GET /services
GET /services?withStock=true      # countriesWithStock, totalAvailable

GET /operators?country=6

GET /prices?service=tg&country=6
GET /prices?service=wa              # all countries for WhatsApp

GET /prices/quote?service=tg&country=6   # exact activation price for one pair

GET /rental-options?service=tg    # required — per-country rental pricing & stock
GET /rental-quote?service=tg&country=6&hours=24

# Request a number
POST /activations
{
  "service": "tg",
  "country": 6,
  "operator": "telkomsel",      // optional
  "maxPrice": 0.50        // optional — reject if price exceeds this
}

# Response
{
  "id": "clx...",
  "phone": "+6281234567890",
  "status": "WAITING_SMS",
  "purchasePrice": 0.35,
  "price": 0.35,
  "amountCharged": 0.35,
  "canCancel": false,
  "sms": null,
  "service": { "code": "tg", "name": "Telegram" },
  "country": { "code": "ID", "name": "Indonesia", "flag": "🇮🇩" },
  "expiresAt": "2026-06-19T18:30:00.000Z"
}

GET /activations                  # list all (optional ?status=WAITING_SMS)
GET /activations/active           # waiting for SMS only
GET /activations/{id}             # poll for code — sms.code when received
POST /activations/{id}/cancel     # cancel & refund amountCharged (after 1 min, before SMS)

GET /activations/reactivatable    # numbers you can reuse (last 24h, SIM online)
POST /activations/{id}/reactivate # new 30-min session on same SIM

GET /rentals/durations          # [1, 6, 24, 168, 720]
GET /rentals                    # your rentals

POST /rentals
{
  "service": "tg",
  "country": 6,
  "hours": 24
}

POST /rentals/{id}/extend
{ "hours": 24 }                 # same allowed hour presets

POST /rentals/{id}/cancel
# Full refund of purchasePrice if no OTP — only within 30 min of purchase

PUT /webhooks
{
  "url": "https://your-server.com/smstwins-hook",
  "events": ["activation.assigned", "sms.received", "activation.completed"]
}

GET /webhooks                     # current config
DELETE /webhooks                  # disable

# Payload shape
{
  "event": "sms.received",
  "timestamp": "2026-06-19T12:00:00.000Z",
  "data": { ... }
}

# Node.js verification
const crypto = require('crypto');
const expected = crypto.createHmac('sha256', WEBHOOK_SECRET)
  .update(rawBody)
  .digest('hex');
if (expected !== req.headers['x-smstwins-signature']) throw new Error('Invalid');

GET /simple?action=balance&api_key=sk_live_...
→ SMSTWINS_OK:BALANCE:25.50

GET /simple?action=request_number&service=tg&country=6&max_price=0.50&api_key=...
→ SMSTWINS_OK:NUMBER:{id}:{phone}:{price}

GET /simple?action=check_status&id={activationId}&api_key=...
→ SMSTWINS_OK:CODE:123456 | SMSTWINS_OK:WAITING | SMSTWINS_OK:CANCELLED

GET /simple?action=cancel_number&id={id}&api_key=...
→ SMSTWINS_OK:CANCELLED:{refunded}

GET /simple?action=list_countries&api_key=...
GET /simple?action=list_services&api_key=...
GET /simple?action=list_prices&service=tg&api_key=...   # purchasePrice per row
GET /simple?action=get_price&service=tg&country=6&api_key=...

GET /simple?action=list_rental_options&service=tg&api_key=...
GET /simple?action=get_rental_price&service=tg&country=6&hours=24&api_key=...
GET /simple?action=rent_number&service=tg&country=6&hours=1&api_key=...
→ SMSTWINS_OK:RENTAL:{id}:{phone}:{purchasePrice}

GET /simple?action=extend_rental&id={rentalId}&hours=24&api_key=...
→ SMSTWINS_OK:EXTENDED:{id}:{totalPaid}

GET /simple?action=cancel_rental&id={rentalId}&api_key=...
→ SMSTWINS_OK:CANCELLED:{refunded}

{
  "statusCode": 400,
  "message": "Insufficient balance",
  "error": "Bad Request"
}

GET /user/balance
→ { "balance": 25.50 }

npm install @smstwins/sdk
pip install smstwins-sdk

import { SMSTwinsClient } from '@smstwins/sdk';

const client = new SMSTwinsClient({
  apiKey: 'sk_live_...',
  baseUrl: 'https://smstwins.com/v1',
});

const balance = await client.getBalance();
const activation = await client.requestNumber('tg', 6, { maxPrice: 0.5 });
const code = await client.waitForCode(activation.id, 120000);
await client.cancelActivation(activation.id);

// Simple API from SDK
const text = await client.simple('balance');

WebSocket URL: wss://smstwins.com/gateway
Library: socket.io-client

// 1. Connect
const socket = io('https://smstwins.com/gateway', {
  path: '/socket.io',
  transports: ['websocket', 'polling'],
});

// 2. Authenticate with device token from dashboard
socket.emit('auth', { deviceToken: 'your-96-char-hex-token', version: '1.0.0' });
socket.on('auth_ok', (data) => console.log('Online', data));
socket.on('auth_error', (err) => console.error(err));

// 3. Heartbeat every 30s
setInterval(() => socket.emit('heartbeat', {}), 30000);

// 4. Sync SIM inventory
socket.emit('numbers_sync', {
  numbers: [
    { phone: '+6281234567890', countryId: 6, iccid: 'optional' },
  ],
});
socket.on('numbers_sync_ack', (result) => console.log(result));

// 5. Forward incoming SMS
socket.emit('sms_received', {
  phone: '+6281234567890',
  text: 'Your Telegram code is 12345',
});
socket.on('sms_ack', (result) => console.log(result));