Gérer vos numéros de téléphone

Une fois qu'un numéro est attribué à votre espace de travail, API des numéros vous permet de lister ce que vous détenez, de trouver un numéro par n'importe lequel de ses identifiants, de l'étiqueter avec un nom et votre propre référence, et de l'annuler ou le libérer quand vous n'en avez plus besoin. La lecture nécessite une clé API avec le scope numbers en niveau lecture ; modifier, annuler ou libérer un numéro nécessite le niveau écriture.

La page Numbers dans le tableau de bord affiche les mêmes numéros.

Lister tous les numéros que vous détenez

GET /v1/numbers renvoie les numéros actuellement attribués à votre espace de travail, du plus récent au plus ancien, dédiés et partagés confondus. Chaque page contient 25 numéros, sauf si vous en demandez jusqu'à 100 avec limit.

La liste est paginée par curseur. Renvoyez le next_cursor d'une page en tant que starting_after pour lire la page suivante, et arrêtez quand next_cursor vaut null. Les SDK suivent le curseur pour vous. Les exemples ci-dessous restreignent la liste à country_code: "GB" ; retirez le filtre pour parcourir tous les numéros que vous détenez :

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_..."

Utilisez l'hôte régional qui correspond au préfixe bk_{region}_ de votre clé : https://us1.platform.bird.com ou https://eu1.platform.bird.com.

La liste ne contient pas de total. Pour compter vos numéros, parcourez les pages jusqu'à la fin et comptez les entrées. Passer include_total est refusé avec 422 et E01029.

Chaque entrée porte ses champs status et ownership. Lorsqu'un pays n'exige aucun justificatif de propriété, ownership vaut null. La vue d'ensemble des numéros explique la signification de chaque statut. Pour déposer les justificatifs qu'un numéro attend, consultez Déposer les justificatifs de propriété d'un numéro.

Chaque entrée porte aussi pricing, ce que votre organisation paie pour le numéro, hors taxes :

recurring_price est votre tarif par recurring_period, dans la devise dans laquelle le numéro est facturé. Il s'agit de votre devise de facturation, sauf si l'abonnement du numéro a commencé avant un changement de votre devise de facturation ; un tel numéro conserve la devise de son abonnement, que currency_code indique.
intervals_per_charge est le nombre de recurring_period facturés par renouvellement. Le montant récurrent hors taxes est recurring_price multiplié par intervals_per_charge. Un prix fixé pour le numéro couvre toute sa période, donc son intervals_per_charge vaut 1.

pricing vaut null pour un numéro shared et pour un numéro sans abonnement actif. Lorsque l'abonnement d'un numéro n'a aucun prix applicable, ses prix valent null avec pricing.error: null ; contactez l'équipe commerciale pour obtenir un tarif. Si le prix n'a pas pu être lu, pricing.error contient E14009 et les prix valent null. Réessayez GET /v1/numbers/{number_id} avec un backoff exponentiel. Le numéro reste disponible pour la gestion ; ne répétez pas une mise à jour ou une annulation déjà terminée pour actualiser son prix.

Le tableau de bord et API utilisent la même résolution de prix. Un prix fixé conserve ses conditions existantes ; sinon, il s'agit du tarif actuel, qui peut changer avant le renouvellement. Il n'indique pas ce qu'une commande antérieure a facturé. Un numéro dont releases_at est défini conserve son pricing jusqu'à la libération, et aucun renouvellement ne suit.

Trouver un numéro dans votre liste

Les filtres de la liste se combinent : un filtre par pays ou par capacité continue de s'appliquer en même temps que les autres.

number recherche un numéro quelle que soit la façon dont vos dossiers l'écrivent. +31612345678 et 0031612345678 correspondent au même numéro. Une écriture nationale telle que 0612345678 n'est résolue que si country_code indique le pays :

Exemple de code

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

Lorsque vous transmettez un numéro complet, ou une écriture nationale avec son country_code, sans autre filtre, un tableau data vide signifie que le numéro n'est pas attribué à votre espace de travail, ce qui inclut un numéro que vous avez libéré. Une écriture nationale sans country_code, par exemple 0612345678 seul, renvoie aussi une liste vide et ne prouve donc pas que le numéro n'est pas le vôtre.

search recherche une correspondance partielle dans le numéro, son nom ou sa référence, sans tenir compte de la casse. reference renvoie les numéros portant exactement cette référence, en respectant la casse :

Exemple de code

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

prefix renvoie les numéros qui commencent par les chiffres que vous indiquez, et la signification de ces chiffres dépend de country_code :

Avec country_code, les chiffres sont nationaux, comparés juste après l'indicatif. prefix=6&country_code=NL renvoie les numéros néerlandais commençant par +31 6.
Sans country_code, les chiffres sont comparés depuis le début du numéro complet. prefix=6 seul renvoie les numéros dont l'indicatif commence par 6, comme les numéros australiens +61, et ne trouve donc aucun de vos mobiles néerlandais. Il correspond aussi aux codes courts commençant par ces chiffres.

Nommer un numéro et définir votre référence

Un numéro porte deux libellés qui vous sont propres. name distingue vos numéros les uns des autres, par exemple Support line. reference contient un identifiant issu de vos propres dossiers, tel qu'un identifiant de client ou de magasin, et n'a pas besoin d'être unique. Les deux s'appliquent aux numéros dédiés et partagés et comptent jusqu'à 100 caractères.

Définissez-les avec PATCH /v1/numbers/{number_id}. Un champ que vous omettez conserve sa valeur actuelle, et un champ envoyé avec la valeur null est effacé. Les espaces en début et en fin de chaîne sont supprimés.

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"
  }'

La réponse est 200 avec le numéro mis à jour. Pour effacer la référence et conserver le nom, envoyez la référence comme null et omettez le nom :

Exemple de code

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}'

Pour définir la référence au moment de l'achat du numéro, passez reference sur POST /v1/numbers/orders. Une commande qui doit attendre un opérateur conserve la référence jusqu'à l'attribution du numéro, et le numéro la porte à partir de ce moment.

Trouver l'enregistrement vocal qui achemine un numéro

Un numéro qui prend en charge la voix possède deux identifiants. Le id sur GET /v1/numbers commence par nda_ pour un numéro dédié et nal_ pour un numéro partagé, et les opérations sur les numéros l'utilisent. Les opérations vocales, y compris celle qui définit la destination des appels entrants, utilisent l'enregistrement vocal du numéro, dont le id commence par vnu_. Passer un id nda_ ou nal_ à une opération vocale est refusé avec 422.

Pour passer de l'un à l'autre, recherchez les numéros vocaux par numéro de téléphone. Cela nécessite le scope voice_management en lecture :

Exemple de code

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

Le id de l'entrée est l'identifiant vnu_, et son provider.number_id est l'identifiant nda_ ou nal_ du même numéro. Recevoir des appels montre comment acheminer le numéro à partir de là.

L'enregistrement vocal possède un name qui lui est propre. Nommer un numéro avec PATCH /v1/numbers/{number_id} ne modifie pas le nom de l'enregistrement vocal, et l'inverse est aussi vrai.

Libérer un numéro

Vous pouvez rendre un numéro dédié de deux façons :

À la fin de la période que vous avez payée. DELETE /v1/numbers/{number_id} empêche le renouvellement du numéro. Il continue de fonctionner jusqu'à la fin de la période de facturation en cours, puis il est libéré. La réponse 202 renvoie le numéro avec releases_at fixé à cette date, et une nouvelle demande renvoie le même releases_at. Une annulation est irréversible. Un numéro sans abonnement associé, par exemple un numéro qui vous a été attribué sans frais, est libéré immédiatement, et la réponse est 200 avec le status du numéro défini sur released.
Immédiatement. POST /v1/numbers/{number_id}/release libère le numéro sur-le-champ, y compris un numéro déjà programmé pour annulation. Le reste de la période en cours n'est pas remboursé. Acheter et libérer un numéro montre l'appel dans chaque SDK.

Tant qu'un paiement de renouvellement pour le numéro est en retard, les deux requêtes répondent 409 jusqu'à ce qu'il soit réglé.

Quelle que soit l'option de libération choisie, envoyez la requête avec un Idempotency-Key pour qu'une nouvelle tentative soit sans risque : la même clé rejoue la première réponse avec un en-tête Idempotency-Replay: true, tandis qu'une nouvelle requête pour un numéro déjà libéré répond 404 avec E01008. Idempotence explique combien de temps une clé est conservée.

Tant qu'une annulation programmée n'a pas pris effet, le numéro se consulte normalement et porte releases_at. Après la libération :

Le numéro cesse de fonctionner pour vous et son abonnement ne se renouvelle pas.
GET /v1/numbers/{number_id} et l'enregistrement vocal du numéro répondent 404, et le numéro quitte GET /v1/numbers.
La commande du numéro reste dans GET /v1/numbers/orders, et son number_id répond désormais 404.
Le numéro entre dans une période de rétention de 30 jours avant de pouvoir être remis en vente ; vous ne pouvez donc pas racheter le même numéro immédiatement.

Étapes suivantes

Recevoir des appels achemine un numéro vers un trunk SIP, un renvoi ou une séquence.
Acheter et libérer un numéro détaille l'achat via l'API.
Référence API Numbers documente chaque opération et chaque champ.

Poursuivez avec la documentation, les guides et les exemples sur ce sujet.

Obtenir un guide d'implémentation

Gérer vos numéros de téléphone

Lister tous les numéros que vous détenez

Trouver un numéro dans votre liste

Nommer un numéro et définir votre référence

Trouver l'enregistrement vocal qui achemine un numéro

Libérer un numéro

Étapes suivantes

Ressources associées