अपने फ़ोन नंबर प्रबंधित करना

जब कोई नंबर आपके वर्कस्पेस को आवंटित हो जाता है, तो नंबर API से आप अपने सभी नंबरों की सूची देख सकते हैं, किसी भी पहचानकर्ता से एक नंबर खोज सकते हैं, उसे एक नाम और अपना संदर्भ दे सकते हैं, और काम पूरा होने पर उसे रद्द या रिलीज़ कर सकते हैं। पढ़ने के लिए ऐसी API कुंजी चाहिए जिसमें numbers स्कोप पढ़ने के स्तर पर हो; नंबर बदलने, रद्द करने या रिलीज़ करने के लिए लिखने का स्तर चाहिए।

डैशबोर्ड का Numbers पेज यही नंबर दिखाता है।

अपने सभी नंबरों की सूची देखें

GET /v1/numbers आपके वर्कस्पेस को आवंटित नंबर लौटाता है, सबसे नए पहले, चाहे वे समर्पित हों या साझा। हर पेज में 25 नंबर होते हैं, जब तक आप limit से 100 तक न माँगें।

सूची कर्सर से पेजों में बँटी होती है। अगला पेज पढ़ने के लिए किसी पेज का next_cursor वापस starting_after के रूप में भेजें, और जब next_cursor null हो तो रुक जाएँ। SDK आपके लिए कर्सर का पालन करते हैं। नीचे दिए उदाहरण सूची को country_code: "GB" तक सीमित करते हैं; अपने सभी नंबरों से गुज़रने के लिए फ़िल्टर हटा दें:

for await (const allocated of bird.numbers.list({ country_code: "GB" })) {
  console.log(allocated.number, allocated.kind, allocated.status);
}

for allocated in client.numbers.list(country_code="GB"):
    print(allocated.number, allocated.kind, allocated.status)

for allocated, err := range client.Numbers.List(context.Background(), bird.NumbersListParams{
	CountryCode: "GB",
}) {
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(allocated.Number, allocated.Kind, allocated.Status)
}

$page = $bird->numbers->list(['country_code' => 'GB']);
foreach ($page as $allocated) {
    echo $allocated->getNumber(), ' ', $allocated->getKind(), ' ', $allocated->getStatus(), "\n";
}

curl "https://us1.platform.bird.com/v1/numbers?country_code=GB" \
  -H "Authorization: Bearer bk_us1_..."

वही क्षेत्रीय होस्ट इस्तेमाल करें जो आपकी कुंजी के bk_{region}_ प्रीफ़िक्स से मेल खाता है: https://us1.platform.bird.com या https://eu1.platform.bird.com।

सूची में कुल संख्या नहीं होती। अपने नंबर गिनने के लिए अंत तक सभी पेज देखें और प्रविष्टियाँ गिनें। include_total भेजने पर अनुरोध 422 और E01029 के साथ अस्वीकार हो जाता है।

हर प्रविष्टि में उसका status और ownership होता है। जिस देश में स्वामित्व के दस्तावेज़ नहीं माँगे जाते, वहाँ ownership का मान null होता है। Numbers का अवलोकन बताता है कि हर स्थिति का क्या अर्थ है। जिन दस्तावेज़ों का कोई नंबर इंतज़ार कर रहा है, उन्हें जमा करने के लिए किसी नंबर के स्वामित्व के दस्तावेज़ जमा करें देखें।

हर प्रविष्टि में pricing भी होता है, यानी आपका संगठन इस नंबर के लिए कर को छोड़कर कितना भुगतान करता है:

• recurring_price प्रति recurring_period आपकी दर है, उस मुद्रा में जिसमें नंबर का शुल्क लिया जाता है। यह आपकी बिलिंग मुद्रा होती है, जब तक कि नंबर का सब्सक्रिप्शन आपकी बिलिंग मुद्रा बदलने से पहले शुरू न हुआ हो; ऐसा नंबर अपने सब्सक्रिप्शन की मुद्रा बनाए रखता है, जिसे currency_code बताता है।
• intervals_per_charge बताता है कि एक नवीनीकरण में कितने recurring_period का शुल्क लगता है। कर से पहले आवर्ती शुल्क recurring_price को intervals_per_charge से गुणा करने पर मिलता है। नंबर के लिए तय की गई कीमत उसकी पूरी अवधि को कवर करती है, इसलिए उसका intervals_per_charge 1 होता है।

shared नंबर के लिए और बिना सक्रिय सब्सक्रिप्शन वाले नंबर के लिए pricing का मान null होता है। जब किसी नंबर के सब्सक्रिप्शन पर कोई लागू कीमत नहीं होती, तो उसकी कीमतें pricing.error: null के साथ null होती हैं; कीमत तय करवाने के लिए सेल्स से संपर्क करें। अगर कीमत पढ़ी नहीं जा सकी, तो pricing.error में E14009 होता है और कीमतें null होती हैं। एक्सपोनेंशियल बैकऑफ़ के साथ GET /v1/numbers/{number_id} को फिर से प्रयास करें। नंबर का प्रबंधन तब भी किया जा सकता है; उसकी कीमत ताज़ा करने के लिए पूरा हो चुका अपडेट या रद्दीकरण दोबारा न करें।

डैशबोर्ड और API कीमत एक ही तरीके से तय करते हैं। तय की गई कीमत अपनी मौजूदा शर्तें बनाए रखती है; अन्यथा यह मौजूदा दर है, जो नवीनीकरण से पहले बदल सकती है। यह नहीं बताती कि किसी पिछले ऑर्डर में कितना शुल्क लगा था। जिस नंबर पर releases_at सेट है, वह रिलीज़ होने तक अपना pricing बनाए रखता है, और उसके बाद कोई नवीनीकरण नहीं होता।

अपनी सूची में कोई नंबर खोजें

सूची के फ़िल्टर एक साथ लागू होते हैं, इसलिए देश या क्षमता का फ़िल्टर बाकी फ़िल्टरों के साथ भी लागू रहता है।

number एक नंबर को खोजता है, चाहे आपके रिकॉर्ड में वह किसी भी रूप में लिखा हो। +31612345678 और 0031612345678 एक ही नंबर पर पहुँचते हैं। 0612345678 जैसा राष्ट्रीय रूप तभी मिलता है जब country_code देश बताता है:

curl "https://us1.platform.bird.com/v1/numbers?number=0612345678&country_code=NL" \
  -H "Authorization: Bearer bk_us1_..."

जब आप पूरा नंबर, या उसके country_code के साथ राष्ट्रीय रूप देते हैं और कोई दूसरा फ़िल्टर नहीं देते, तो खाली data ऐरे का मतलब है कि नंबर आपके वर्कस्पेस को आवंटित नहीं है। इसमें वह नंबर भी शामिल है जिसे आपने रिलीज़ कर दिया है। country_code के बिना राष्ट्रीय रूप, जैसे अकेला 0612345678, भी खाली सूची लौटाता है, इसलिए इससे यह साबित नहीं होता कि नंबर आपका नहीं है।

search नंबर के किसी हिस्से, उसके नाम या उसके रेफ़रेंस से मिलान करता है और अक्षरों के छोटे-बड़े होने को अनदेखा करता है। reference ठीक उसी रेफ़रेंस वाले नंबर लौटाता है और छोटे-बड़े अक्षरों का भी मिलान करता है:

curl "https://us1.platform.bird.com/v1/numbers?reference=STORE-042" \
  -H "Authorization: Bearer bk_us1_..."

prefix वे नंबर लौटाता है जो आपके दिए अंकों से शुरू होते हैं। उन अंकों का अर्थ country_code पर निर्भर करता है:

• country_code के साथ, अंक राष्ट्रीय माने जाते हैं और डायल कोड के ठीक बाद से मिलाए जाते हैं। prefix=6&country_code=NL वे डच नंबर लौटाता है जो +31 6 से शुरू होते हैं।
• country_code के बिना, अंक पूरे नंबर की शुरुआत से मिलाए जाते हैं। अकेला prefix=6 वे नंबर लौटाता है जिनका डायल कोड 6 से शुरू होता है, जैसे ऑस्ट्रेलियाई +61 नंबर, इसलिए इससे आपका कोई भी डच मोबाइल नंबर नहीं मिलता। यह उन शॉर्ट कोड से भी मिलान करता है जो इन अंकों से शुरू होते हैं।

नंबर को नाम दें और अपना रेफ़रेंस सेट करें

एक नंबर पर आपके अपने दो लेबल होते हैं। name से आप अपने नंबरों को अलग पहचानते हैं, जैसे Support line। reference में आपके अपने रिकॉर्ड का कोई पहचानकर्ता रहता है, जैसे ग्राहक या स्टोर id, और इसका अद्वितीय होना ज़रूरी नहीं है। दोनों डेडिकेटेड और शेयर्ड नंबरों पर लागू होते हैं और अधिकतम 100 अक्षरों के हो सकते हैं।

इन्हें PATCH /v1/numbers/{number_id} से सेट करें। जिस फ़ील्ड को आप छोड़ देते हैं, उसका मौजूदा मान बना रहता है, और जिस फ़ील्ड को आप null के रूप में भेजते हैं, वह खाली हो जाता है। शुरू और अंत की खाली जगह हटा दी जाती है।

const allocated = await bird.numbers.update("nda_01krdgeqcxet5s7t44vh8rt9mg", {
  name: "Support line",
  reference: "STORE-042",
});
console.log(allocated.name, allocated.reference);

allocated = client.numbers.update(
    "nda_01krdgeqcxet5s7t44vh8rt9mg", name="Support line", reference="STORE-042"
)
print(allocated.name, allocated.reference)

allocated, err := client.Numbers.Update(ctx, "nda_01krdgeqcxet5s7t44vh8rt9mg", bird.NumbersUpdateParams{
	Name:      bird.Value("Support line"),
	Reference: bird.Value("STORE-042"),
})
if err != nil {
	log.Fatal(err)
}
if allocated.Name != nil {
	fmt.Println(*allocated.Name)
}
if allocated.Reference != nil {
	fmt.Println(*allocated.Reference)
}

$allocated = $bird->numbers->update(
    'nda_01krdgeqcxet5s7t44vh8rt9mg',
    (new \MessageBird\Wire\Model\NumberUpdate())->setName('Support line')->setReference('STORE-042'),
);
echo $allocated->getName(), ' ', $allocated->getReference(), "\n";

curl -X PATCH "https://{region}.platform.bird.com/v1/numbers/{number_id}" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support line",
    "reference": "STORE-042"
  }'

प्रतिक्रिया अपडेट किए गए नंबर के साथ 200 होती है। नाम रखते हुए रेफ़रेंस खाली करने के लिए रेफ़रेंस को null के रूप में भेजें और नाम न भेजें:

curl -X PATCH "https://us1.platform.bird.com/v1/numbers/nda_01krdgeqcxet5s7t44vh8rt9mg" \
  -H "Authorization: Bearer bk_us1_..." \
  -H "Content-Type: application/json" \
  -d '{"reference": null}'

नंबर खरीदते समय रेफ़रेंस सेट करने के लिए POST /v1/numbers/orders पर reference दें। जिस ऑर्डर को किसी कैरियर का इंतज़ार करना पड़ता है, वह नंबर आवंटित होने तक रेफ़रेंस को संभाले रखता है, और उसके बाद से वह रेफ़रेंस नंबर पर रहता है।

किसी नंबर को रूट करने वाला वॉइस रिकॉर्ड खोजें

वॉइस वाले नंबर के दो पहचानकर्ता होते हैं। GET /v1/numbers पर id डेडिकेटेड नंबर के लिए nda_ से और शेयर्ड नंबर के लिए nal_ से शुरू होता है, और नंबर ऑपरेशन यही लेते हैं। वॉइस ऑपरेशन, जिनमें इनकमिंग कॉल का गंतव्य तय करने वाला ऑपरेशन भी शामिल है, नंबर का वॉइस रिकॉर्ड लेते हैं, जिसका id vnu_ से शुरू होता है। किसी वॉइस ऑपरेशन को nda_ या nal_ id देने पर अनुरोध 422 के साथ अस्वीकार हो जाता है।

एक से दूसरे तक पहुँचने के लिए, फ़ोन नंबर से वॉइस नंबर खोजें। इसके लिए पढ़ने के स्तर पर voice_management स्कोप चाहिए:

curl "https://us1.platform.bird.com/v1/voice/numbers?search=%2B31612345678" \
  -H "Authorization: Bearer bk_us1_..."

प्रविष्टि का id vnu_ पहचानकर्ता है, और उसका provider.number_id उसी नंबर का nda_ या nal_ पहचानकर्ता है। वहाँ से नंबर को रूट करने का तरीका कॉल प्राप्त करना में दिया गया है।

वॉइस रिकॉर्ड का अपना अलग name होता है। PATCH /v1/numbers/{number_id} से नंबर का नाम रखने पर वॉइस रिकॉर्ड का नाम नहीं बदलता, और उल्टा भी यही लागू होता है।

नंबर रिलीज़ करें

आप डेडिकेटेड नंबर दो तरीकों से लौटा सकते हैं:

• भुगतान की गई अवधि के अंत में। DELETE /v1/numbers/{number_id} नंबर का नवीनीकरण रोक देता है। नंबर मौजूदा बिलिंग अवधि खत्म होने तक काम करता रहता है और फिर रिलीज़ हो जाता है। 202 प्रतिक्रिया नंबर को लौटाती है, जिसमें releases_at उसी समय पर सेट होता है, और दोबारा अनुरोध करने पर वही releases_at मिलता है। रद्दीकरण को वापस नहीं लिया जा सकता। जिस नंबर के पीछे कोई सब्सक्रिप्शन नहीं है, जैसे बिना शुल्क के आवंटित नंबर, वह तुरंत रिलीज़ हो जाता है, और प्रतिक्रिया 200 होती है जिसमें नंबर का status released पर सेट होता है।
• अभी। POST /v1/numbers/{number_id}/release नंबर को तुरंत रिलीज़ करता है, उस नंबर को भी जिसका रद्दीकरण पहले से निर्धारित है। मौजूदा अवधि का बाकी हिस्सा वापस नहीं किया जाता। नंबर खरीदें और रिलीज़ करें में हर SDK में यह कॉल दिखाई गई है।

जब तक नंबर का नवीनीकरण भुगतान बकाया रहता है, दोनों अनुरोध भुगतान होने तक 409 लौटाते हैं।

रिलीज़ का आप जो भी विकल्प चुनें, अनुरोध Idempotency-Key के साथ भेजें, ताकि फिर से प्रयास सुरक्षित रहे: वही कुंजी पहली प्रतिक्रिया को Idempotency-Replay: true हेडर के साथ दोबारा लौटाती है, जबकि पहले से रिलीज़ हुए नंबर के लिए नया अनुरोध E01008 के साथ 404 लौटाता है। कुंजी कितने समय तक रखी जाती है, यह आइडेम्पोटेंसी में बताया गया है।

निर्धारित रद्दीकरण लागू होने तक नंबर सामान्य रूप से पढ़ा जाता है और उसमें releases_at रहता है। रिलीज़ के बाद:

• नंबर आपके लिए काम करना बंद कर देता है, और उसके सब्सक्रिप्शन का नवीनीकरण नहीं होता।
• GET /v1/numbers/{number_id} और नंबर का वॉइस रिकॉर्ड 404 लौटाते हैं, और नंबर GET /v1/numbers से हट जाता है।
• नंबर का ऑर्डर GET /v1/numbers/orders में बना रहता है, और उसका number_id अब 404 लौटाता है।
• दोबारा बिक्री के लिए उपलब्ध होने से पहले नंबर 30 दिन की कूलडाउन अवधि में रहता है, इसलिए आप वही नंबर तुरंत वापस नहीं खरीद सकते।

अगले कदम

• कॉल प्राप्त करना बताता है कि नंबर को SIP ट्रंक, फ़ॉरवर्ड या सीक्वेंस पर कैसे रूट करें।
• नंबर खरीदें और रिलीज़ करें API के ज़रिए खरीद की पूरी प्रक्रिया दिखाता है।
• Numbers API संदर्भ हर ऑपरेशन और फ़ील्ड का विवरण देता है।