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, hacer sonar un grupo de timbrado de personas conectadas en el teléfono del navegador o rechazarla. Cada número tiene una sola 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 las pruebas y la publicación.
- Para un grupo de timbrado: un grupo de timbrado cuyos miembros se conecten en el teléfono del navegador. En Inbound routing, selecciona Ring a ring group, elige el grupo y guarda.
- Para cambiar el ajuste a través de la API o CLI: una clave API con el alcance
voice_managementen nivel de escritura. Ese alcance cubre la configuración de voz; el alcancevoicecubre 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 primero esa dirección, porque un número solo se puede apuntar a un trunk que ya acepte llamadas entrantes. Configurar un trunk SIP recorre toda la configuración en orden.
- Abre Voice > SIP Trunks, abre el trunk y en Inbound calling selecciona Enable inbound.
- En Inbound routing, añade tus gateways en la pestaña Gateways, agrúpalos en la pestaña Groups y establece Default route en Route to group en la pestaña Rules. Selecciona Review and save y confirma.
- Abre Voice > Numbers, abre el número y en Inbound routing elige Deliver to a SIP trunk.
- 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.
Un trunk con llamadas entrantes activadas tiene su propio Inbound routing: los Gateways a los que puede llegar, los Groups que los recorren, Rules opcionales y una Default route. Bird entrega cada llamada a un grupo, así que un gateway solo suena cuando una regla o la ruta por defecto envía la llamada a un grupo que lo contiene. Conmutar por error y repartir llamadas entrantes muestra cómo configurar la conmutación por error y el reparto de carga. Enrutar llamadas entrantes de trunk por origen y número de quien llama ofrece reglas funcionales para llamadas desde móviles y fijos y para prefijos según el origen de quien llama.
| Parte | Qué hace |
|---|---|
| Gateways | Las direcciones a las que se pueden entregar las llamadas, con sus formatos de número |
| Groups | Un conjunto de gateways que se prueban para una llamada. Order es Sequential (orden de la lista), Random (aleatorio en cada llamada) o Weighted (primero la Priority más baja; Weight reparte dentro de una prioridad). Cada miembro tiene un Ring time |
| Rules | Condiciones opcionales, que se comprueban en orden. La primera regla que coincide decide la llamada |
| Default route | Qué ocurre con una llamada que no coincide con ninguna regla: Route to group, Reject o Forward to number |
Un trunk cuyo enrutamiento nunca se ha guardado envía cada llamada a todos sus gateways, por orden de prioridad. Cuando guardas el enrutamiento en el panel, deciden los grupos y la ruta por defecto guardados. Una ruta por defecto guardada como Reject rechaza todas las llamadas que no coinciden con ninguna regla.
Al guardar, el panel muestra el aviso Calls never reach some gateways si un gateway no está en ningún grupo que use una regla o la ruta por defecto. Las llamadas nunca hacen sonar ese gateway. Cuando la ruta por defecto rechaza y ninguna regla envía la llamada a un grupo, la llamada se rechaza antes de llegar a tu equipo, como muestra Diagnosticar una llamada entrante rechazada.
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 31201234567curl -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"
}
}
}
JSONcurl -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:
| Ajuste | Qué es |
|---|---|
| URI SIP | El nombre de host o la dirección IPv4 de tu sistema telefónico, con un puerto opcional, como en sip:pbx.example.com:5060. Para TLS, usa sips:pbx.example.com:5061 o sip:pbx.example.com:5061;transport=tls. Indica solo el host: se rechaza un URI que incluya user part |
| Priority | El orden en que se prueban los gateways, del más bajo al más alto |
| Destination format | Cómo se escribe el número marcado para este par. Por defecto, E.164 |
| Origination format | Cómo se escribe el número que llama para este par, en la cabecera P-Asserted-Identity de la llamada entregada. Por defecto, E.164 |
En el panel, el URI SIP se introduce como Host, Port y Transport, y el formato de destino aparece como R-URI user part. A través de la API, son sip_uri y destination_format. En el panel eliges un formato de la lista del campo, como Without the plus, y la API devuelve la misma opción escrita con {number}.
Los gateways que comparten prioridad reciben una parte igual de las llamadas, y cualquiera de ellos puede probarse primero en una llamada concreta. Para que la entrega pase a una segunda dirección si falla, asigna a ese gateway un número de prioridad mayor: se prueba cuando el primero no responde. La prioridad se aplica mientras el enrutamiento del trunk no se haya guardado nunca. Cuando guardas el enrutamiento en el panel, sus grupos fijan el orden, y un gateway añadido después, también a través de la API, solo suena cuando lo incluyes en un grupo.
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:5060curl -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.
- Abre Voice > Numbers.
- 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.
- Abre Voice > Numbers, abre el número y en Inbound routing elige Forward to another number.
- 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.
- 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_numbercurl -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:
| Registro | Qué es |
|---|---|
| La llamada entrante | direction es inbound, y route indica que el número estaba configurado para reenviar, a qué número, y qué número presentó el tramo reenviado |
| La llamada reenviada | direction es outbound, desde el número que el tramo presentó hasta el número al que reenvías. No tiene route propio |
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. Si quien llama oculta su número, este sigue oculto y la persona que recibe la llamada la ve como anónima. 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.type | Qué hizo el número |
|---|---|
trunk | La llamada se entregó al trunk SIP indicado en trunk_id |
forward | La llamada se reenvió al número en forward_to, presentando el número en forward_as |
reject | El número rechazó la llamada |
sequence | La llamada seleccionó la secuencia en sequence_id y la entrada en entry_node_id |
ring_group | La llamada hizo sonar el grupo de timbrado indicado en ring_group_id, que puede haberse eliminado desde entonces |
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 llamada de secuencia admitida, consulta la página Runs de la secuencia para identificar la entrada y la versión que se ejecutaron. Una llamada rechazada porque su secuencia estaba en pausa, archivada o sin publicar tiene una ruta seleccionada, pero ninguna ejecución. 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. Para leer el motivo de rechazo y la ruta de una secuencia necesitas voice_management:read; sin él, la ausencia de motivo puede significar que los detalles están ocultos. Pide a un administrador del espacio de trabajo con ese permiso que consulte el ID del tramo.
- 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, yroutedice lo que el número estaba configurado para hacer. Una rutarejectes 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:
route y motivo | Causa |
|---|---|
reject, sin motivo | El número tiene su propia ruta configurada como rechazar, o no tiene ruta propia y la ruta por defecto del espacio de trabajo es rechazar. Abre el número para ver cuál es el caso. Eliminar un trunk, o desactivar sus llamadas entrantes, puede hacer que un número que antes funcionaba termine aquí |
trunk, sin motivo | El enrutamiento propio del trunk rechazó la llamada: su Default route (o una regla coincidente) está configurada como Reject. Esto ocurre con un trunk guardado con gateways pero sin grupo, o con la ruta por defecto todavía en rechazar. Abre el Inbound routing del trunk, pon los gateways en un grupo y establece la Default route a ese grupo |
forward, sin motivo | El destino del reenvío ya no es un caller ID verificado. Vuelve a verificarlo en Caller IDs, o reenvía a otro número |
forward, destination_not_enabled | No se pudo realizar el segundo tramo hacia el país del destino del reenvío. Activa ese país en Destinations |
Un número apuntado a un trunk sin ningún gateway guardado rechaza la llamada antes de que exista un registro, así que la llamada no aparece en el registro de tramos. Añade un gateway en el Inbound routing del trunk y guarda el enrutamiento.
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
| Página | Qué cubre |
|---|---|
| Trunks SIP | Crear un trunk, sus dos direcciones y controlar quién puede enviar |
| Caller IDs | Registrar un número y demostrar que lo controlas |
| Grupos de llamada | Hacer sonar a tu equipo en el teléfono del navegador cuando llega una llamada |
| Registro de llamadas | Todos los campos de un registro de llamada y todos los motivos de rechazo |
| Eventos de voz | Recibir resultados de llamadas en tus propios sistemas |
| Solución de problemas de voz | Diagnosticar una llamada que no se completa, a partir de su síntoma |
Recursos relacionados
Continúa con la documentación, guías y ejemplos de este tema.