Anrufe empfangen

Eine Nummer Ihres Workspace kann einen eingehenden Anruf an einen SIP-Trunk zustellen, an eine verifizierte Nummer weiterleiten, eine veröffentlichte Sequenz ausführen oder ihn ablehnen. Eine Nummer hat jeweils eine Route: ihre eigene oder die Standardroute Ihres Workspace, wenn sie keine hat.

Die Standardroute des Workspace ist anfänglich auf „Ablehnen" gesetzt, sodass eine Nummer, die niemand konfiguriert hat, Anrufer abweist, anstatt gar keine Antwort zu geben. Ändern Sie die Standardroute, um all diesen Nummern dieselbe Antwort zu geben. Siehe Standardroute festlegen.

Um eingehende Anrufe in einem nativen Bird-Ablauf zu bearbeiten, veröffentlichen Sie eine Sequenz und verknüpfen Sie die Nummer mit ihrem Anrufeinstieg. Der ausgewählte Einstieg muss leere Daten akzeptieren.

Voraussetzungen

Bevor Sie eine Nummer auf eine Antwort richten:

• Eine Nummer, die Anrufe empfangen kann. Öffnen Sie Voice > Numbers und prüfen Sie die Spalte Directions auf eine Inbound-Markierung. Eine Nummer, die Sie als Anrufer-ID eines anderen Anbieters registriert haben, empfängt hier keine Anrufe: Dieser Anbieter leitet die an sie gerichteten Anrufe weiter, daher trägt sie keine Antwort.
• Für die Zustellung an einen Trunk: ein SIP-Trunk mit aktiviertem Inbound-Calling und mindestens einem Zustellungs-Gateway.
• Für eine Weiterleitung: eine verifizierte Anrufer-ID, an die weitergeleitet werden soll.
• Für eine Sequenz: eine aktive, veröffentlichte Sequenz im selben Workspace mit einem Anrufeinstieg, der leere Einstiegsdaten akzeptiert. Wählen Sie unter Inbound routing die Option Run a sequence, wählen Sie die Sequenz und den Anrufeinstieg aus und speichern Sie. Der Leitfaden zum Sequenz-Builder erklärt die Veröffentlichung und Tester für eingehende Entwurfsanrufe.
• Um die Einstellung über die API oder CLI zu ändern: ein API-Schlüssel mit dem Scope voice_management auf Schreibebene. Dieser Scope deckt die Voice-Konfiguration ab; der Scope voice deckt Anrufverkehr und Statistiken ab, sodass Sie zum Lesen des Anrufprotokolls den anderen benötigen.

Anrufe an einen SIP-Trunk zustellen

Die Zustellung wählt Ihre eigene Telefonanlage unter den Adressen an, die Sie am Trunk angegeben haben. Aktivieren Sie zuerst die Richtung, da eine Nummer nur auf einen Trunk verweisen kann, der bereits eingehende Anrufe akzeptiert.

1. Öffnen Sie Voice > SIP Trunks, öffnen Sie den Trunk und wählen Sie unter Inbound calling die Option Enable inbound.
2. Fügen Sie mindestens ein Gateway im selben Abschnitt hinzu. Ein Trunk ohne Gateway lehnt jeden eingehenden Anruf an die von ihm beantworteten Nummern ab.
3. Öffnen Sie Voice > Numbers, öffnen Sie die Nummer und wählen Sie unter Inbound routing die Option Deliver to a SIP trunk.
4. Wählen Sie den Trunk aus und klicken Sie auf Save. In der Liste erscheinen nur Trunks mit aktiviertem Inbound-Calling.

Die Spalte Used for in der Numbers-Liste zeigt die Nummer dann als an diesen Trunk zugestellt an, und die Seite des Trunks listet die Nummern auf, die er beantwortet.

Über die API aktualisieren Sie den Trunk mit inbound_enabled: true, fügen ein Gateway hinzu und verweisen dann den Voice-Datensatz der Nummer auf den Trunk. Der Voice-Datensatz hat eine ID, die mit vnu_ beginnt und sich von der nda_-ID unterscheidet, die /v1/numbers für dieselbe Nummer zurückgibt. Die Übergabe der nda_-ID an eine Voice-Nummernoperation wird mit 422 abgelehnt. Um den Voice-Datensatz zu finden, durchsuchen Sie Ihre Voice-Nummern nach den Ziffern der Nummer:

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"

Jedes Ergebnis enthält seine id, seine phone_number und die aktuelle inbound_configuration.route. Senden Sie die Trunk-Route an Voice-Nummer aktualisieren mit dieser 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"
      }
    }
  }'

Ein Trunk mit deaktiviertem Inbound-Calling wird mit 412 und E21052 abgelehnt. Die Route ersetzt das, was die Nummer vorher hatte. {"type": "reject"} als Route zu senden weist Anrufer unabhängig vom Standard ab, und null zu senden gibt die Nummer an die Standard-Route des Workspace zurück.

Was ein Gateway benötigt

Ein Gateway ist eine Adresse, an die ein Anruf zugestellt wird, sowie die Art, wie diese Gegenstelle die beiden Rufnummern des Anrufs formatiert haben möchte:

Gateways mit gleicher Priorität teilen sich die Anrufe gleichmäßig auf, und bei einem bestimmten Anruf kann jedes von ihnen zuerst versucht werden. Um die Zustellung an eine zweite Adresse weiterzuleiten, geben Sie diesem Gateway eine höhere Prioritätsnummer: Es wird versucht, wenn das erste nicht antwortet.

Beide Nummernformate sind Templates mit einem Platzhalter, {number}, der für die Nummer ohne die vorangestellte + steht. Das Zielformat wird vor den SIP-URI-Host gesetzt, sodass 1234#{number} einen Anruf an +31201234567 als sip:1234#31201234567@pbx.example.com:5060 zustellt. Der Standardwert für beide ist +{number}, also E.164. Ein Format ohne {number} leitet jede Nummer, die der Trunk beantwortet, an eine feste Adresse. Eine Gegenstelle, die Nummern ohne die + erwartet, nimmt {number} allein als Format.

Über die API fügen Sie dem Trunk ein Gateway hinzu mit diesen Einstellungen. Aktivieren Sie zuerst das Inbound-Calling des Trunks: Ein Gateway auf einem Trunk ohne aktiviertes Inbound-Calling wird mit 412 und E21052 abgelehnt.

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

Aktualisieren Sie ein Gateway, um seine Priorität oder Formate später zu ändern.

Warnung: Wenn Sie eingehende Anrufe auf einem Trunk deaktivieren oder den Trunk löschen, fällt jede Nummer, die auf ihn zeigt, auf die Standard-Route des Workspace zurück. Eine Standard-Route des Workspace, die den Trunk benennt, wird wieder auf Ablehnung gesetzt. Das erneute Aktivieren eingehender Anrufe stellt beides nicht wieder her – jede Nummer muss erneut auf einen Trunk gerichtet werden.

Standard-Route festlegen

Die Standard-Route des Workspace beantwortet Anrufe für jede Nummer ohne eigene Route. Sie startet auf „Ablehnen". Eine Nummer mit eigener Route behält diese, wenn sich die Standard-Route ändert.

1. Öffnen Sie Voice > Numbers.
2. Wählen Sie neben Calls to numbers without their own route die Option Change, wählen Sie die Antwort aus und speichern Sie.

Die Änderung gilt ab dem nächsten Anruf, den jede dieser Nummern empfängt. Über die API aktualisieren Sie die Voice-Einstellungen:

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

Die Standard-Route wird genauso geprüft wie die Route einer Nummer. Um eine Nummer auf die Standard-Route zurückzusetzen, setzen Sie ihre Route auf null, oder wählen Sie Use the workspace default an der Nummer.

Anrufe an eine andere Nummer weiterleiten

Eine Weiterleitung nimmt den eingehenden Anruf an, baut einen zweiten Anruf zu einer von Ihnen verifizierten Nummer auf und verbindet dann beide.

1. Öffnen Sie Voice > Numbers, öffnen Sie die Nummer und wählen Sie unter Inbound routing die Option Forward to another number.
2. Wählen Sie die Nummer aus, an die weitergeleitet werden soll. Die Liste enthält Ihre verifizierten Anrufer-IDs, da eine Weiterleitung nur auf eine Nummer verweisen darf, deren Kontrolle Sie nachgewiesen haben.
3. Wählen Sie, welche Nummer der weitergeleitete Anruf als Anrufer anzeigt, und klicken Sie dann auf Save.

Über die API durchsuchen Sie Ihre Voice-Nummern nach den Ziffern der Nummer, um ihre vnu_-ID auszulesen, und senden Sie dann eine forward-Route mit forward_to und 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 muss eine Anrufer-ID sein, deren Verifizierung abgeschlossen ist. Eine nicht registrierte Nummer oder eine, deren Verifizierung pending oder failed ist, wird mit 412 und E21053 abgelehnt. Anrufer-IDs behandelt die Registrierung und Verifizierung über die API.

Das Weiterleitungsziel wird geprüft, wenn Sie es festlegen, und erneut bei jedem Anruf, den es weiterleitet. Eine Anrufer-ID, die Sie später entfernen, stoppt die Weiterleitung, anstatt weiterzuarbeiten, und die eingehenden Anrufe werden ab diesem Zeitpunkt abgelehnt.

Der weitergeleitete Anruf klingelt 45 Sekunden, bevor er aufgegeben wird. Das ist länger als bei einer Trunk-Zustellung, weil die Gegenseite in der Regel das Telefon einer Person ist und keine Telefonanlage.

Eine Weiterleitung baut einen Anruf auf, daher gelten die Outbound-Regeln für den zweiten Abschnitt: Eine Weiterleitung in ein Land, das Sie unter Destinations nicht aktiviert haben, wird mit destination_not_enabled abgelehnt.

Eine Weiterleitung, zwei Anrufdatensätze

Ein weitergeleiteter Anruf erzeugt zwei Leg-Datensätze mit gemeinsamer call_id:

Verwenden Sie den call_id-Filter in der Leg-Liste, um die zugehörigen Verbindungen zu finden, oder öffnen Sie Voice > Calls. Der eingehende Datensatz ist derjenige, der angibt, was die Nummer tun sollte.

Auswählen, welche Nummer ein weitergeleiteter Anruf als Anrufer anzeigt

Ein weitergeleiteter Anruf hat zwei Nummern, die er der antwortenden Person präsentieren kann, und die Wahl beeinflusst sowohl, was diese sieht, als auch, wie wahrscheinlich ein Carrier in den Anruf eingreift:

• Calling number ist die eigene Nummer des Anrufers, sodass das Telefon klingelt, als hätte er direkt gewählt, und der Anruf aus dem Anrufprotokoll zurückgerufen werden kann. Da die Nummer nicht Ihnen gehört, kennzeichnen manche Carrier, am häufigsten in den USA und Teilen Europas, solche Anrufe als nicht verifiziert, ersetzen die Nummer oder filtern sie.
• Dialed number ist die Nummer, die der Anrufer gewählt hat, also eine Ihrer Nummern. Die antwortende Person sieht, welche Ihrer Nummern angerufen wurde, nicht aber, wer angerufen hat.

Geben Sie die Wahl bei jeder Weiterleitung an, die Sie über die API oder CLI festlegen. Eine ältere Konfiguration ohne gespeicherte Wahl gibt die gewählte Nummer zurück.

Das Feld inbound_configuration.forward_as_options der Nummer listet die dem Editor verfügbaren Optionen auf. Die aktuellen Optionen umfassen die anrufende Nummer und die gewählte Nummer. Lesen Sie diese Optionen beim Erstellen einer Integration aus und verwenden Sie den zurückgegebenen Wert forward_as, um die wirksame Einstellung zu bestätigen.

Bei einem Lesevorgang ist forward_as der Wert, den die Anrufe tatsächlich übermitteln, der vom zuletzt geschriebenen Wert abweichen kann.

Lesen, was eine Nummer mit einem Anruf getan hat

Der Datensatz eines eingehenden Anrufs enthält neben seinem Status eine route, und route gibt an, was die Nummer zum Zeitpunkt der Anrufbehandlung tun sollte. Eine spätere Änderung der Nummereinstellung ändert nicht, was ihre vergangenen Anrufe aussagen.

route gibt an, was die Nummer tun sollte, nicht ob es funktioniert hat. Eine trunk-Route bei einem nie verbundenen Anruf bedeutet, dass die Nummer auf einen Trunk verweist, der den Anruf nicht angenommen hat, und der Status des Anrufs gibt das Ergebnis wieder. route fehlt bei ausgehenden Anrufen und bei Anrufen, die vor der Einführung des Feldes aufgezeichnet wurden.

Öffnen Sie im Dashboard den Anruf über Voice > Legs und lesen Sie die Zeile Inbound route, die auf die Nummer verlinkt, deren Einstellungen darüber entschieden haben. Über die API finden Sie route auf GET /v1/voice/legs/{leg_id} und GET /v1/voice/legs, und direction filtert die Liste auf eingehende Anrufe.

Prüfen Sie bei einer Sequenzroute auch die Seite Runs der Sequenz, um den ausgeführten Einstieg und die Version zu ermitteln. Die aktuelle Konfiguration der Nummer kann von der für einen früheren Anruf gespeicherten Version abweichen.

Einen abgelehnten eingehenden Anruf diagnostizieren

Ein abgelehnter eingehender Anruf wird mit dem Status rejected aufgezeichnet. Zwei verschiedene Ursachen erzeugen ihn, und rejection_reason unterscheidet sie:

• Abgelehnt ohne rejection_reason. Die Nummer selbst hat den Anruf abgewiesen. Der Anruf ist an keiner unserer Prüfungen gescheitert und nennt daher keinen Grund. route gibt an, was die Nummer tun sollte. Eine reject-Route gehört zu einer Nummer, die auf Ablehnung gesetzt ist, oder zu einer ohne eigene Route, während die Workspace-Standardroute auf „Ablehnen" steht.
• Abgelehnt mit einem rejection_reason. Der Anruf hat eine unserer Prüfungen nicht bestanden, bevor er Ihre Telefonanlage erreicht hat. Der Grund nennt die Prüfung. Abgelehnte Anrufe listet jeden Grund und seine Behebung auf.

failed ist ein anderer Status und bedeutet nicht abgelehnt: Er bedeutet, dass der Anruf versucht wurde und nicht funktioniert hat, wobei sip_response_code die zurückgegebene Antwort enthält.

Lesen Sie route und rejection_reason zusammen, um die Ablehnungen zu unterscheiden:

Die Kontolimits gelten auch für eingehende Anrufe: Wenn Ihr Wallet-Guthaben, das tägliche Voice-Ausgabenlimit Ihrer Organisation oder Ihre Gleichzeitigkeits- und Pro-Sekunde-Limits überschritten sind, wird ein eingehender Anruf mit dem entsprechenden Grund abgelehnt. Voice-Übersicht behandelt die Limits selbst.

Kosten eines empfangenen Anrufs prüfen

Der Empfang eines Anrufs ist kostenpflichtig. Der Tarif hängt vom Land und Typ der empfangenden Nummer ab und wird pro Land unter Receiving calls auf der Voice-Preisseite veröffentlicht, zusammen mit den Tarifen für von Ihnen getätigte Anrufe.

Eine Weiterleitung wird als zwei Anrufe abgerechnet: der eingehende Anruf zum Empfangstarif und das von uns aufgebaute Leg zum ausgehenden Tarif für die Nummer, an die Sie weiterleiten. Eine einzelne Bearbeitungsgebühr wird einmal pro Anruf berechnet, nicht einmal pro Leg.

Das Wallet wird vor Zustellung eines eingehenden Anrufs geprüft, sodass ein Guthaben, das ihn nicht deckt, zur Ablehnung des Anrufs führt, anstatt ihn Ihnen nachträglich in Rechnung zu stellen. Kosten und Abrechnung erklärt, wie abrechenbare Zeit, Tarife und das Wallet in beiden Richtungen funktionieren.

Nächste Schritte