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

किसी उपयोगकर्ता को सत्यापित करने में दो कॉल लगती हैं। 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) उस क्रम में सूचीबद्ध करें जिसमें उन्हें आज़माना है; जो चैनल आप छोड़ते हैं वह उपयोग नहीं होता, और जो नाम प्राप्तकर्ता की रिज़ॉल्व्ड योजना में नहीं है उसे अनदेखा किया जाता है। इस तरह आप कोई चैनल जोड़ नहीं सकते, केवल प्राप्तकर्ता और देश कॉन्फ़िगरेशन द्वारा पहले से अनुमत चैनलों को ट्रिम या पुनर्क्रमित कर सकते हैं, और ऐसी सूची जो कोई उपयोगी चैनल नहीं छोड़ती, रिक्वेस्ट को 422 के साथ विफल कर देती है।
• language: एक BCP 47 टैग जैसे fr या pt-BR जो तय करता है कि कोड संदेश कौन-सा बिल्ट-इन अनुवाद उपयोग करे। इसे छोड़ दें तो भाषा प्राप्तकर्ता के फ़ोन नंबर से आती है; देखें संदेश भाषा।

मेटाडेटा

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, email, और शेयर्ड WhatsApp संदेश 40 बिल्ट-इन अनुवादों में उपलब्ध हैं। कस्टम WhatsApp सेंडर अपने चयनित ऑथेंटिकेशन टेम्पलेट की स्वीकृत भाषाओं का उपयोग करता है। Telegram अपना संदेश खुद लिखता है, इसलिए यह सेटिंग वहाँ कोई प्रभाव नहीं डालती।

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

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

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

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

सत्यापन बनाएँ रेफ़रेंस आधिकारिक सूची है।

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

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

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

कोड जाँचें

उपयोगकर्ता ने जो भी टाइप किया उसे POST /v1/verify/verifications/check को सबमिट करें, उसी प्राप्तकर्ता से कुंजीबद्ध; कोई verification 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 endpoint फिर से कॉल करें: चल रहा सत्यापन प्रतिस्थापित नहीं बल्कि पुन: उपयोग होता है। दोबारा भेजने का कूलडाउन बीतने के बाद (डिफ़ॉल्ट 60 सेकंड) एक नया कोड जाता है; कूलडाउन के भीतर कॉल बिना दोबारा भेजे लाइव सत्यापन लौटाती है। लाइव सत्यापन के लिए भेजा गया हर कोड रिज़ॉल्व या एक्सपायर होने तक मान्य रहता है, इसलिए उपयोगकर्ता जो भी कोड आया हो वह दर्ज कर सकता है।

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

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

इसे उसी प्राप्तकर्ता से कुंजीबद्ध करें जिससे आपने सत्यापन बनाया था, जैसे check में:

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 उस चैनल का नाम बताता है जहाँ नया कोड गया। पहले भेजा गया हर कोड मान्य रहता है, इसलिए देर से आया संदेश भी जाँचा जा सकता है।

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

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

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

चार रिस्पॉन्स को साधारण फिर से प्रयास करने की बजाय हैंडलिंग चाहिए:

इस endpoint द्वारा भेजा गया हर कोड किसी भी अन्य Verify सेंड की तरह बिल होता है; देखें लागत और बिलिंग।

स्टेटस

सत्यापन pending रहता है जब तक यह किसी अंतिम स्थिति में रिज़ॉल्व नहीं होता, reason कारण बताता है:

reason एक ओपन enum है। रिस्पॉन्स को अमान्य मानने की बजाय किसी अपरिचित वैल्यू को संरक्षित करें।

बाउंस, कैरियर अस्वीकृति, या डिलीवरी टाइमआउट सेशन को पेंडिंग छोड़ सकते हैं क्योंकि प्राप्तकर्ता के पास अभी भी एक वैध कोड हो सकता है। केवल डिलीवरी-प्लान का समाप्त होना इसका मतलब नहीं है कि सेशन विफल हो गया। विफलता की शर्तों के लिए 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 को हटा दें।

अगले कदम