# BLACKSMS Complete Developer API Reference

> Enterprise-grade Communications Infrastructure for Transactional SMS, 2FA OTP Verification, and WhatsApp Messaging in India.

- **Base URL:** `https://blacksms.in`
- **Protocol:** HTTPS (REST API, JSON Payloads)
- **Authentication:** `Authorization: <YOUR_API_KEY>` or API Key in request header
- **Response Format:** JSON (`application/json`)
- **Default Delivery Latency:** 1 to 3 seconds for OTP priority channels

---

## 1. Authentication & API Key

All API requests must include your BlackSMS API key.

```http
Authorization: YOUR_API_KEY
Content-Type: application/json
```

Generate or view your API key in your account dashboard at `https://blacksms.in/dashboard`.

---

## 2. API Endpoints

### 2.1 Send Transactional & OTP SMS (`POST /sms`)

Send SMS alerts, OTP verification codes, or promotional notifications.

**Endpoint:** `POST https://blacksms.in/sms`

#### Request Headers
| Header | Type | Description |
|---|---|---|
| `Authorization` | String | Your BlackSMS API key |
| `Content-Type` | String | Must be `application/json` |

#### Request Payload
```json
{
  "sender_id": "BLACKSMS",
  "variables_values": "123456",
  "numbers": "9876543210",
  "route": 1
}
```

#### Parameters Reference
| Parameter | Type | Required | Description |
|---|---|---|---|
| `sender_id` | String | Yes | Approved DLT Header / Sender ID (6 characters) |
| `variables_values` | String | Yes | Dynamic template variable value (e.g. OTP code `123456`) |
| `numbers` | String | Yes | 10-digit Indian recipient mobile number or comma-separated list |
| `route` | Integer | Yes | Route channel identifier (`1`, `2`, `3`, or `4`) |

#### Successful Response (`200 OK`)
```json
{
  "status": "success",
  "message_id": "MSG_9845612389",
  "destination": "9876543210",
  "credits_deducted": 1,
  "delivery_status": "queued"
}
```

---

### 2.2 WhatsApp OTP & Business Messaging (`POST /wasend.php` or `POST /wa.php`)

Deliver verification OTPs and notification messages via WhatsApp Business API channels.

**Endpoint:** `POST https://blacksms.in/wasend.php`

#### Request Payload
```json
{
  "api_key": "YOUR_API_KEY",
  "number": "9876543210",
  "message": "Your verification code is 654321. Valid for 10 minutes."
}
```

---

## 3. Code Examples

### cURL
```bash
curl -X POST https://blacksms.in/sms \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sender_id": "BLACKSMS",
    "variables_values": "123456",
    "numbers": "9876543210",
    "route": 1
  }'
```

### PHP (cURL / Guzzle)
```php
<?php
$apiKey = "YOUR_API_KEY";
$url = "https://blacksms.in/sms";

$payload = [
    "sender_id" => "BLACKSMS",
    "variables_values" => "123456",
    "numbers" => "9876543210",
    "route" => 1
];

$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => json_encode($payload),
    CURLOPT_HTTPHEADER => [
        "Authorization: " . $apiKey,
        "Content-Type: application/json"
    ]
]);

$response = curl_exec($ch);
curl_close($ch);

echo $response;
?>
```

### Python (`requests`)
```python
import requests

url = "https://blacksms.in/sms"
headers = {
    "Authorization": "YOUR_API_KEY",
    "Content-Type": "application/json"
}
payload = {
    "sender_id": "BLACKSMS",
    "variables_values": "123456",
    "numbers": "9876543210",
    "route": 1
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())
```

### Node.js (`fetch` / Axios)
```javascript
import fetch from 'node-fetch';

const response = await fetch('https://blacksms.in/sms', {
  method: 'POST',
  headers: {
    'Authorization': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    sender_id: 'BLACKSMS',
    variables_values: '123456',
    numbers: '9876543210',
    route: 1
  })
});

const data = await response.json();
console.log(data);
```

---

## 4. DLT Compliance & Telecom Regulations

Pursuant to TRAI TCCCPR 2018 regulations in India:
- All business entity senders must possess a registered DLT Principal Entity ID.
- SMS templates and Sender IDs (Headers) must be pre-approved on DLT telecom portals (Jio, Airtel, Vodafone Idea, BSNL).
- Non-DLT traffic can be delivered via compliant transactional OTP backup channels provided by BLACKSMS.

---

## 5. Pricing Schedule (INR)

| Recharge Tier | Regular Bulk SMS | WhatsApp SMS |
|---|---|---|
| ₹100 – ₹3,999 | ₹0.30 / SMS | ₹0.30 / msg |
| ₹4,000 – ₹14,999 | ₹0.25 / SMS | ₹0.22 / msg |
| ₹15,000 – ₹49,999 | ₹0.20 / SMS | ₹0.15 / msg |
| ₹50,000 – ₹199,999 | ₹0.18 / SMS | ₹0.10 / msg |
| ₹200,000 – ₹599,999 | ₹0.17 / SMS | ₹0.06 / msg |
| ₹600,000+ | ₹0.16 / SMS | ₹0.04 / msg |

---

## 6. Official Resources & Documentation

- **Full API Documentation:** `https://blacksms.in/docs`
- **Sitemap:** `https://blacksms.in/sitemap.xml`
- **llms.txt Summary:** `https://blacksms.in/llms.txt`
- **Support Contact:** `support@blacksms.in` | Telegram: `https://t.me/blacksmsindia` | Instagram: `https://www.instagram.com/blacksmsindia`