Ricevere chiamate

Un numero del tuo spazio di lavoro può consegnare una chiamata in entrata a un trunk SIP, inoltrarla a un numero verificato, eseguire una sequenza pubblicata o rifiutarla. Un numero ha una sola rotta alla volta: la propria, oppure la rotta predefinita dello spazio di lavoro quando non ne ha una.

La rotta predefinita dello spazio di lavoro parte su rifiuto, quindi un numero che nessuno ha configurato respinge i chiamanti anziché restare senza risposta. Modifica la rotta predefinita per dare a ogni numero in questa condizione la stessa risposta. Vedi Impostare una rotta predefinita.

Per gestire le chiamate in arrivo in un flusso nativo di Bird, pubblica una sequenza e associa il numero al suo ingresso di chiamata. L'ingresso selezionato deve accettare dati vuoti.

Prerequisiti

Prima di indirizzare un numero verso una risposta:

• Un numero che può ricevere chiamate. Apri Voice > Numbers e controlla la colonna Directions per un contrassegno inbound. Un numero registrato come caller ID da un altro operatore non riceve chiamate qui: quell'operatore instrada le chiamate dirette a esso, quindi non porta alcuna risposta.
• Per la consegna a un trunk: un trunk SIP con le chiamate in entrata attive e almeno un gateway di consegna.
• Per un inoltro: un caller ID verificato verso cui inoltrare.
• Per una sequenza: una sequenza attiva e pubblicata nello stesso spazio di lavoro, con un punto di ingresso della chiamata che accetta dati di ingresso vuoti. Sotto Inbound routing, seleziona Run a sequence, scegli la sequenza e il punto di ingresso e salva. La guida al builder di sequenze spiega la pubblicazione e i tester delle bozze per le chiamate in entrata.
• Per modificare l'impostazione tramite API o CLI: una chiave API con lo scope voice_management a livello di scrittura. Quello scope copre la configurazione vocale; lo scope voice copre il traffico e le statistiche delle chiamate, quindi la lettura del registro chiamate richiede l'altro.

Consegnare le chiamate a un trunk SIP

La consegna chiama il tuo centralino agli indirizzi che dichiari sul trunk. Attiva prima la direzione, perché un numero può essere indirizzato solo verso un trunk che già accetta chiamate in entrata.

1. Apri Voice > SIP Trunks, apri il trunk e sotto Inbound calling seleziona Enable inbound.
2. Aggiungi almeno un gateway nella stessa sezione. Un trunk senza gateway rifiuta ogni chiamata in entrata verso i numeri a cui risponde.
3. Apri Voice > Numbers, apri il numero e sotto Inbound routing scegli Deliver to a SIP trunk.
4. Scegli il trunk e seleziona Save. Nell'elenco compaiono solo i trunk con le chiamate in entrata attive.

La colonna Used for nell'elenco Numbers mostra quindi il numero come consegnato a quel trunk, e la pagina del trunk elenca i numeri a cui risponde.

Tramite API, aggiorna il trunk con inbound_enabled: true, aggiungi un gateway, poi indirizza il record vocale del numero verso il trunk. Il record vocale ha un ID che inizia con vnu_, diverso dall'ID nda_ che /v1/numbers restituisce per lo stesso numero. Passare l'ID nda_ a un'operazione su un numero vocale viene rifiutato con 422. Per trovare il record vocale, cerca tra i tuoi numeri vocali le cifre del numero:

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"

Ogni risultato porta il suo id, il suo phone_number e la inbound_configuration.route attuale. Invia la rotta trunk per aggiornare il numero vocale con quel 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 con le chiamate in entrata disattivate viene rifiutato con 412 e E21052. La rotta sostituisce qualsiasi impostazione precedente del numero. Inviare {"type": "reject"} come rotta respinge i chiamanti indipendentemente dal valore predefinito, e inviare null riporta il numero alla rotta predefinita dello spazio di lavoro.

Cosa serve a un gateway

Un gateway è un indirizzo a cui viene consegnata una chiamata, insieme al modo in cui quel peer vuole che i due numeri della chiamata siano formattati:

I gateway con la stessa priorità ricevono una quota uguale di chiamate, e ognuno di essi può essere provato per primo su una data chiamata. Per trasferire la consegna a un secondo indirizzo, assegna a quel gateway un numero di priorità più alto: viene provato quando il primo non risponde.

Entrambi i formati dei numeri sono template basati su un segnaposto, {number}, che rappresenta il numero senza il + iniziale. Il formato di destinazione viene posto prima dell'host URI SIP, quindi 1234#{number} consegna una chiamata a +31201234567 come sip:1234#31201234567@pbx.example.com:5060. Il valore predefinito per entrambi è +{number}, cioè E.164. Un formato che non contiene alcun {number} invia tutti i numeri a cui il trunk risponde a un unico indirizzo fisso. Un peer che si aspetta numeri senza il + usa {number} da solo come formato.

Tramite API, aggiungi un gateway al trunk con queste impostazioni. Attiva prima le chiamate in entrata del trunk: creare un gateway su un trunk senza di esse viene rifiutato con 412 e 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}"
  }'

Aggiorna un gateway per modificarne la priorità o i formati in seguito.

Attenzione: disattivare le chiamate in entrata su un trunk, o eliminare il trunk, riporta ogni numero che lo utilizzava al percorso predefinito dello spazio di lavoro. Un percorso predefinito che fa riferimento a quel trunk torna a rifiutare. Riattivare le chiamate in entrata non ripristina nessuna delle due configurazioni, quindi ogni numero deve essere associato di nuovo a un trunk.

Impostare una rotta predefinita

La rotta predefinita dello spazio di lavoro risponde alle chiamate per ogni numero privo di una propria rotta. Parte come rifiuto. Un numero con una propria rotta la mantiene quando la rotta predefinita cambia.

1. Apri Voice > Numbers.
2. Accanto a Calls to numbers without their own route, seleziona Change, scegli la risposta e salva.

La modifica si applica dalla chiamata successiva che ciascuno di quei numeri riceve. Tramite API, aggiorna le impostazioni vocali:

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 rotta predefinita viene verificata allo stesso modo della rotta di un numero. Per riportare un numero alla rotta predefinita, imposta la sua rotta su null, oppure scegli Use the workspace default sul numero.

Inoltrare le chiamate a un altro numero

Un inoltro risponde alla chiamata in entrata e ne effettua una seconda verso un numero che hai verificato, poi collega le due.

1. Apri Voice > Numbers, apri il numero e sotto Inbound routing scegli Forward to another number.
2. Scegli il numero verso cui inoltrare. L'elenco contiene i tuoi caller ID verificati, perché un inoltro può avere come destinazione solo un numero di cui hai dimostrato il controllo.
3. Scegli quale numero la chiamata inoltrata mostra come chiamante, poi seleziona Save.

Tramite API, cerca i tuoi numeri vocali in base alle cifre del numero per leggere il suo ID vnu_, poi invia una rotta forward con forward_to e 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 deve essere un caller ID la cui verifica è completata. Un numero che non hai registrato, o la cui verifica è pending o failed, viene rifiutato con 412 e E21053. Caller IDs tratta la registrazione e la verifica tramite API.

La destinazione dell'inoltro viene verificata quando la imposti e di nuovo a ogni chiamata inoltrata. Un caller ID che rimuovi in seguito interrompe l'inoltro anziché proseguire, e le chiamate in entrata vengono rifiutate da quel momento.

La chiamata inoltrata squilla per 45 secondi prima di essere abbandonata, un tempo più lungo rispetto alla consegna a un trunk perché il destinatario è di solito il telefono di una persona e non un centralino.

L'inoltro effettua una chiamata, quindi le regole in uscita si applicano alla seconda tratta: l'inoltro verso un paese che non hai attivato sotto Destinations viene rifiutato con destination_not_enabled.

Un inoltro, due record di chiamata

Una chiamata inoltrata produce due record dei leg che condividono un call_id:

Usa il filtro call_id nell'elenco dei leg per trovare le connessioni correlate oppure apri Voice > Calls. Il record in arrivo indica come era configurato il numero.

Scegliere quale numero una chiamata inoltrata mostra come chiamante

Una chiamata inoltrata ha due numeri che potrebbe presentare a chi risponde, e la scelta cambia sia ciò che vedono sia la probabilità che un operatore interferisca con la chiamata:

• Numero chiamante è il numero del chiamante stesso, quindi il telefono squilla come se avesse composto il numero direttamente e la chiamata può essere restituita dal registro chiamate. Poiché il numero non è uno dei tuoi, alcuni operatori, più spesso negli USA e in parti d'Europa, contrassegnano tali chiamate come non verificate, sostituiscono il numero o le filtrano.
• Numero composto è il numero che il chiamante ha composto, che è uno dei tuoi. Chi risponde vede quale dei tuoi numeri è stato chiamato anziché chi ha chiamato.

Specifica la scelta su ogni inoltro che configuri tramite API o CLI. Una configurazione precedente senza una scelta memorizzata restituisce in lettura il numero composto.

Il campo inbound_configuration.forward_as_options del numero elenca le scelte disponibili per l'editor. Le opzioni attuali includono il numero chiamante e il numero composto. Leggi quelle opzioni quando costruisci un'integrazione e usa il forward_as restituito per confermare l'impostazione effettiva.

In lettura, forward_as è il valore che le chiamate effettivamente portano, che può differire dall'ultimo valore scritto.

Leggere cosa ha fatto un numero con una chiamata

Il record di una chiamata in entrata porta un route insieme al suo stato, e route indica cosa il numero era impostato per fare al momento della gestione della chiamata. Modificare l'impostazione del numero in seguito non cambia ciò che le sue chiamate passate riportano.

route indica cosa il numero era impostato per fare, non che abbia funzionato. Una rotta trunk su una chiamata mai connessa è un numero indirizzato verso un trunk che non ha accettato la chiamata, e lo stato della chiamata è ciò che riporta l'esito. route è assente sulle chiamate in uscita e sulle chiamate registrate prima dell'esistenza del campo.

Nella dashboard, apri la chiamata da Voice > Legs e leggi la riga Inbound route, che rimanda al numero le cui impostazioni l'hanno determinata. Tramite API, route si trova su GET /v1/voice/legs/{leg_id} e GET /v1/voice/legs, e direction filtra l'elenco sulle chiamate in entrata.

Per una rotta di tipo sequenza, controlla anche la pagina Runs della sequenza per identificare il punto di ingresso e la versione eseguiti. La configurazione attuale del numero può differire dalla versione conservata da una chiamata precedente.

Diagnosticare una chiamata in entrata rifiutata

Una chiamata in entrata rifiutata viene registrata con lo stato rejected. Due cause diverse lo producono, e rejection_reason è ciò che le distingue:

• Rifiutata senza rejection_reason. Il numero stesso ha respinto la chiamata. La chiamata non ha fallito alcun nostro controllo, quindi non indica alcun motivo, e route indica come era impostato il numero. Una rotta reject è un numero impostato per rifiutare, o uno senza una propria rotta mentre la rotta predefinita dello spazio di lavoro è rifiuto.
• Rifiutata con un rejection_reason. La chiamata ha fallito uno dei nostri controlli prima di raggiungere il tuo centralino. Il motivo indica il controllo. Chiamate rifiutate elenca ogni motivo e la relativa soluzione.

failed è uno stato diverso e non significa rifiutata: significa che la chiamata è stata tentata e non ha funzionato, con sip_response_code che riporta la risposta ricevuta.

Leggi route e rejection_reason insieme per distinguere i rifiuti:

I limiti dell'account si applicano anche alle chiamate in entrata: oltre il saldo del wallet, il limite di spesa vocale giornaliero della tua organizzazione, o i tuoi limiti di concorrenza e al secondo, una chiamata in entrata viene rifiutata con il motivo corrispondente. Panoramica Voice tratta i limiti stessi.

Verificare il costo di una chiamata ricevuta

Ricevere una chiamata ha un costo. La tariffa dipende dal paese e dal tipo del numero che la riceve, ed è pubblicata per paese sotto Receiving calls nella pagina dei prezzi Voice, insieme alle tariffe per le chiamate che effettui.

Un inoltro viene fatturato come due chiamate: la chiamata in arrivo alla tariffa di ricezione e il leg che effettuiamo alla tariffa in uscita per il numero verso cui inoltri. Un'unica commissione di gestione viene addebitata una volta per la chiamata anziché una per leg.

Il wallet viene verificato prima che una chiamata in entrata sia consegnata, quindi un saldo insufficiente a coprirla significa che la chiamata viene rifiutata anziché addebitata in seguito. Costi e fatturazione spiega come funzionano il tempo fatturabile, le tariffe e il wallet per entrambe le direzioni.

Passaggi successivi