Oproepen ontvangen

Een nummer in je werkruimte kan een inkomende oproep afleveren bij een SIP-trunk, doorsturen naar een geverifieerd nummer, een gepubliceerde sequence uitvoeren of de oproep weigeren. Een nummer heeft één route tegelijk: zijn eigen route, of de standaardroute van je werkruimte als het er geen heeft.

De standaardroute van de werkruimte begint op weigeren, dus een nummer dat niemand heeft geconfigureerd wijst bellers af in plaats van helemaal geen antwoord te hebben. Wijzig de standaardroute om elk zo'n nummer hetzelfde antwoord te geven. Zie Een standaardroute instellen.

Publiceer een sequence en koppel het nummer aan het oproepstartpunt ervan om inkomende oproepen in een native Bird-flow te verwerken. Het gekozen startpunt moet lege gegevens accepteren.

Vereisten

Voordat je een nummer aan een antwoord koppelt:

• Een nummer dat oproepen kan ontvangen. Open Voice > Numbers en controleer de kolom Directions op een inbound-markering. Een nummer dat je als beller-ID van een andere provider hebt geregistreerd, ontvangt hier geen oproepen: die provider routeert de oproepen ernaartoe, dus het heeft geen antwoord.
• Voor aflevering bij een trunk: een SIP-trunk met inkomend bellen aan en minstens één aflevergateway.
• Voor doorsturen: een geverifieerd beller-ID om naar door te sturen.
• Voor een sequence: een actieve, gepubliceerde sequence in dezelfde werkruimte, met een oproepstartpunt dat lege startgegevens accepteert. Selecteer onder Inbound routing de optie Run a sequence, kies de sequence en het oproepstartpunt en sla op. De gids voor de sequence-bouwer legt publicatie en inkomende concepttesters uit.
• Om de instelling via de API of CLI te wijzigen: een API-sleutel met het voice_management-bereik op schrijfniveau. Dat bereik dekt spraakconfiguratie; het voice-bereik dekt oproepverkeer en statistieken, dus het oproeplogboek lezen vereist het andere bereik.

Oproepen afleveren bij een SIP-trunk

Aflevering belt je eigen telefoonsysteem op adressen die je op de trunk declareert. Zet de richting eerst aan, want een nummer kan alleen worden gekoppeld aan een trunk die al inkomende oproepen accepteert.

1. Open Voice > SIP Trunks, open de trunk en selecteer onder Inbound calling de optie Enable inbound.
2. Voeg minstens één gateway toe in dezelfde sectie. Een trunk zonder gateway weigert elke inkomende oproep naar de nummers die hij beantwoordt.
3. Open Voice > Numbers, open het nummer en kies onder Inbound routing de optie Deliver to a SIP trunk.
4. Kies de trunk en selecteer Save. Alleen trunks met inkomend bellen aan verschijnen in de lijst.

De kolom Used for in de Numbers-lijst toont het nummer vervolgens als afgeleverd bij die trunk, en de eigen pagina van de trunk vermeldt de nummers die hij beantwoordt.

Via de API werk je de trunk bij met inbound_enabled: true, voeg je een gateway toe en koppel je het voice-record van het nummer aan de trunk. Het voice-record heeft een ID dat begint met vnu_, wat verschilt van het nda_-ID dat /v1/numbers retourneert voor hetzelfde nummer. Het nda_-ID doorgeven aan een voice-nummerbewerking wordt geweigerd met 422. Om het voice-record te vinden zoek je in je voice-nummers op de cijfers van het 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"

Elk resultaat bevat zijn id, zijn phone_number en de huidige inbound_configuration.route. Stuur de trunkroute naar het voice-nummer bijwerken met dat 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"
      }
    }
  }'

Een trunk waarvan het inkomend bellen uit staat, wordt geweigerd met 412 en E21052. De route vervangt wat het nummer eerder had. {"type": "reject"} als route versturen wijst bellers af ongeacht de standaardroute, en null versturen zet het nummer terug op de standaardroute van de werkruimte.

Wat een gateway nodig heeft

Een gateway is één adres waarnaar een oproep wordt afgeleverd, en hoe die peer de twee nummers van de oproep weergegeven wil hebben:

Gateways met dezelfde prioriteit krijgen een gelijk aandeel van de oproepen, en elk van hen kan als eerste worden geprobeerd bij een bepaalde oproep. Om de aflevering over te laten vallen naar een tweede adres geef je die gateway een hoger prioriteitsnummer: hij wordt geprobeerd wanneer de eerste niet antwoordt.

Beide nummerformaten zijn templates met één placeholder, {number}, die staat voor het nummer zonder de voorlooptekens +. Het bestemmingsformaat wordt voor de SIP URI-host geplaatst, dus 1234#{number} levert een oproep naar +31201234567 af als sip:1234#31201234567@pbx.example.com:5060. De standaardwaarde voor beide is +{number}, wat E.164 is. Een formaat dat helemaal geen {number} bevat, stuurt elk nummer dat de trunk beantwoordt naar één vast adres. Een peer die nummers zonder de + verwacht, neemt {number} op zichzelf als formaat.

Voeg via de API een gateway toe aan de trunk met deze instellingen. Zet eerst het inkomend bellen van de trunk aan: een gateway aanmaken op een trunk zonder inkomend bellen wordt geweigerd met 412 en 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}"
  }'

Werk een gateway bij om de prioriteit of formaten later te wijzigen.

Waarschuwing: als je inkomend bellen op een trunk uitzet of de trunk verwijdert, vallen alle nummers die ernaar verwijzen terug op de standaardroute van de werkruimte. Een standaardroute van de werkruimte die naar die trunk verwijst, wordt weer reject. Opnieuw inschakelen herstelt geen van beide, dus elk nummer moet opnieuw naar een trunk worden verwezen.

Een standaardroute instellen

De standaardroute van de werkruimte beantwoordt oproepen voor elk nummer zonder eigen route. Hij begint als weigeren. Een nummer met een eigen route behoudt die wanneer de standaardroute verandert.

1. Open Voice > Numbers.
2. Selecteer naast Calls to numbers without their own route de optie Change, kies het antwoord en sla op.

De wijziging geldt vanaf de volgende oproep die elk van die nummers ontvangt. Via de API kun je de spraakinstellingen bijwerken:

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

De standaardroute wordt op dezelfde manier gecontroleerd als de route van een nummer. Om een nummer terug te zetten naar de standaardroute stel je de route in op null, of kies je Use the workspace default op het nummer.

Oproepen doorsturen naar een ander nummer

Een doorschakeling beantwoordt de inkomende oproep en plaatst een tweede oproep naar een nummer dat je hebt geverifieerd, en verbindt de twee vervolgens.

1. Open Voice > Numbers, open het nummer en kies onder Inbound routing de optie Forward to another number.
2. Kies het nummer om naar door te sturen. De lijst bevat je geverifieerde beller-ID's, omdat een doorschakeling alleen een nummer mag targeten waarvan je hebt bewezen dat je het beheert.
3. Kies welk nummer de doorgestuurde oproep als beller toont en selecteer vervolgens Save.

Zoek via de API met zoek je voice-nummers op de cijfers van het nummer om het vnu_-ID te lezen, en stuur vervolgens een forward-route met forward_to en 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 moet een beller-ID zijn waarvan de verificatie is voltooid. Een nummer dat je niet hebt geregistreerd, of een nummer waarvan de verificatie pending of failed is, wordt geweigerd met 412 en E21053. Beller-ID's behandelt het registreren en verifiëren van een nummer via de API.

Het doorschakeldoel wordt gecontroleerd wanneer je het instelt en opnieuw bij elke oproep die wordt doorgestuurd. Een beller-ID dat je later verwijdert stopt het doorsturen in plaats van door te gaan, en de inkomende oproepen worden vanaf dat moment geweigerd.

De doorgestuurde oproep gaat 45 seconden over voordat hij wordt opgegeven, wat langer is dan bij een trunk-aflevering omdat het andere uiteinde meestal de telefoon van een persoon is in plaats van een telefoonsysteem.

Doorsturen plaatst een oproep, dus de uitgaande regels gelden voor het tweede been: doorsturen naar een land dat je niet hebt ingeschakeld onder Destinations wordt geweigerd met destination_not_enabled.

Eén doorschakeling, twee oproeprecords

Een doorgestuurde oproep produceert twee leg-records die een call_id delen:

Gebruik het call_id-filter op de lijst met legs om de gerelateerde verbindingen te vinden, of open Voice > Calls. Het binnenkomende record is het record dat aangeeft wat de instelling van het nummer was.

Kiezen welk nummer een doorgestuurde oproep als beller toont

Een doorgestuurde oproep heeft twee nummers die hij kan presenteren aan degene die opneemt, en de keuze bepaalt zowel wat diegene ziet als hoe waarschijnlijk het is dat een provider de oproep beïnvloedt:

• Bellend nummer is het eigen nummer van de beller, zodat de telefoon overgaat alsof diegene rechtstreeks heeft gebeld en de oproep kan worden teruggebeld vanuit het oproeplogboek. Omdat het nummer niet van jou is, markeren sommige providers, vooral in de VS en delen van Europa, zulke oproepen als niet-geverifieerd, vervangen ze het nummer of screenen ze de oproep.
• Gebeld nummer is het nummer dat de beller heeft gebeld, en dat is een van jouw nummers. Degene die opneemt ziet welk van jouw nummers is gebeld in plaats van wie er belde.

Geef de keuze op bij elke doorschakeling die je schrijft via de API of CLI. Een oudere configuratie zonder opgeslagen keuze geeft het gebelde nummer terug.

De inbound_configuration.forward_as_options van het nummer vermeldt de keuzes die beschikbaar zijn voor de bewerker. De huidige opties omvatten het bellende nummer en het gebelde nummer. Lees die opties bij het bouwen van een integratie en gebruik de geretourneerde forward_as om de effectieve instelling te bevestigen.

Bij het uitlezen is forward_as de waarde die de oproepen daadwerkelijk meesturen, wat kan afwijken van de laatst geschreven waarde.

Bekijken wat een nummer met een oproep heeft gedaan

Het record van een inkomende oproep bevat een route naast de status, en route is wat het nummer was ingesteld te doen op het moment dat de oproep werd afgehandeld. De instelling van het nummer achteraf wijzigen verandert niet wat de eerdere oproepen vermelden.

route geeft aan wat het nummer was ingesteld te doen, niet dat het gelukt is. Een trunk-route op een oproep die nooit verbinding maakte, is een nummer dat naar een trunk wees die de oproep niet aannam, en de status van de oproep draagt het resultaat. route ontbreekt bij uitgaande oproepen en bij oproepen die zijn vastgelegd voordat het veld bestond.

Open in het dashboard het gesprek via Voice > Legs en lees de rij Inbound route, die linkt naar het nummer waarvan de instellingen het bepaalden. Via de API staat route op GET /v1/voice/legs/{leg_id} en GET /v1/voice/legs, en direction filtert de lijst op inkomende oproepen.

Bekijk bij een sequentieroute ook de pagina Runs van de sequentie om te achterhalen welk startpunt en welke versie zijn uitgevoerd. De huidige configuratie van het nummer kan afwijken van de versie die voor een eerder gesprek is bewaard.

Een geweigerde inkomende oproep diagnosticeren

Een inkomende oproep die is geweigerd, wordt vastgelegd met de status rejected. Twee verschillende dingen veroorzaken dit, en rejection_reason is wat ze onderscheidt:

• Geweigerd zonder rejection_reason. Het nummer zelf heeft de oproep afgewezen. De oproep faalde op geen enkele controle van ons, dus er wordt geen reden vermeld, en route geeft aan wat het nummer was ingesteld te doen. Een reject-route is een nummer dat op weigeren staat, of een nummer zonder eigen route terwijl de standaardroute van de werkruimte op weigeren staat.
• Geweigerd met een rejection_reason. De oproep faalde op een van onze controles voordat hij je telefoonsysteem bereikte. De reden noemt de controle. Geweigerde oproepen vermeldt elke reden en de bijbehorende oplossing.

failed is een andere status en betekent niet geweigerd: het betekent dat de oproep is geprobeerd en niet is gelukt, waarbij sip_response_code het teruggekomen antwoord draagt.

Lees route en rejection_reason samen om de weigeringen te onderscheiden:

De accountlimieten gelden ook voor inkomende oproepen: bij onvoldoende walletsaldo of overschrijding van de dagelijkse bestedingslimiet voor Voice van je organisatie, de limiet voor gelijktijdige gesprekken of de limiet per seconde wordt een inkomende oproep met de bijbehorende reden geweigerd. Het Voice-overzicht beschrijft de limieten zelf.

Controleren wat een ontvangen oproep kost

Het ontvangen van een oproep wordt in rekening gebracht. Het tarief hangt af van het land en het type van het ontvangende nummer en wordt per land gepubliceerd onder Receiving calls op de spraakprijzenpagina, naast de tarieven voor oproepen die je plaatst.

Een doorschakeling wordt gefactureerd als twee gesprekken: het binnenkomende gesprek tegen het ontvangsttarief en de leg die wij plaatsen tegen het uitgaande tarief voor het nummer waarnaar je doorstuurt. Er wordt één afhandelingsvergoeding in rekening gebracht per gesprek, niet per leg.

De wallet wordt gecontroleerd voordat een inkomende oproep wordt afgeleverd, dus een saldo dat de oproep niet kan dekken betekent dat de oproep wordt geweigerd in plaats van achteraf aan je gefactureerd. Kosten en facturering behandelt hoe factureerbare tijd, tarieven en de wallet werken voor beide richtingen.

Volgende stappen