Realizar llamadas

Tu PBX envía un INVITE SIP al dominio SIP de la troncal para realizar una llamada. Bird comprueba la solicitud, la enruta a un operador y retransmite el audio. Esta página explica los requisitos previos, los campos de la solicitud, la autenticación y el coste.

Para iniciar una llamada desde tu aplicación mediante HTTP, usa la guía para crear llamadas. Esta vía ejecuta una secuencia publicada de Bird cuando se contesta la llamada.

Antes de realizar una llamada

Configurar una troncal SIP explica paso a paso la configuración completa de una troncal para ambas direcciones.

Deben estar listos cuatro elementos, sin importar el orden. Tres de ellos los configuras tú:

• Una troncal que acepte tu tráfico. Crea una troncal SIP y habilita las llamadas salientes. Añade los rangos de IP de tu equipo, una clave de API permitida o ambos. Los clientes que no puedan almacenar un secreto de larga duración pueden usar una credencial de sesión.
• Un identificador de llamada válido. Usa un número de Bird asignado a este espacio de trabajo o registra un número externo y completa su llamada de verificación. La verificación no garantiza la entrega de extremo a extremo del CLI ni la conexión de la llamada cuando el CLI no es un número adquirido a través de Bird: consulta el aviso de exención de responsabilidad sobre la verificación y la entrega del CLI.
• El país de destino habilitado. Activa los países en los que prestas servicio en la página Destinations.
• El enrutamiento vinculado a tu espacio de trabajo. Bird lo configura por ti y elige qué operadores atienden cada destino. Hasta que esté configurado, las llamadas se rechazan con routing_not_configured, uno de los motivos que se explican en Llamadas rechazadas.

Qué espera Bird en el INVITE

Envía la solicitud al dominio SIP de tu troncal por uno de sus puertos compatibles. Bird lee tres partes de la solicitud:

Escribe los números en formato internacional E.164: un + inicial seguido del código de país y el número nacional. Bird también acepta el mismo número con 00 en lugar de +, o solo con dígitos que empiecen por el código de país. Bird interpreta que los dígitos sin + ni 00 empiezan por un código de país, por lo que un número en formato nacional no se interpreta como el número que querías indicar. No añadas un prefijo técnico al número al que llamas.

Aparte de estos requisitos, se trata de una llamada SIP normal y no necesitas enviar ninguna cabecera personalizada.

Ofrece G.711, A-law o µ-law en tu SDP. Envía los tonos del teclado (DTMF) como eventos telefónicos RFC 4733. Bird elimina otros códecs, como G.729 u Opus, de la oferta que envía al operador, así que incluye G.711 en cada oferta.

El contenido multimedia se transmite mediante RTP sin cifrar. No se admite SRTP. TLS en el puerto 5061 cifra la señalización, pero el audio permanece sin cifrar.

Autenticación de cada llamada

El proceso que sigue una llamada depende de cómo se permita el acceso a la troncal:

• Solo lista de direcciones IP permitidas. Una única solicitud. Bird comprueba si la dirección de origen está en la lista y enruta la llamada, sin enviar un desafío al que haya que responder.
• Solo claves API permitidas. Bird solicita primero una contraseña para la llamada mediante el intercambio Digest de SIP.
• Ambas opciones. Las llamadas que usan una clave API permitida también deben proceder de una dirección incluida en la lista. Las credenciales de sesión habilitadas proporcionan la vía de acceso independiente que se describe a continuación.
• Credenciales de sesión habilitadas. Bird envía un desafío a la llamada, sea cual sea su origen, incluso si procede de una dirección que no figura en la lista de direcciones permitidas. Para responder se utiliza una credencial que emitió unos minutos antes. Los equipos ya admitidos por la lista de direcciones permitidas en una troncal sin claves permitidas siguen conectándose sin desafío.

Si la troncal tiene claves API permitidas, tu sistema telefónico responde con un hash del secreto de la clave API, en lugar del propio secreto. Así funciona la autenticación Digest de SIP:

1. Tu PBX envía el INVITE.
2. Bird responde con 407 Proxy Authentication Required e incluye una línea de desafío por cada algoritmo que ofrece la troncal: de forma predeterminada, SHA-256 y después MD5.
3. Tu PBX vuelve a enviar el INVITE con una cabecera Proxy-Authorization calculada con el nombre de usuario bird y el secreto de la clave API como contraseña.
4. Bird verifica la respuesta y continúa con el enrutamiento.

Una cabecera Proxy-Authorization preventiva se envía antes del desafío, por lo que tu equipo debe elegir un algoritmo que ofrezca la troncal. Para la autenticación con clave API, una troncal con una lista de direcciones IP permitidas sigue exigiendo que la solicitud proceda de una dirección de esa lista.

Bird responde a un intercambio de autenticación fallido en la capa SIP, por lo que el intento se rechaza antes de que la plataforma cree un registro de llamada. Si tus llamadas no aparecen en absoluto en el registro de llamadas, revisa las credenciales en lugar del enrutamiento.

Atestación de llamadas

Las llamadas a Estados Unidos y Francia incluyen una atestación STIR/SHAKEN. Los operadores utilizan esta firma al etiquetar las llamadas. Bird aplica el nivel B de forma predeterminada, sin configuración adicional. Contacta con soporte para solicitar el nivel A.

Cuándo se rechaza una llamada

Bird comprueba el identificador de llamada, el destino, los límites y el saldo del monedero antes de marcar a través de un operador. Tu sistema telefónico recibe el rechazo como SIP 503; la causa específica queda en el registro de la llamada, accesible tras autenticarse. Abre la llamada en el registro de llamadas o consulta llamadas rechazadas para ver cada motivo y su solución.

Resuelve la causa registrada antes de reintentar. Por ejemplo, calls_per_second_exceeded sigue produciéndose hasta que reduzcas la frecuencia de marcación.

Las respuestas a una llamada registrada por Bird, incluido el 503 de un rechazo con un motivo registrado, incluyen una cabecera X-BIRD-CALL-ID con el Leg ID de la llamada (vcl_…). Consulta el registro con GET /v1/voice/legs/{leg_id} o facilita ese identificador a soporte.

No se cursan llamadas de emergencia

Bird Voice no cursa llamadas a los servicios de emergencia. Las llamadas al 112, 911, 999 o a cualquier otro número de emergencia se rechazan en todas las troncales y en todos los países. Tu sistema telefónico debe comunicarse con los servicios de emergencia por otra ruta.

Este comportamiento no depende de tu plan, saldo ni destinos. Configura tu sistema telefónico para que enrute las llamadas de emergencia a través de un servicio que las admita, como una línea PSTN local, una pasarela en tus instalaciones u otro proveedor. Prueba esa ruta. Bird devuelve 503 cuando rechaza una llamada de emergencia, lo que permite que un sistema telefónico con otra ruta en su plan de marcación intente utilizarla.

Los servicios de emergencia dependen de la ubicación registrada de quien llama, que Bird no almacena para las troncales. No dependas de una ruta de Bird para las llamadas de emergencia.

Coste y facturación

Voice se paga por adelantado con el saldo del monedero de tu organización, al igual que los demás canales:

• El tiempo facturable va desde que se contesta la llamada hasta que termina, independientemente de cuánto tiempo haya sonado antes. El registro de la llamada lo muestra junto a Total duration, que se mide desde el momento en que Bird recibió la llamada.
• La tarifa depende del país de destino. Tu tabla de tarifas indica el precio para cada país en la moneda del monedero. Cada tarifa define un tiempo mínimo facturable y el incremento que se aplica una vez superado ese mínimo. Por ejemplo, una tarifa con un mínimo de un minuto e incrementos de seis segundos factura una llamada de 10 segundos como un minuto.
• El saldo del monedero se comprueba antes de cursar la llamada al operador. Si tu saldo no puede cubrir una llamada, esta se rechaza con insufficient_balance de antemano, en lugar de facturártela después. Mantén un margen de saldo o activa las recargas automáticas.
• Se aplica un límite diario de gasto en voz. Si se supera, las llamadas se rechazan con daily_spend_exceeded hasta que comienza el siguiente día UTC. En un espacio de trabajo también puedes establecer un límite diario por país de destino en Voice > Destinations. Cada llamada debe respetar ambos límites. El importe depende de tu plan.
• El coste aparece en la llamada una vez calculado según la tarifa, con toda su precisión y sin impuestos.

Para revisar los cargos de todas las llamadas, consulta Uso, gasto y facturas. La exportación CSV de Legs incluye las duraciones y el tiempo facturable, pero no tiene una columna de coste.

Próximos pasos