# WhatsApp OTP

> Copy code बटन के साथ WhatsApp पर वेरिफ़िकेशन कोड भेजें

- पेज: https://tbit.app/hi/docs/api/otp
- Base URL: `https://rest-api.tbit.app/v1`
- ऑथेंटिकेशन: हर request में आपकी key के साथ `X-API-Key` header (उदाहरण इसे `TBIT_API_KEY` environment variable से पढ़ते हैं)

## परिचय

TBit एक नंबर वाला कोड बनाता है, उसे आपके एजेंट की लाइन से authentication टेम्पलेट (Copy code बटन) के साथ WhatsApp पर भेजता है और रिस्पॉन्स में आपको लौटा देता है। आप इसे अपने सिस्टम में जाँच सकते हैं या /v1/otp/verify से TBit से जँचवा सकते हैं। OTP मुफ़्त हैं और आपके टेम्पलेट कोटा में नहीं गिने जाते।

## Endpoints

| Method | Path | विवरण |
| --- | --- | --- |
| `POST` | `/v1/otp/template` | Authentication टेम्पलेट बनाएँ |
| `GET` | `/v1/otp/template` | OTP टेम्पलेट का स्टेटस |
| `POST` | `/v1/otp/send` | कोड बनाएँ और भेजें |
| `POST` | `/v1/otp/verify` | कोड वेरिफ़ाई करें (वैकल्पिक) |

## ज़रूरतें

आपके एजेंट से जुड़ी एक WhatsApp लाइन चाहिए। Meta authentication टेम्पलेट सिर्फ़ उन बिज़नेस को देता है जो Meta Business में वेरिफ़ाइड हैं (Business settings → Security center); वेरिफ़िकेशन के बिना टेम्पलेट बनाने पर META_ERROR आता है: "does not have permission to create message template"। कोड उसी एजेंट की लाइन के नंबर से जाता है जिसकी API key है।

## टेम्पलेट बनाएँ

हर भाषा के लिए एक बार (नाम tbit_otp_<भाषा>)। टेक्स्ट Meta लिखता है और बदला नहीं जा सकता: कोड, एक सुरक्षा सलाह और फ़ुटर में वैधता। वैकल्पिक फ़ील्ड: language (डिफ़ॉल्ट es), code_expiration_minutes (1 से 90, डिफ़ॉल्ट 10) और channel_id अगर एजेंट की कई लाइनें हैं। टेम्पलेट पहले से हो तो created: false और उसका स्टेटस लौटता है। Meta आम तौर पर इसे कुछ सेकंड में मंज़ूर कर देता है।

`POST /v1/otp/template`

```bash
curl -X POST "https://rest-api.tbit.app/v1/otp/template" \
  -H "X-API-Key: $TBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "language": "es",
    "code_expiration_minutes": 10
  }'
```

Response:

```json
{
  "data": {
    "created": true,
    "template": {
      "id": "6ac60aeaa2a9ed0cd9ca7fd4",
      "name": "tbit_otp_es",
      "language": "es",
      "status": "PENDING",
      "rejected_reason": null,
      "code_expiration_minutes": 10,
      "channel_id": "691deef351c7513d0c6a2a6f"
    }
  }
}
```

## टेम्पलेट का स्टेटस

एजेंट के OTP टेम्पलेट की लिस्ट। जो अभी मंज़ूर नहीं हुए उन्हें Meta से लाइव चेक किया जाता है: status PENDING, APPROVED या REJECTED होता है।

`GET /v1/otp/template`

```bash
curl "https://rest-api.tbit.app/v1/otp/template" \
  -H "X-API-Key: $TBIT_API_KEY"
```

Response:

```json
{
  "data": [
    {
      "id": "6ac60aeaa2a9ed0cd9ca7fd4",
      "name": "tbit_otp_es",
      "language": "es",
      "status": "APPROVED",
      "rejected_reason": null,
      "code_expiration_minutes": 10,
      "channel_id": "691deef351c7513d0c6a2a6f"
    }
  ]
}
```

## कोड भेजें

to देश कोड के साथ फ़ोन नंबर है (स्पेस, डैश और + चलते हैं)। length 4 से 8 अंक (डिफ़ॉल्ट 6) और language टेम्पलेट चुनता है (डिफ़ॉल्ट es)। रिस्पॉन्स में कोड आता है ताकि आपका सिस्टम उसे इस्तेमाल करे; कोड चैट हिस्ट्री में सेव नहीं होता।

`POST /v1/otp/send`

```bash
curl -X POST "https://rest-api.tbit.app/v1/otp/send" \
  -H "X-API-Key: $TBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+57 300 123 4567",
    "length": 6
  }'
```

Response:

```json
{
  "data": {
    "request_id": "be4ffa6c-f45a-4410-b38a-882bd3edd9b3",
    "to": "573001234567",
    "code": "054381",
    "expires_in_minutes": 10,
    "expires_at": "2026-10-07T09:17:26.278Z"
  }
}
```

## कोड वेरिफ़ाई करें

वैकल्पिक: अगर आप कोड सेव नहीं करना चाहते तो TBit उसे जाँचता है। हर कोड एक ही बार चलता है और टेम्पलेट के साथ एक्सपायर होता है। 5 गलत कोशिशों के बाद वह रद्द हो जाता है और नया माँगना पड़ता है। reason हो सकता है invalid_code (attempts_left के साथ), too_many_attempts या expired_or_not_found। सही कोड पर { "valid": true } आता है।

`POST /v1/otp/verify`

```bash
curl -X POST "https://rest-api.tbit.app/v1/otp/verify" \
  -H "X-API-Key: $TBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "573001234567",
    "code": "054381"
  }'
```

Response:

```json
{
  "data": {
    "valid": false,
    "reason": "invalid_code",
    "attempts_left": 4
  }
}
```

## लिमिट

हर फ़ोन पर: हर 30 सेकंड में एक भेजना और एक घंटे में 5। इससे ज़्यादा पर 429 OTP_RATE_LIMITED और Retry-After हेडर आता है। हर API key पर प्रति मिनट 100 रिक्वेस्ट की सामान्य लिमिट भी लागू है।

## एरर

| कोड | HTTP | कब |
| --- | --- | --- |
| `TEMPLATE_NOT_APPROVED` | 409 | उस भाषा का OTP टेम्पलेट नहीं है या Meta ने अभी मंज़ूर नहीं किया |
| `OTP_RATE_LIMITED` | 429 | उस फ़ोन के लिए बहुत ज़्यादा कोड; Retry-After के बाद फिर कोशिश करें |
| `META_ERROR` | 422 | Meta ने टेम्पलेट रिजेक्ट किया (जैसे बिना वेरिफ़िकेशन वाला बिज़नेस) |
| `SEND_FAILED` | 422 | Meta ने मैसेज भेजना स्वीकार नहीं किया |
| `VALIDATION_ERROR` | 400 | गलत body: फ़ोन, लंबाई, भाषा या कोड |
| `NOT_FOUND` | 404 | WhatsApp लाइन नहीं है या इस एजेंट की नहीं है |
