Recevoir des appels

Un numéro détenu par votre espace de travail peut acheminer un appel entrant vers un trunk SIP, le transférer vers un numéro vérifié, exécuter une séquence publiée ou le refuser. Un numéro possède une seule route à la fois : la sienne, ou la route par défaut de votre espace de travail lorsqu'il n'en a pas.

La route par défaut de l'espace de travail démarre sur le rejet : un numéro que personne n'a configuré refuse les appelants au lieu de n'avoir aucune réponse. Modifiez la valeur par défaut pour donner la même réponse à tous ces numéros. Voir Définir une route par défaut.

Pour traiter les appels entrants dans un flux natif Bird, publiez une séquence et associez le numéro à son entrée d'appel. L'entrée sélectionnée doit accepter des données vides.

Prérequis

Avant de diriger un numéro vers une réponse :

• Un numéro capable de recevoir des appels. Ouvrez Voice > Numbers et vérifiez la colonne Directions pour une marque entrante. Un numéro que vous avez enregistré comme identifiant d'appelant depuis un autre opérateur ne reçoit pas d'appels ici : c'est cet opérateur qui achemine les appels vers ce numéro, il ne porte donc aucune réponse.
• Pour une livraison vers un trunk : un trunk SIP avec les appels entrants activés et au moins une passerelle de livraison.
• Pour un transfert : un identifiant d'appelant vérifié vers lequel transférer.
• Pour une séquence : une séquence active et publiée dans le même espace de travail, avec une entrée d'appel qui accepte des données d'entrée vides. Sous Inbound routing, sélectionnez Run a sequence, choisissez la séquence et l'entrée d'appel, puis enregistrez. Le guide du concepteur de séquences explique la publication et les testeurs de brouillons entrants.
• Pour modifier le paramètre via API ou CLI : une clé API disposant du scope voice_management en écriture. Ce scope couvre la configuration vocale ; le scope voice couvre le trafic d'appels et les statistiques, donc la lecture du journal d'appels nécessite l'autre.

Livrer les appels à un trunk SIP

La livraison appelle votre propre système téléphonique aux adresses que vous déclarez sur le trunk. Activez d'abord la direction, car un numéro ne peut être dirigé que vers un trunk qui accepte déjà les appels entrants.

1. Ouvrez Voice > SIP Trunks, ouvrez le trunk, et sous Inbound calling sélectionnez Enable inbound.
2. Ajoutez au moins une passerelle dans la même section. Un trunk sans passerelle refuse chaque appel entrant vers les numéros auxquels il répond.
3. Ouvrez Voice > Numbers, ouvrez le numéro, et sous Inbound routing choisissez Deliver to a SIP trunk.
4. Sélectionnez le trunk et cliquez sur Save. Seuls les trunks avec les appels entrants activés apparaissent dans la liste.

La colonne Used for dans la liste Numbers affiche alors le numéro comme livré à ce trunk, et la page du trunk liste les numéros auxquels il répond.

Via API, mettez à jour le trunk avec inbound_enabled: true, ajoutez une passerelle, puis dirigez l'enregistrement vocal du numéro vers le trunk. L'enregistrement vocal possède un ID commençant par vnu_, différent de l'ID nda_ que /v1/numbers renvoie pour le même numéro. Passer l'ID nda_ à une opération de numéro vocal est refusé avec 422. Pour trouver l'enregistrement vocal, recherchez vos numéros vocaux par les chiffres du numéro :

for await (const number of bird.voice.numbers.list({ search: "31201234567" })) {
  console.log(number.id, number.phone_number);
}

for number, err := range client.Voice.Numbers.List(context.Background(), bird.VoiceNumbersListParams{
	Search: "31201234567",
}) {
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(number.Id, number.PhoneNumber)
}

foreach ($bird->voice->numbers->list(['search' => '31201234567']) as $number) {
    echo $number->getId(), ' ', $number->getPhoneNumber(), "\n";
}

bird voice numbers list --search 31201234567

curl -X GET "https://{region}.platform.bird.com/v1/voice/numbers" \
  -H "Authorization: Bearer $TOKEN" \
  --url-query "search=31201234567"

Chaque résultat porte son id, son phone_number et la inbound_configuration.route actuelle. Envoyez la route trunk à mettre à jour le numéro vocal avec cet id :

const number = await bird.voice.numbers.update("NUMBER_ID", {
  inbound_configuration: {
    route: { type: "trunk", trunk_id: "spt_01krdgeqcxet5s7t44vh8rt9mg" },
  },
});
console.log(number.id, number.inbound_configuration?.route?.type);

var route bird.VoiceCallRouteWritable
if err := route.FromVoiceCallRouteTrunk(bird.VoiceCallRouteTrunk{
	TrunkId: "spt_01krdgeqcxet5s7t44vh8rt9mg",
}); err != nil {
	log.Fatal(err)
}
number, err := client.Voice.Numbers.Update(context.Background(), "NUMBER_ID", bird.VoiceNumbersUpdateParams{
	InboundConfiguration: &bird.VoiceInboundConfigurationPut{Route: route},
})
if err != nil {
	log.Fatal(err)
}
fmt.Println(number.Id)

$number = $bird->voice->numbers->update(
    'NUMBER_ID',
    (new VoiceNumberUpdate())->setInboundConfiguration(
        (new VoiceInboundConfigurationPut())->setRoute([
            'type' => 'trunk',
            'trunk_id' => 'spt_01krdgeqcxet5s7t44vh8rt9mg',
        ]),
    ),
);
echo $number->getId(), "\n";

bird voice numbers update <number-id> --body-file - <<'JSON'
{
  "inbound_configuration": {
    "route": {
      "type": "trunk",
      "trunk_id": "spt_01krdgeqcxet5s7t44vh8rt9mg"
    }
  }
}
JSON

curl -X PATCH "https://{region}.platform.bird.com/v1/voice/numbers/{number_id}" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "inbound_configuration": {
      "route": {
        "type": "trunk",
        "trunk_id": "spt_01krdgeqcxet5s7t44vh8rt9mg"
      }
    }
  }'

Un trunk dont les appels entrants sont désactivés est refusé avec 412 et E21052. La route remplace ce que le numéro avait auparavant. Envoyer {"type": "reject"} comme route refuse les appelants quel que soit le défaut, et envoyer null ramène le numéro à la route par défaut de l'espace de travail.

Ce dont une passerelle a besoin

Une passerelle est une adresse vers laquelle un appel est livré, ainsi que la façon dont ce pair souhaite que les deux numéros de l'appel soient formatés :

Les passerelles partageant une même priorité reçoivent une part égale des appels, et n'importe laquelle peut être essayée en premier pour un appel donné. Pour basculer la livraison vers une deuxième adresse, attribuez à cette passerelle un numéro de priorité plus élevé : elle est essayée lorsque la première ne répond pas.

Les deux formats de numéro sont des modèles utilisant un seul espace réservé, {number}, qui représente le numéro sans son + initial. Le format de destination est placé devant l'hôte de l'URI SIP, de sorte que 1234#{number} livre un appel vers +31201234567 sous la forme sip:1234#31201234567@pbx.example.com:5060. La valeur par défaut pour les deux est +{number}, soit E.164. Un format ne contenant aucun {number} envoie chaque numéro auquel le trunk répond vers une seule adresse fixe. Un pair qui attend les numéros sans le + utilise {number} seul comme format.

Via API, ajoutez une passerelle au trunk avec ces paramètres. Activez d'abord les appels entrants du trunk : créer une passerelle sur un trunk sans cette activation est refusé avec 412 et E21052.

const gateway = await bird.voice.trunks.gateways.create("TRUNK_ID", {
  sip_uri: "sip:pbx.example.com:5060",
  priority: 0,
  destination_format: "1234#{number}",
});
console.log(gateway.id, gateway.priority);

gateway = client.voice.trunks.gateways.create(
    "TRUNK_ID",
    sip_uri="sip:pbx.example.com:5060",
    priority=0,
    destination_format="1234#{number}",
)
print(gateway.id, gateway.priority)

gateway, err := client.Voice.Trunks.Gateways.Create(context.Background(), "TRUNK_ID", bird.VoiceTrunksGatewaysCreateParams{
	SipURI:            "sip:pbx.example.com:5060",
	Priority:          0,
	DestinationFormat: bird.Ptr("1234#{number}"),
})
if err != nil {
	log.Fatal(err)
}
fmt.Println(gateway.Id, gateway.Priority)

$gateway = $bird->voice->trunks->gateways->create(
    'TRUNK_ID',
    (new VoiceTrunkGatewayCreate())
        ->setSipUri('sip:pbx.example.com:5060')
        ->setPriority(0)
        ->setDestinationFormat('1234#{number}'),
);
echo $gateway->getId(), ' ', $gateway->getPriority(), "\n";

bird voice trunks gateways create <trunk-id> \
  --destination-format '1234#{number}' \
  --priority 0 \
  --sip-uri sip:pbx.example.com:5060

curl -X POST "https://{region}.platform.bird.com/v1/voice/trunks/{trunk_id}/gateways" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sip_uri": "sip:pbx.example.com:5060",
    "priority": 0,
    "destination_format": "1234#{number}"
  }'

Mettez à jour une passerelle pour modifier sa priorité ou ses formats par la suite.

Attention : désactiver les appels entrants sur un trunk, ou supprimer le trunk, renvoie chaque numéro qui y pointait vers la route par défaut de l'espace de travail. Une route par défaut de l'espace de travail qui désignait ce trunk revient à rejeter. Réactiver les appels entrants ne restaure ni l'un ni l'autre : chaque numéro doit être pointé à nouveau vers un trunk.

Définir une route par défaut

La route par défaut de l'espace de travail répond aux appels pour chaque numéro sans route propre. Elle démarre sur le rejet. Un numéro possédant sa propre route la conserve lorsque la route par défaut change.

1. Ouvrez Voice > Numbers.
2. À côté de Calls to numbers without their own route, sélectionnez Change, choisissez la réponse, puis enregistrez.

La modification s'applique dès le prochain appel que chacun de ces numéros reçoit. Via API, mettez à jour les paramètres vocaux :

curl -X PATCH "https://{region}.platform.bird.com/v1/voice/settings" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "inbound_configuration": {
      "route": {
        "type": "trunk",
        "trunk_id": "spt_01krdgeqcxet5s7t44vh8rt9mg"
      }
    }
  }'

La route par défaut est vérifiée de la même manière que la route d'un numéro. Pour ramener un numéro à la route par défaut, définissez sa route sur null, ou choisissez Use the workspace default sur le numéro.

Transférer les appels vers un autre numéro

Un transfert répond à l'appel entrant, passe un second appel vers un numéro que vous avez vérifié, puis connecte les deux.

1. Ouvrez Voice > Numbers, ouvrez le numéro, et sous Inbound routing choisissez Forward to another number.
2. Sélectionnez le numéro vers lequel transférer. La liste contient vos identifiants d'appelant vérifiés, car un transfert ne peut cibler qu'un numéro dont vous avez prouvé le contrôle.
3. Choisissez quel numéro l'appel transféré affiche comme appelant, puis sélectionnez Save.

Via API, recherchez vos numéros vocaux par les chiffres du numéro pour lire son identifiant vnu_, puis envoyez une route forward avec forward_to et forward_as :

const number = await bird.voice.numbers.update("NUMBER_ID", {
  inbound_configuration: {
    route: { type: "forward", forward_to: "+14155551234", forward_as: "dialed_number" },
  },
});
console.log(number.id, number.inbound_configuration?.route?.type);

var route bird.VoiceCallRouteWritable
if err := route.FromVoiceCallRouteForward(bird.VoiceCallRouteForward{
	ForwardTo: "+14155551234",
	ForwardAs: "dialed_number",
}); err != nil {
	log.Fatal(err)
}
number, err := client.Voice.Numbers.Update(context.Background(), "NUMBER_ID", bird.VoiceNumbersUpdateParams{
	InboundConfiguration: &bird.VoiceInboundConfigurationPut{Route: route},
})
if err != nil {
	log.Fatal(err)
}
fmt.Println(number.Id)

$number = $bird->voice->numbers->update(
    'NUMBER_ID',
    (new VoiceNumberUpdate())->setInboundConfiguration(
        (new VoiceInboundConfigurationPut())->setRoute([
            'type' => 'forward',
            'forward_to' => '+14155551234',
            'forward_as' => 'dialed_number',
        ]),
    ),
);
echo $number->getId(), "\n";

bird voice numbers update <number-id> --route forward --forward-to +14155551234 --forward-as dialed_number

curl -X PATCH "https://{region}.platform.bird.com/v1/voice/numbers/{number_id}" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "inbound_configuration": {
      "route": {
        "type": "forward",
        "forward_to": "+14155551234",
        "forward_as": "dialed_number"
      }
    }
  }'

forward_to doit être un identifiant d'appelant dont la vérification est terminée. Un numéro que vous n'avez pas enregistré, ou dont la vérification est pending ou failed, est refusé avec 412 et E21053. Identifiants d'appelant couvre l'enregistrement et la vérification d'un numéro via API.

La cible du transfert est vérifiée au moment où vous la définissez et à nouveau à chaque appel transféré. Un identifiant d'appelant que vous supprimez par la suite arrête le transfert au lieu de continuer, et les appels entrants sont rejetés à partir de ce moment.

L'appel transféré sonne pendant 45 secondes avant d'être abandonné, soit plus longtemps qu'une livraison par trunk, car l'extrémité distante est généralement le téléphone d'une personne et non un système téléphonique.

Le transfert passe un appel, donc les règles sortantes s'appliquent au second segment : transférer vers un pays que vous n'avez pas activé sous Destinations est refusé avec destination_not_enabled.

Un transfert, deux enregistrements d'appel

Un appel transféré produit deux traces de segment partageant un même call_id :

Utilisez le filtre call_id dans la liste des segments pour trouver les connexions liées, ou ouvrez Voice > Calls. L'enregistrement d'arrivée est celui qui indique ce que le numéro était configuré pour faire.

Choisir quel numéro un appel transféré affiche comme appelant

Un appel transféré dispose de deux numéros qu'il peut présenter à la personne qui répond, et le choix modifie à la fois ce qu'elle voit et la probabilité qu'un opérateur interfère avec l'appel :

• Numéro appelant est le propre numéro de l'appelant : le téléphone sonne comme s'il avait composé directement et l'appel peut être rappelé depuis le journal d'appels. Comme le numéro ne vous appartient pas, certains opérateurs, le plus souvent aux États-Unis et dans certaines parties de l'Europe, marquent ces appels comme non vérifiés, remplacent le numéro ou les filtrent.
• Numéro composé est le numéro que l'appelant a composé, qui est l'un des vôtres. La personne qui répond voit lequel de vos numéros a été appelé plutôt que qui a appelé.

Indiquez le choix pour chaque transfert que vous configurez via API ou CLI. Une ancienne configuration sans choix enregistré renvoie le numéro composé.

Le champ inbound_configuration.forward_as_options du numéro liste les choix disponibles pour l'éditeur. Les options comprennent le numéro appelant et le numéro composé. Consultez ces options lors de la création d'une intégration, et utilisez le forward_as renvoyé pour confirmer le paramètre effectif.

En lecture, forward_as est la valeur que les appels portent réellement, qui peut différer de la dernière valeur écrite.

Consulter ce qu'un numéro a fait d'un appel

L'enregistrement d'un appel entrant porte un route en plus de son statut, et route est ce que le numéro était configuré pour faire au moment où l'appel a été traité. Modifier le paramètre du numéro par la suite ne change pas ce qu'indiquent ses appels passés.

route indique ce que le numéro était configuré pour faire, pas que cela a fonctionné. Une route trunk sur un appel qui ne s'est jamais connecté signifie un numéro dirigé vers un trunk qui n'a pas pris l'appel, et c'est le statut de l'appel qui porte le résultat. route est absent sur les appels sortants et sur les appels enregistrés avant l'existence du champ.

Dans le tableau de bord, ouvrez l'appel depuis Voice > Legs et consultez la ligne Inbound route, qui renvoie au numéro dont les paramètres l'ont déterminé. Via API, route se trouve sur GET /v1/voice/legs/{leg_id} et GET /v1/voice/legs, et direction filtre la liste sur les appels entrants.

Pour une route de type séquence, consultez également la page Runs de la séquence afin d'identifier le point d'entrée et la version exécutés. La configuration actuelle du numéro peut différer de la version conservée pour un appel antérieur.

Diagnostiquer un appel entrant refusé

Un appel entrant refusé est enregistré avec le statut rejected. Deux situations différentes le produisent, et rejection_reason est ce qui les distingue :

• Rejeté sans rejection_reason. Le numéro lui-même a refusé l'appel. L'appel n'a échoué à aucun de nos contrôles, il n'indique donc aucune raison, et route indique ce que le numéro était configuré pour faire. Une route reject signifie un numéro configuré pour refuser, ou un numéro sans route propre alors que la route par défaut de l'espace de travail est le rejet.
• Rejeté avec un rejection_reason. L'appel a échoué à l'un de nos contrôles avant d'atteindre votre système téléphonique. La raison nomme le contrôle. Appels rejetés liste chaque raison et sa correction.

failed est un statut différent et ne signifie pas refusé : il signifie que l'appel a été tenté et n'a pas abouti, sip_response_code portant la réponse reçue.

Lisez route et rejection_reason ensemble pour distinguer les refus :

Les plafonds du compte s'appliquent aussi aux appels entrants : au-delà du solde de votre portefeuille, de la limite de dépenses vocales quotidiennes de votre organisation, ou de vos plafonds de simultanéité et de débit par seconde, un appel entrant est rejeté avec la raison correspondante. Vue d'ensemble Voice couvre les plafonds eux-mêmes.

Vérifier le coût d'un appel reçu

La réception d'un appel est facturée. Le tarif dépend du pays et du type du numéro qui le reçoit, et est publié par pays sous Receiving calls sur la page de tarification vocale, aux côtés des tarifs pour les appels que vous passez.

Un transfert est facturé comme deux appels : l'appel entrant au tarif de réception, et le segment que nous passons au tarif sortant pour le numéro vers lequel vous transférez. Des frais de traitement uniques sont facturés une seule fois pour l'appel et non une fois par segment.

Le portefeuille est vérifié avant la livraison d'un appel entrant : un solde insuffisant pour le couvrir signifie que l'appel est rejeté plutôt que facturé après coup. Coûts et facturation couvre le fonctionnement du temps facturable, des tarifs et du portefeuille dans les deux sens.

Étapes suivantes