Odbieranie połączeń

Numer posiadany przez Twój obszar roboczy może dostarczyć połączenie przychodzące do trunka SIP, przekierować je na zweryfikowany numer, uruchomić opublikowaną sekwencję lub je odrzucić. Numer ma jedną trasę naraz: własną albo domyślną trasę obszaru roboczego, gdy nie ma własnej.

Domyślna trasa obszaru roboczego zaczyna jako odrzucanie, więc numer, którego nikt nie skonfigurował, odprawia dzwoniących zamiast nie mieć żadnej odpowiedzi. Zmień wartość domyślną, aby nadać każdemu takiemu numerowi tę samą odpowiedź. Zobacz Ustawianie domyślnej trasy.

Aby obsługiwać połączenia przychodzące w natywnym przepływie Bird, opublikuj sekwencję i powiąż numer z jej wejściem połączenia. Wybrane wejście musi akceptować puste dane.

Wymagania wstępne

Zanim skierujesz numer na sposób obsługi:

• Numer, który może odbierać połączenia. Otwórz Voice > Numbers i sprawdź w kolumnie Directions, czy jest oznaczenie przychodzące. Numer zarejestrowany jako identyfikator dzwoniącego od innego operatora nie odbiera tu połączeń: ten operator kieruje połączenia na niego, więc nie ma on ustawienia obsługi.
• Do dostarczania na trunk: trunk SIP z włączonym odbieraniem połączeń i co najmniej jedną bramką dostarczania.
• Do przekierowania: zweryfikowany identyfikator dzwoniącego, na który chcesz przekierować.
• Do sekwencji: aktywna, opublikowana sekwencja w tym samym obszarze roboczym, z wejściem połączeniowym akceptującym puste dane wejściowe. W sekcji Inbound routing wybierz Run a sequence, wskaż sekwencję i wejście połączeniowe, a następnie zapisz. Przewodnik po kreatorze sekwencji opisuje publikację i testerów wersji roboczej dla połączeń przychodzących.
• Aby zmienić ustawienie przez API lub CLI: klucz API z uprawnieniem voice_management na poziomie zapisu. To uprawnienie obejmuje konfigurację głosową; uprawnienie voice obejmuje ruch połączeń i statystyki, więc odczyt dziennika połączeń wymaga tego drugiego.

Dostarczanie połączeń do trunku SIP

Dostarczanie wybiera Twój własny system telefoniczny pod adresami zadeklarowanymi na trunku. Najpierw włącz kierunek przychodzący, bo numer można skierować tylko na trunk, który już przyjmuje połączenia przychodzące.

1. Otwórz Voice > SIP Trunks, otwórz trunk i w sekcji Inbound calling wybierz Enable inbound.
2. Dodaj co najmniej jedną bramkę w tej samej sekcji. Trunk bez bramki odrzuca każde połączenie przychodzące na numery, które obsługuje.
3. Otwórz Voice > Numbers, otwórz numer i w sekcji Inbound routing wybierz Deliver to a SIP trunk.
4. Wybierz trunk i kliknij Save. Na liście pojawiają się tylko trunki z włączonym odbieraniem połączeń.

Kolumna Used for na liście Numbers pokazuje wtedy numer jako dostarczany do tego trunku, a strona trunku wyświetla numery, które obsługuje.

Przez API zaktualizuj trunk ustawieniem inbound_enabled: true, dodaj bramkę, a następnie skieruj rekord głosowy numeru na trunk. Rekord głosowy ma identyfikator zaczynający się od vnu_, który różni się od identyfikatora nda_ zwracanego przez /v1/numbers dla tego samego numeru. Przekazanie identyfikatora nda_ do operacji na numerze głosowym jest odrzucane z kodem 422. Aby znaleźć rekord głosowy, wyszukaj swoje numery głosowe po cyfrach numeru:

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"

Każdy wynik zawiera swoje id, swoje phone_number i bieżącą inbound_configuration.route. Wyślij trasę trunkową do aktualizacji numeru głosowego z tym 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"
      }
    }
  }'

Trunk z wyłączonym odbieraniem połączeń jest odrzucany z kodem 412 i komunikatem E21052. Trasa zastępuje to, co numer miał wcześniej. Wysłanie {"type": "reject"} jako trasy odrzuca dzwoniących niezależnie od ustawienia domyślnego, a wysłanie null przywraca numer do domyślnej trasy obszaru roboczego.

Czego wymaga bramka

Bramka to jeden adres, na który dostarczane jest połączenie, oraz sposób, w jaki ten peer oczekuje zapisu dwóch numerów połączenia:

Bramki o tym samym priorytecie dzielą połączenia równomiernie i przy danym połączeniu dowolna z nich może być wypróbowana jako pierwsza. Aby przełączyć dostarczanie na drugi adres, nadaj tej bramce wyższy numer priorytetu: zostanie wypróbowana, gdy pierwsza nie odpowie.

Oba formaty numerów to szablony z jednym symbolem zastępczym {number}, który oznacza numer bez wiodącego +. Format docelowy jest umieszczany przed hostem URI SIP, więc 1234#{number} dostarcza połączenie do +31201234567 jako sip:1234#31201234567@pbx.example.com:5060. Domyślna wartość obu to +{number}, czyli E.164. Format niezawierający żadnego {number} wysyła każdy numer obsługiwany przez trunk na jeden stały adres. Peer oczekujący numerów bez + przyjmuje sam {number} jako format.

Przez API dodaj bramkę do trunku z tymi ustawieniami. Najpierw włącz odbieranie połączeń na trunku: utworzenie bramki na trunku bez niego jest odrzucane z 412 i 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}"
  }'

Zaktualizuj bramkę, aby później zmienić jej priorytet lub formaty.

Uwaga: wyłączenie połączeń przychodzących na trunku lub usunięcie trunka powoduje, że każdy numer wskazujący na niego wraca do domyślnej trasy obszaru roboczego. Domyślna trasa obszaru roboczego, która wskazywała na ten trunk, wraca do odrzucania. Ponowne włączenie połączeń przychodzących nie przywraca żadnego z tych ustawień, więc każdy numer trzeba ponownie skierować na trunk.

Ustawianie trasy domyślnej

Domyślna trasa obszaru roboczego obsługuje połączenia dla każdego numeru bez własnej trasy. Zaczyna jako odrzucanie. Numer z własną trasą zachowuje ją po zmianie trasy domyślnej.

1. Otwórz Voice > Numbers.
2. Obok Calls to numbers without their own route kliknij Change, wybierz sposób obsługi i zapisz.

Zmiana obowiązuje od następnego połączenia, które każdy z tych numerów odbierze. Przez API zaktualizuj ustawienia głosowe:

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

Domyślna trasa jest sprawdzana tak samo jak trasa numeru. Aby przywrócić numer do trasy domyślnej, ustaw jego trasę na null lub wybierz Use the workspace default na numerze.

Przekierowanie połączeń na inny numer

Przekierowanie odbiera połączenie przychodzące i wykonuje drugie połączenie na zweryfikowany numer, a następnie łączy oba.

1. Otwórz Voice > Numbers, otwórz numer i w sekcji Inbound routing wybierz Forward to another number.
2. Wybierz numer docelowy przekierowania. Na liście znajdują się Twoje zweryfikowane identyfikatory dzwoniącego, ponieważ przekierowanie może wskazywać tylko numer, którego kontrolę udowodniłeś.
3. Wybierz, który numer przekierowane połączenie ma pokazywać jako dzwoniącego, a następnie kliknij Save.

Przez API wyszukaj swoje numery głosowe po cyfrach numeru, aby odczytać jego identyfikator vnu_, a następnie wyślij trasę forward z forward_to i 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 musi być identyfikatorem dzwoniącego z ukończoną weryfikacją. Numer, którego nie zarejestrowałeś, lub taki, którego weryfikacja ma status pending lub failed, jest odrzucany z kodem 412 i komunikatem E21053. Identyfikatory dzwoniącego opisują rejestrację i weryfikację przez API.

Cel przekierowania jest sprawdzany w momencie ustawienia i ponownie przy każdym przekierowywanym połączeniu. Identyfikator dzwoniącego, który później usuniesz, zatrzymuje przekierowywanie zamiast kontynuować, a połączenia przychodzące są od tego momentu odrzucane.

Przekierowane połączenie dzwoni przez 45 sekund, zanim zostanie porzucone. To dłużej niż przy dostarczaniu na trunk, ponieważ po drugiej stronie jest zwykle telefon osoby, a nie system telefoniczny.

Przekierowanie wykonuje połączenie, więc do drugiego etapu mają zastosowanie reguły wychodzące: przekierowanie do kraju, którego nie włączyłeś w sekcji Destinations, jest odrzucane z kodem destination_not_enabled.

Jedno przekierowanie, dwa rekordy połączeń

Przekierowane połączenie tworzy dwa rekordy etapów z tym samym call_id:

Użyj filtra call_id na liście etapów, aby znaleźć powiązane połączenia, lub otwórz Voice > Calls. Rekord połączenia przychodzącego zawiera informację o tym, jak numer był skonfigurowany.

Wybór numeru prezentowanego przez przekierowane połączenie

Przekierowane połączenie może prezentować odbierającemu jeden z dwóch numerów, a wybór wpływa zarówno na to, co zobaczy, jak i na prawdopodobieństwo ingerencji operatora w połączenie:

• Numer dzwoniącego to własny numer dzwoniącego, więc telefon dzwoni tak, jakby osoba wybrała numer bezpośrednio, a połączenie można oddzwonić z dziennika. Ponieważ numer nie należy do Ciebie, niektórzy operatorzy, najczęściej w USA i częściach Europy, oznaczają takie połączenia jako niezweryfikowane, podmieniają numer lub je filtrują.
• Numer wybrany to numer, który wybrał dzwoniący, czyli jeden z Twoich. Odbierający widzi, na który z Twoich numerów zadzwoniono, a nie kto dzwoni.

Określ wybór przy każdym przekierowaniu ustawianym przez API lub CLI. Starsza konfiguracja bez zapisanego wyboru zwraca numer wybrany.

Pole inbound_configuration.forward_as_options numeru zawiera listę opcji dostępnych dla edytora. Bieżące opcje obejmują numer dzwoniącego i numer wybrany. Odczytaj te opcje podczas tworzenia integracji i użyj zwróconego forward_as, aby potwierdzić obowiązujące ustawienie.

Przy odczycie forward_as to wartość faktycznie przenoszona przez połączenia, która może różnić się od ostatnio zapisanej.

Sprawdź, co numer zrobił z połączeniem

Rekord połączenia przychodzącego zawiera route obok statusu, a route to sposób obsługi ustawiony na numerze w momencie obsłużenia połączenia. Zmiana ustawienia numeru po fakcie nie zmienia informacji w rekordach wcześniejszych połączeń.

route mówi, jak numer był ustawiony, a nie czy to zadziałało. Trasa trunk przy połączeniu, które nigdy nie zostało zestawione, oznacza numer skierowany na trunk, który nie przyjął połączenia, a status połączenia niesie informację o wyniku. route jest nieobecne przy połączeniach wychodzących i przy połączeniach zarejestrowanych przed wprowadzeniem tego pola.

W panelu otwórz połączenie z poziomu Voice > Legs i sprawdź wiersz Inbound route, który prowadzi do numeru, którego ustawienia o nim zdecydowały. Przez API pole route znajduje się na GET /v1/voice/legs/{leg_id} i GET /v1/voice/legs, a direction filtruje listę do połączeń przychodzących.

W przypadku trasy sekwencji sprawdź też stronę Runs sekwencji, aby ustalić użyty punkt wejścia i wykonaną wersję. Bieżąca konfiguracja numeru może różnić się od wersji zachowanej dla wcześniejszego połączenia.

Diagnozowanie odrzuconego połączenia przychodzącego

Odrzucone połączenie przychodzące jest zapisywane ze statusem rejected. Dwie różne przyczyny go generują, a rejection_reason je rozróżnia:

• Odrzucone bez rejection_reason. Sam numer odrzucił połączenie. Połączenie nie naruszyło żadnej naszej reguły, więc nie podaje powodu, a route wskazuje, jak numer był ustawiony. Trasa reject to numer ustawiony na odrzucanie lub numer bez własnej trasy, gdy domyślna trasa obszaru roboczego jest ustawiona na odrzucanie.
• Odrzucone z rejection_reason. Połączenie nie przeszło jednej z naszych kontroli przed dotarciem do Twojego systemu telefonicznego. Powód wskazuje kontrolę. Odrzucone połączenia zawierają listę wszystkich powodów i sposobów naprawy.

failed to inny status i nie oznacza odrzucenia: oznacza, że podjęto próbę połączenia i nie powiodła się, a sip_response_code zawiera odpowiedź, która wróciła.

Odczytaj route i rejection_reason razem, aby rozróżnić odrzucenia:

Limity konta dotyczą też połączeń przychodzących: po przekroczeniu salda portfela, dziennego limitu wydatków na głos w organizacji lub limitów współbieżności i liczby połączeń na sekundę połączenie przychodzące jest odrzucane z odpowiednim powodem. Przegląd Voice opisuje same limity.

Sprawdź koszt odebranego połączenia

Odbieranie połączeń jest płatne. Stawka zależy od kraju i typu numeru odbierającego i jest publikowana dla każdego kraju w sekcji Receiving calls na stronie cennika głosowego obok stawek za połączenia wychodzące.

Przekierowanie jest rozliczane jako dwa połączenia: przychodzące po stawce za odbiór i etap, który wykonujemy, po stawce wychodzącej dla numeru docelowego przekierowania. Pojedyncza opłata manipulacyjna jest naliczana raz za połączenie, a nie raz za etap.

Portfel jest sprawdzany przed dostarczeniem połączenia przychodzącego, więc saldo niewystarczające do jego pokrycia oznacza odrzucenie połączenia zamiast obciążenia Cię po fakcie. Koszty i rozliczenia opisują, jak działają czas podlegający opłacie, stawki i portfel w obu kierunkach.

Następne kroki