Recibir llamadas

Un número que posee tu espacio de trabajo puede entregar una llamada entrante a un trunk SIP, reenviarla a un número verificado, ejecutar una secuencia publicada o rechazarla. Cada número tiene una ruta a la vez: la suya propia, o la ruta por defecto del espacio de trabajo cuando no tiene ninguna.

La ruta por defecto del espacio de trabajo comienza como rechazar, así que un número que nadie ha configurado rechaza a quienes llaman en lugar de quedarse sin respuesta. Cambia el valor por defecto para dar a todos esos números la misma respuesta. Consulta Establecer una ruta por defecto.

Para gestionar llamadas entrantes con un flujo nativo de Bird, publica una secuencia y vincula el número a su entrada de llamada. La entrada seleccionada debe aceptar datos vacíos.

Requisitos previos

Antes de apuntar un número a una respuesta:

• Un número que pueda recibir llamadas. Abre Voice > Numbers y comprueba en la columna Directions que tenga una marca de entrada. Un número que registraste como caller ID de otro operador no recibe llamadas aquí: ese operador enruta las llamadas dirigidas a él, así que no tiene respuesta.
• Para entregar a un trunk: un trunk SIP con llamadas entrantes activadas y al menos un gateway de entrega.
• Para un reenvío: un caller ID verificado al que reenviar.
• Para una secuencia: una secuencia activa y publicada en el mismo espacio de trabajo, con una entrada de llamada que acepte datos de entrada vacíos. En Inbound routing, selecciona Run a sequence, elige la secuencia y la entrada de llamada, y guarda. La guía del constructor de secuencias explica la publicación y los testers de borradores entrantes.
• Para cambiar el ajuste a través de la API o CLI: una clave API con el alcance voice_management en nivel de escritura. Ese alcance cubre la configuración de voz; el alcance voice cubre el tráfico de llamadas y las estadísticas, así que leer el registro de llamadas requiere el otro.

Entregar llamadas a un trunk SIP

La entrega llama a tu propio sistema telefónico en las direcciones que declaras en el trunk. Activa la dirección primero, porque un número solo se puede apuntar a un trunk que ya acepte llamadas entrantes.

1. Abre Voice > SIP Trunks, abre el trunk y en Inbound calling selecciona Enable inbound.
2. Añade al menos un gateway en la misma sección. Un trunk sin gateway rechaza todas las llamadas entrantes a los números que responde.
3. Abre Voice > Numbers, abre el número y en Inbound routing elige Deliver to a SIP trunk.
4. Elige el trunk y selecciona Save. Solo aparecen en la lista los trunks con llamadas entrantes activadas.

La columna Used for en la lista de Numbers muestra entonces el número como entregado a ese trunk, y la página del trunk lista los números que responde.

A través de la API, actualiza el trunk con inbound_enabled: true, añade un gateway y apunta el registro de voz del número al trunk. El registro de voz tiene un ID que empieza por vnu_, distinto del ID nda_ que /v1/numbers devuelve para el mismo número. Pasar el ID nda_ a una operación de número de voz se rechaza con 422. Para encontrar el registro de voz, busca en tus números de voz las cifras del número:

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"

Cada resultado incluye su id, su phone_number y la inbound_configuration.route actual. Envía la ruta de trunk a actualizar el número de voz con ese 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 las llamadas entrantes desactivadas se rechaza con 412 y E21052. La ruta reemplaza cualquier configuración anterior del número. Enviar {"type": "reject"} como ruta rechaza a los que llaman sin importar el valor por defecto, y enviar null devuelve el número a la ruta por defecto del espacio de trabajo.

Qué necesita un gateway

Un gateway es una dirección a la que se entrega una llamada, y cómo ese par quiere que se escriban los dos números de la llamada:

Los gateways que comparten prioridad reciben una parte igual de las llamadas, y cualquiera de ellos puede ser el primero en una llamada dada. Para pasar la entrega a una segunda dirección, asigna a ese gateway un número de prioridad mayor: se prueba cuando el primero no responde.

Ambos formatos de número son plantillas sobre un marcador de posición, {number}, que representa el número sin su + inicial. El formato de destino se coloca antes del host del URI SIP, así que 1234#{number} entrega una llamada a +31201234567 como sip:1234#31201234567@pbx.example.com:5060. El valor por defecto de ambos es +{number}, que es E.164. Un formato que no contenga ningún {number} envía todos los números que el trunk responde a una única dirección fija. Un par que espere números sin el + acepta {number} solo como formato.

A través de la API, añade un gateway al trunk con estos ajustes. Activa primero las llamadas entrantes del trunk: crear un gateway en un trunk sin ellas se rechaza con 412 y 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}"
  }'

Actualiza un gateway para cambiar su prioridad o formatos más adelante.

Advertencia: desactivar las llamadas entrantes en un trunk, o eliminar el trunk, devuelve todos los números que apuntaban a él a la ruta predeterminada del espacio de trabajo. Una ruta predeterminada del espacio de trabajo que nombre ese trunk vuelve a rechazar. Reactivar las llamadas entrantes no restaura ninguna de las dos cosas, así que cada número tiene que apuntarse a un trunk de nuevo.

Establecer una ruta por defecto

La ruta por defecto del espacio de trabajo responde las llamadas de todos los números sin ruta propia. Comienza como rechazar. Un número con ruta propia la conserva cuando cambia la ruta por defecto.

1. Abre Voice > Numbers.
2. Junto a Calls to numbers without their own route, selecciona Change, elige la respuesta y guarda.

El cambio se aplica a partir de la siguiente llamada que reciba cada uno de esos números. A través de la API, actualiza los ajustes de voz:

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 ruta por defecto se comprueba del mismo modo que la ruta de un número. Para devolver un número a la ruta por defecto, establece su ruta a null, o elige Use the workspace default en el número.

Reenviar llamadas a otro número

Un reenvío responde la llamada entrante y realiza una segunda llamada a un número que hayas verificado, y luego conecta las dos.

1. Abre Voice > Numbers, abre el número y en Inbound routing elige Forward to another number.
2. Elige el número al que reenviar. La lista contiene tus caller IDs verificados, porque un reenvío solo puede apuntar a un número que hayas demostrado que controlas.
3. Elige qué número muestra la llamada reenviada como el que llama y selecciona Save.

A través de la API, busca tus números de voz por los dígitos del número para obtener su ID vnu_, y luego envía una ruta forward con forward_to y 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 debe ser un caller ID cuya verificación esté completa. Un número que no hayas registrado, o uno cuya verificación sea pending o failed, se rechaza con 412 y E21053. Caller IDs cubre cómo registrar y verificar uno a través de la API.

El destino del reenvío se comprueba cuando lo configuras y de nuevo en cada llamada que reenvía. Un caller ID que elimines después deja de reenviar en lugar de continuar, y las llamadas entrantes se rechazan a partir de ese momento.

La llamada reenviada suena durante 45 segundos antes de darse por perdida, más tiempo que una entrega a trunk, porque el extremo remoto suele ser el teléfono de una persona y no un sistema telefónico.

Un reenvío realiza una llamada, así que las reglas de salida se aplican al segundo tramo: reenviar a un país que no hayas activado en Destinations se rechaza con destination_not_enabled.

Un reenvío, dos registros de llamada

Una llamada reenviada produce dos registros de tramo que comparten un call_id:

Usa el filtro call_id en la lista de tramos para encontrar las conexiones relacionadas, o abre Voice > Calls. El registro de la llamada entrante es el que indica cómo estaba configurado el número.

Elegir qué número muestra una llamada reenviada como el que llama

Una llamada reenviada tiene dos números que podría presentar a quien responda, y la elección cambia tanto lo que ven como la probabilidad de que un operador interfiera con la llamada:

• Calling number es el número propio de quien llama, así que el teléfono suena como si hubiera marcado directamente y la llamada se puede devolver desde el registro de llamadas. Como el número no es tuyo, algunos operadores, sobre todo en EE. UU. y partes de Europa, marcan esas llamadas como no verificadas, reemplazan el número o las filtran.
• Dialed number es el número que marcó quien llama, que es uno de los tuyos. Quien responda ve cuál de tus números se marcó, en lugar de quién llamó.

Indica la elección en cada reenvío que escribas a través de la API o CLI. Una configuración anterior sin elección almacenada devuelve el número marcado.

El inbound_configuration.forward_as_options del número lista las opciones disponibles para el editor. Las opciones actuales incluyen el número que llama y el número marcado. Lee esas opciones al construir una integración, y usa el forward_as devuelto para confirmar el ajuste efectivo.

En una lectura, forward_as es el valor que las llamadas realmente llevan, que puede diferir del último valor escrito.

Consultar qué hizo un número con una llamada

El registro de una llamada entrante lleva un route junto a su estado, y route es lo que el número estaba configurado para hacer en el momento en que se gestionó la llamada. Cambiar el ajuste del número después no cambia lo que dicen sus llamadas anteriores.

route indica lo que el número estaba configurado para hacer, no que haya funcionado. Una ruta trunk en una llamada que nunca se conectó es un número apuntado a un trunk que no aceptó la llamada, y el estado de la llamada es lo que refleja el resultado. route está ausente en llamadas salientes y en llamadas registradas antes de que existiera el campo.

En el panel, abre la llamada desde Voice > Legs y consulta la fila Inbound route, que enlaza al número cuya configuración la decidió. A través de la API, route está en GET /v1/voice/legs/{leg_id} y GET /v1/voice/legs, y direction filtra la lista a llamadas entrantes.

Para una ruta de secuencia, consulta también la página Runs de la secuencia para identificar la entrada y la versión que se ejecutaron. La configuración actual del número puede diferir de la versión conservada por una llamada anterior.

Diagnosticar una llamada entrante rechazada

Una llamada entrante que fue rechazada se registra con el estado rejected. Dos cosas distintas lo producen, y rejection_reason es lo que las distingue:

• Rechazada sin rejection_reason. El propio número rechazó la llamada. La llamada no falló ninguna comprobación nuestra, por lo que no indica motivo, y route dice lo que el número estaba configurado para hacer. Una ruta reject es un número configurado para rechazar, o uno sin ruta propia mientras la ruta por defecto del espacio de trabajo es rechazar.
• Rechazada con rejection_reason. La llamada falló una de nuestras comprobaciones antes de llegar a tu sistema telefónico. El motivo indica la comprobación. Rejected calls lista todos los motivos y su solución.

failed es un estado diferente y no significa rechazada: significa que se intentó la llamada y no funcionó, con sip_response_code indicando la respuesta recibida.

Lee route y rejection_reason juntos para distinguir los rechazos:

Los límites de la cuenta también se aplican a las llamadas entrantes: si superas el saldo de tu monedero, el límite diario de gasto en voz de tu organización, o tus límites de concurrencia y por segundo, la llamada entrante se rechaza con el motivo correspondiente. Voice overview cubre los propios límites.

Comprobar cuánto cuesta una llamada recibida

Recibir una llamada tiene coste. La tarifa depende del país y tipo del número que la recibe, y se publica por país en Receiving calls en la página de precios de voz, junto a las tarifas de las llamadas que realizas.

Un reenvío se factura como dos llamadas: la llamada entrante a la tarifa de recepción, y el tramo que realizamos a la tarifa de salida del número al que reenvías. Se cobra una única tarifa de gestión por la llamada, no una por tramo.

El monedero se comprueba antes de entregar una llamada entrante, así que un saldo que no pueda cubrirla significa que la llamada se rechaza en lugar de facturársete después. Cost and billing cubre cómo funcionan el tiempo facturable, las tarifas y el monedero en ambas direcciones.

Próximos pasos