सत्यापन भेजना

किसी उपयोगकर्ता के सत्यापन के लिए दो कॉल चाहिए। POST /v1/verify/verifications किसी ईमेल पते या फ़ोन नंबर पर सत्यापन कोड भेजता है। POST /v1/verify/verifications/check उपयोगकर्ता का दर्ज किया गया मान जमा करता है और बताता है कि वह मेल खाया या नहीं। Bird कोड बनाता है, उसे API प्रतिक्रिया में नहीं लौटाता, और समाप्ति तथा प्रयास की सीमाएँ लागू करता है।

कोड भेजें

सबसे छोटे मान्य अनुरोध में केवल एक to प्राप्तकर्ता होता है:

const verification = await bird.verify.verifications.create({
  to: { phone_number: "+15551234567" },
});
console.log(verification.id, verification.status);

verification = client.verify.verifications.create(to={"phone_number": "+15551234567"})
print(verification.id, verification.status)

verification, err := client.Verify.Verifications.Create(context.Background(), bird.VerifyVerificationsCreateParams{
	To: bird.VerificationTo{PhoneNumber: bird.String("+15551234567")},
})
if err != nil {
	log.Fatal(err)
}
fmt.Println(verification.Id, *verification.Status)

$verification = $bird->verify->verifications->create(
    (new VerificationCreateRequest())->setTo((new VerificationTo())->setPhoneNumber('+15551234567')),
);
echo $verification->getId(), ' ', $verification->getStatus();

bird verify verifications create --body-file - <<'JSON'
{
  "to": {
    "phone_number": "+15551234567"
  },
  "metadata": {
    "correlation_id": "signup-7f3a"
  }
}
JSON

curl -X POST https://us1.platform.bird.com/v1/verify/verifications \
  -H "Authorization: Bearer bk_us1_..." \
  -H "Content-Type: application/json" \
  -d '{
    "to": { "phone_number": "+15551234567" }
  }'

अपना क्षेत्रीय होस्ट (https://us1.platform.bird.com या https://eu1.platform.bird.com) उसी से मेल खाती bk_{region}_... कुंजी के साथ इस्तेमाल करें।

प्राप्तकर्ता

to प्राप्तकर्ता की पहचान email से, E.164 फ़ॉर्मेट में phone_number से, या दोनों से करता है। ईमेल पता देने पर ईमेल से डिलीवरी चालू होती है। फ़ोन नंबर से उसके गंतव्य देश में उपलब्ध चैनल तय होते हैं, उस क्रम में जो देश कॉन्फ़िगरेशन में सेट है। ज़्यादातर देश SMS से पहले WhatsApp आज़माते हैं, जबकि कुछ देश पहले SMS आज़माते हैं; प्लेटफ़ॉर्म के फ़ॉलबैक क्रम में Telegram इन दोनों के बाद आता है। वॉइस कॉल का उपयोग केवल उन्हीं देशों में होता है जहाँ आपने वॉइस चालू किया है। दोनों पते देने पर विफल प्रयास किसी दूसरे उपलब्ध चैनल पर जा सकता है।

विकल्प

options केवल इसी अनुरोध के लिए सेटिंग्स बदलता है:

• code_length: इस सत्यापन के लिए सत्यापन कोड की लंबाई, 4 से 8 अंक, जो डिफ़ॉल्ट की जगह लागू होती है।
• channels: इस अनुरोध के लिए डिलीवरी चैनलों का क्रम बदलें या उन्हें सीमित करें। चैनल के नाम (sms, whatsapp, email, telegram, voice) उसी क्रम में लिखें जिसमें उन्हें आज़माना है। जो चैनल आप छोड़ देते हैं, उसका उपयोग नहीं होता, और जो नाम प्राप्तकर्ता की तय योजना में नहीं है, उसे अनदेखा किया जाता है। इस तरीके से आप कोई चैनल जोड़ नहीं सकते। आप केवल उन्हीं चैनलों को हटा सकते हैं या उनका क्रम बदल सकते हैं जिनकी अनुमति प्राप्तकर्ता और देश कॉन्फ़िगरेशन पहले से देते हैं। अगर सूची में कोई उपयोग योग्य चैनल नहीं बचता, तो अनुरोध 422 के साथ विफल हो जाता है।
• language: fr या pt-BR जैसा BCP 47 टैग, जो तय करता है कि कोड संदेश किस बिल्ट-इन अनुवाद में जाएगा। इसे छोड़ देने पर भाषा प्राप्तकर्ता के फ़ोन नंबर से तय होती है। संदेश की भाषा देखें।

मेटाडेटा

metadata एक मुक्त-रूप ऑब्जेक्ट है, जो हर रीड में लौटाया जाता है। इसमें आप अपनी यूज़र ID या सेशन संदर्भ रख सकते हैं। प्रेषक के विकल्प और सत्यापन सेटिंग्स अनुरोध के साथ नहीं भेजे जाते। वे आपके वर्कस्पेस के कॉन्फ़िगरेशन से आते हैं, जिसे डैशबोर्ड में प्रबंधित किया जाता है (सत्यापन सेटिंग्स देखें)।

प्रतिक्रिया

{
  "id": "vrf_01ky7q1fdze3695yvyz7z9nm3a",
  "status": "pending",
  "reason": null,
  "to": { "phone_number": "+15551234567" },
  "channels": [{ "channel": "whatsapp" }, { "channel": "sms" }],
  "last_channel": "whatsapp",
  "expires_at": "2026-07-23T14:55:58Z",
  "verified_at": null,
  "created_at": "2026-07-23T14:45:58Z",
  "updated_at": "2026-07-23T14:45:58Z"
}

channels इस सत्यापन के लिए तय हुई क्रमबद्ध डिलीवरी योजना है। फ़ोन प्राप्तकर्ता के लिए इसमें फ़ोन चैनल प्रयास के क्रम में दिखते हैं। last_channel बताता है कि सबसे हाल का कोड कहाँ भेजा गया। expires_at वह समय है जब सही कोड न आने पर सत्यापन समाप्त हो जाता है। दोबारा भेजने से यह समय नहीं बढ़ता।

संदेश की भाषा

Bird के SMS, ईमेल और साझा WhatsApp संदेश 40 बिल्ट-इन अनुवादों में उपलब्ध हैं। कस्टम WhatsApp प्रेषक अपने चुने गए ऑथेंटिकेशन टेम्पलेट की स्वीकृत भाषाओं का उपयोग करता है। Telegram अपना संदेश खुद लिखता है और वॉइस कॉल कोड को अंग्रेज़ी में पढ़ती है, इसलिए इन दोनों पर इस सेटिंग का कोई असर नहीं होता।

options.language न होने पर भाषा प्राप्तकर्ता के फ़ोन नंबर से तय होती है। फ़्रांसीसी नंबर पर फ़्रेंच और जापानी नंबर पर जापानी भाषा में संदेश जाता है, इसके लिए आपको कुछ माँगना नहीं पड़ता। जिस सत्यापन में फ़ोन नंबर नहीं है, उसमें संदेश अंग्रेज़ी में जाता है। जिस देश का कोई अनुवाद नहीं है, वहाँ भी अंग्रेज़ी ही जाती है।

भाषा खुद चुनने के लिए options.language सेट करें, उदाहरण के लिए, नंबर के देश के बजाय वह भाषा जो आपके यूज़र ने आपके ऐप में चुनी है:

{
  "to": { "phone_number": "+15551234567" },
  "options": { "language": "es" }
}

जिस टैग का अपना बिल्ट-इन अनुवाद नहीं है, वह पहले अपनी मूल भाषा पर और फिर अंग्रेज़ी पर लौटता है: en-GB अंग्रेज़ी भेजता है, pt-BR पुर्तगाली भेजता है। केवल गलत ढंग से लिखा टैग अस्वीकार होता है, 422 के साथ। आप ये बिल्ट-इन अनुवाद माँग सकते हैं। ये सभी SMS और ईमेल पर उपलब्ध हैं, और मंगोलियाई को छोड़कर सभी Bird के साझा WhatsApp प्रेषक पर उपलब्ध हैं:

सत्यापन बनाने का संदर्भ ही आधिकारिक सूची है।

भाषा सत्यापन बनाते समय तय हो जाती है, इसलिए दोबारा भेजा गया कोड या दूसरे चैनल पर स्विच करने पर भेजा गया संदेश पहले संदेश वाली भाषा में ही पहुँचता है। उसी प्राप्तकर्ता के लिए अलग language के साथ create को फिर से कॉल करने पर चल रहा सत्यापन ही दोबारा उपयोग होता है और उसकी भाषा नहीं बदलती।

फ़ॉलबैक होने पर भेजे गए संदेश का अनुवाद आपके भेजे गए टैग से अलग हो सकता है। इसकी पुष्टि के लिए Verifications पेज पर सत्यापन खोलें: हर प्रयास रेंडर की गई भाषा को Template टैग के रूप में दिखाता है। Bird के साझा WhatsApp सेंडर में मंगोलियाई (mn) टेम्पलेट नहीं है, इसलिए वह इस भाषा के लिए अंग्रेज़ी भेजता है, जबकि SMS और ईमेल मंगोलियाई ही भेजते हैं। आपका अपना WhatsApp टेम्पलेट अपनी स्वीकृत भाषाओं और भाषा नीति का पालन करता है; जो भाषा वह नहीं भेज सकता, उसके कारण WhatsApp प्रयास विफल हो सकता है।

आप हर अनुरोध में भाषा चुन सकते हैं, लेकिन उस अनुरोध के साथ संदेश का पाठ नहीं भेज सकते। कस्टम WhatsApp सेंडर अपने चुने हुए ऑथेंटिकेशन टेम्पलेट का पाठ इस्तेमाल करता है। सेंडर और ब्रांडिंग में सेंडर के विकल्प और Bird के संदेश का पाठ दिया गया है।

कोड जाँचें

उपयोगकर्ता ने जो भी टाइप किया, उसे उसी प्राप्तकर्ता के साथ POST /v1/verify/verifications/check को भेजें। सत्यापन ID की ज़रूरत नहीं है। ठीक वही to सेट दें जिससे आपने सत्यापन बनाया था। दोनों पतों से बना सत्यापन किसी एक पते से अकेले नहीं मिलता।

const result = await bird.verify.verifications.check({
  to: { phone_number: "+15551234567" },
  code: "123456",
});
console.log(result.success);

result = client.verify.verifications.check(
    to={"phone_number": "+15551234567"}, code="123456"
)
print(result.success)

result, err := client.Verify.Verifications.Check(context.Background(), bird.VerifyVerificationsCheckParams{
	To:   bird.VerificationTo{PhoneNumber: bird.String("+15551234567")},
	Code: "123456",
})
if err != nil {
	log.Fatal(err)
}
fmt.Println(*result.Success)

$result = $bird->verify->verifications->check(
    (new VerificationCheckRequest())
        ->setTo((new VerificationTo())->setPhoneNumber('+15551234567'))
        ->setCode('123456'),
);
echo $result->getSuccess() ? 'verified' : 'failed';

bird verify verifications check 123456 --phone-number +15551234567

curl -X POST https://us1.platform.bird.com/v1/verify/verifications/check \
  -H "Authorization: Bearer bk_us1_..." \
  -H "Content-Type: application/json" \
  -d '{
    "to": { "phone_number": "+15551234567" },
    "code": "123456"
  }'

प्रतिक्रिया बताती है कि कोड मेल खाया या नहीं:

{
  "success": false,
  "reason": "incorrect_code",
  "attempts_remaining": 4,
  "verification": {
    "id": "vrf_01ky7q1fdze3695yvyz7z9nm3a",
    "status": "pending",
    "reason": null,
    "to": { "phone_number": "+15551234567" },
    "channels": [{ "channel": "whatsapp" }, { "channel": "sms" }],
    "last_channel": "whatsapp",
    "expires_at": "2026-07-23T14:55:58Z",
    "verified_at": null,
    "created_at": "2026-07-23T14:45:58Z",
    "updated_at": "2026-07-23T14:46:38Z"
  }
}

प्रतिक्रिया के इन दो व्यवहारों को संभालें:

• गलत कोड पर 200 मिलता है। reason (incorrect_code, expired, attempts_exhausted) वाले success: false को सामान्य उत्तर मानें। attempts_remaining बताता है कि कितने प्रयास बचे हैं। त्रुटि प्रबंधन केवल अनुरोध की विफलताओं के लिए रखें।
• अंतिम स्थिति वाले सत्यापन को दोबारा नहीं जाँचा जा सकता। जब सत्यापन किसी भी अंतिम स्थिति में पहुँच जाता है, तो आगे की जाँचें 404 लौटाती हैं। दोबारा जाँचने के बजाय पहला निर्णायक परिणाम सहेज लें।

अगर उपयोगकर्ता ने नया कोड माँगा है, तो उसी प्राप्तकर्ता के साथ create एंडपॉइंट को फिर से कॉल करें। चल रहा सत्यापन बदला नहीं जाता, बल्कि उसी का दोबारा उपयोग होता है। दोबारा भेजने का कूलडाउन (डिफ़ॉल्ट रूप से 60 सेकंड) पूरा होने पर नया कोड भेजा जाता है। कूलडाउन के दौरान कॉल बिना दोबारा भेजे चालू सत्यापन लौटाती है। चालू सत्यापन के लिए भेजा गया हर कोड तब तक मान्य रहता है जब तक सत्यापन पूरा न हो जाए या समय सीमा खत्म न हो जाए, इसलिए उपयोगकर्ता जो भी कोड पहुँचा हो, उसे दर्ज कर सकता है।

कोड किसी दूसरे चैनल पर भेजें

जब उपयोगकर्ता बताए कि कोई कोड पहुँचा ही नहीं, तो POST /v1/verify/verifications/next-channel सत्यापन को उसकी योजना के अगले चैनल पर ले जाता है और वहाँ नया कोड भेजता है। यही एंडपॉइंट "I didn't receive my code" बटन के पीछे काम करता है। डिलीवरी स्टेटस के संकेत का इंतज़ार करने के बजाय आपका ऐप तय करता है कि चैनल कब बदलना है।

जाँच की तरह, इसे भी उसी प्राप्तकर्ता से पहचानें जिसके साथ आपने सत्यापन बनाया था:

const verification = await bird.verify.verifications.nextChannel({
  to: { phone_number: "+15551234567" },
});
console.log(verification.last_channel);

verification = client.verify.verifications.next_channel(
    to={"phone_number": "+15551234567"}
)
print(verification.last_channel)

verification, err := client.Verify.Verifications.NextChannel(context.Background(), bird.VerifyVerificationsNextChannelParams{
	To: bird.VerificationTo{PhoneNumber: bird.String("+15551234567")},
})
if err != nil {
	log.Fatal(err)
}
if verification.LastChannel != nil {
	fmt.Println(*verification.LastChannel)
}

$verification = $bird->verify->verifications->nextChannel(
    (new VerificationNextChannelRequest())->setTo((new VerificationTo())->setPhoneNumber('+15551234567')),
);
echo $verification->getLastChannel();

bird verify verifications next-channel --phone-number +15551234567

curl -X POST "https://{region}.platform.bird.com/v1/verify/verifications/next-channel" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "to": {
      "phone_number": "+15551234567"
    }
  }'

प्रतिक्रिया में सत्यापन मिलता है, जिसमें last_channel उस चैनल का नाम बताता है जिस पर नया कोड गया। पहले भेजा गया हर कोड मान्य रहता है, इसलिए देर से पहुँचे संदेश को भी जाँचा जा सकता है।

दो बातें इसे दोबारा भेजने से अलग करती हैं:

• दोबारा भेजने का कूलडाउन लागू नहीं होता। जानबूझकर चैनल बदलना उसी चैनल पर फिर से माँगने से अलग काम है, इसलिए कोड तुरंत भेजा जाता है।
• केवल चैनल आगे बढ़ता है। समाप्ति, प्रयासों की सीमा और सत्यापन ID पहले जैसे ही रहते हैं।

जब उपयोगकर्ता किसी काम करने वाले चैनल पर एक और मौका चाहता है, तो दोबारा भेजने का उपयोग करें। जब समस्या चैनल में ही लगती है, तो इस एंडपॉइंट का उपयोग करें। जिस फ़ोन नंबर की योजना WhatsApp और फिर SMS है, वह SMS पर आगे बढ़ता है; जिस प्राप्तकर्ता के पास केवल एक उपयोग योग्य चैनल है, उसके लिए आगे कोई चैनल नहीं है।

चार प्रतिक्रियाओं को साधारण रूप से फिर से प्रयास करने के बजाय अलग से संभालना होता है:

यह एंडपॉइंट जो भी कोड भेजता है, उसका बिल किसी भी अन्य Verify भेजे गए कोड की तरह बनता है; लागत और बिलिंग देखें।

स्टेटस

सत्यापन तब तक pending रहता है जब तक वह किसी अंतिम स्थिति में नहीं पहुँच जाता, और reason उसका कारण बताता है:

reason एक खुला एनम है। किसी अपरिचित मान को सुरक्षित रखें, प्रतिक्रिया को अमान्य न मानें।

बाउंस, कैरियर द्वारा अस्वीकृति या डिलीवरी टाइमआउट होने पर भी सत्र लंबित रह सकता है, क्योंकि प्राप्तकर्ता के पास अब भी कोई मान्य कोड हो सकता है। केवल डिलीवरी योजना के समाप्त हो जाने का अर्थ यह नहीं है कि सत्र विफल हुआ। विफलता की शर्तों के लिए Verify इवेंट देखें।

डैशबोर्ड में सत्यापनों पर नज़र रखें

Verifications पेज पर वर्कस्पेस द्वारा बनाया गया हर सत्यापन दिखता है, जिसे स्टेटस के अनुसार फ़िल्टर किया जा सकता है। हर पंक्ति खोलने पर प्राप्तकर्ता, चैनल योजना, अंतिम चैनल, समाप्ति और सत्यापन के समय, और मेटाडेटा दिखते हैं। जनरेट किया गया कोड नहीं दिखाया जाता।

सत्यापन सेटिंग्स

Configure पेज पर वर्कस्पेस का सत्यापन चक्र सेट किया जाता है। हर फ़ील्ड प्रभावी मान दिखाती है: जहाँ आपने ओवरराइड सेट किया है वहाँ आपका मान, अन्यथा Bird का प्लेटफ़ॉर्म डिफ़ॉल्ट।

• Duration: कोड कितनी देर तक मान्य रहता है। डिफ़ॉल्ट 10 मिनट; 1 मिनट से 999 मिनट तक।
• Maximum Retries: कितने जाँच प्रयासों के बाद सत्यापन attempts_exhausted के साथ विफल हो जाता है। डिफ़ॉल्ट 5; 1 से 10 तक।
• Retry Delay: उसी प्राप्तकर्ता को नया कोड भेजे जाने से पहले का कूलडाउन। डिफ़ॉल्ट 60 सेकंड; 0 से 3,600 तक।

कोड की लंबाई इस पेज की कोई फ़ील्ड नहीं है: कोड डिफ़ॉल्ट रूप से 6 अंकों के और संख्यात्मक होते हैं, और options.code_length हर अनुरोध के लिए 4 से 8 अंक सेट करता है।

दुरुपयोग से सुरक्षा

आपकी सेटिंग्स से अलग, Verify प्लेटफ़ॉर्म सीमाएँ लागू करता है, ताकि OTP ट्रैफ़िक का दुरुपयोग न हो सके, चाहे आपके वॉलेट के विरुद्ध (SMS पंपिंग) या किसी पीड़ित के इनबॉक्स के विरुद्ध:

• हर पते पर किसी भी लगातार एक घंटे में 5 बार भेजना, जिसमें सत्यापन शुरू करना और दोबारा भेजना दोनों गिने जाते हैं। जब to में दोनों पते हों, तो हर पते की अपनी अलग सीमा होती है।
• प्राप्तकर्ता के हर पता-सेट पर प्रति मिनट 10 जाँचें, जो सत्यापन की प्रयास सीमा के अतिरिक्त है।

चैनल बदलने की संख्या घंटे की सीमा से नहीं, बल्कि चैनल योजना से सीमित होती है। हर कॉल सख्ती से आगे ही बढ़ती है, इसलिए एक सत्यापन हर बचे हुए चैनल पर अधिकतम एक बार भेजता है।

सीमा पार होने पर 429 लौटता है। रुकें और Retry-After हेडर में दी गई अवधि के बाद फिर से प्रयास करें। आपके खाते की कुल अनुरोध सीमाएँ अलग हैं और आपकी योजना के अनुसार बढ़ती हैं; देखें दर सीमाएँ।

सुरक्षित रूप से फिर से प्रयास करना

तीनों एंडपॉइंट Idempotency-Key हेडर स्वीकार करते हैं। हर तार्किक अनुरोध के लिए एक अनोखा मान भेजें। टाइमआउट या कनेक्शन टूटने के बाद उसी कुंजी से फिर से प्रयास करने पर मूल प्रतिक्रिया दोबारा मिलती है। दोहराई गई प्रतिक्रिया न तो नया कोड भेजती है और न ही कोई और जाँच प्रयास खर्च करती है, और उसमें Idempotency-Replay हेडर होता है। कुंजी के फ़ॉर्मैट और उसे कितने समय तक रखा जाता है, इसके लिए आइडेम्पोटेंसी देखें।

लागत और बिलिंग

बिलिंग हर भेजे गए कोड पर लागू होती है। हर भेजा गया कोड गंतव्य के लिए उस चैनल की दर पर आपके वॉलेट से चार्ज होता है। दोबारा भेजने या किसी दूसरे चैनल पर जाने पर हर बार भेजने का एक चार्ज जुड़ता है। Bird का अपना शुल्क भेजने की प्रक्रिया के दौरान लिया जाता है और कोड पहुँचे या न पहुँचे, यह शुल्क बना रहता है। SMS और WhatsApp पर संदेश डिलीवर होने पर किसी तीसरे पक्ष का शुल्क भी लगता है। मुफ़्त रूट और जाँचों का कोई शुल्क नहीं है, और बिलिंग से पहले अस्वीकार किए गए भेजने पर चार्ज नहीं लगता। बैलेंस और टॉप-अप के लिए भुगतान के तरीके और वॉलेट देखें।

Telegram भेजने की प्रक्रिया के एक अलग चरण पर बिल करता है। संदेश जाने से पहले Telegram से पूछा जाता है कि क्या वह नंबर संदेश प्राप्त कर सकता है। जवाब हाँ होने पर दुनिया भर में एक समान दर पर चार्ज लगता है। जिस नंबर तक पहुँचा नहीं जा सकता, उसका कोई शुल्क नहीं लगता और सत्यापन बिना बिलिंग के अगले चैनल पर चला जाता है। इसलिए Telegram चार्ज का मतलब है कि संदेश डिलीवरी के लिए स्वीकार हुआ, यह नहीं कि वह पहुँचा। अगर कोड बाद में डिलीवर नहीं होता, तो चार्ज बना रहता है, और सत्यापन अगले चैनल के लिए फिर से भुगतान करता है। अगर आप यह दूसरा चार्ज नहीं चाहते, तो Countries पेज पर उन देशों के चैनल क्रम से Telegram हटा दें।

वॉइस का बिल हर कोड के हिसाब से नहीं, बल्कि फ़ोन कॉल की तरह बनता है, और इस पर कोई Verify शुल्क नहीं लगता। जिस कॉल का जवाब नहीं दिया जाता, उसका कोई शुल्क नहीं लगता। जवाब दी गई कॉल का चार्ज जवाब देने से लेकर कॉल काटने तक, गंतव्य की आउटबाउंड वॉइस दर पर लगता है, और उस दर का न्यूनतम बिल किया जाने वाला समय और वृद्धि-अंतराल लागू होते हैं। इसके साथ Bird का कॉल हैंडलिंग शुल्क भी लगता है। ये दोनों वॉइस मूल्य पेज पर दिए गए हैं; बिल योग्य समय कैसे गिना जाता है, इसके लिए वॉइस की लागत और बिलिंग देखें। अगर कोड पूरा पढ़े जाने से पहले कॉल खत्म हो जाती है, तब भी जुड़े रहने के समय का चार्ज लगता है, भले ही प्रयास को undelivered बताया जाए।

अगले कदम