Realizar llamadas

Tu PBX, la centralita telefónica que enruta las llamadas, envía un SIP INVITE al dominio SIP del trunk para realizar una llamada. Bird comprueba la solicitud, la enruta a un operador y retransmite el audio. Esta página cubre los requisitos previos, los campos de la solicitud, la autenticación y el coste.

Antes de realizar una llamada

Cuatro cosas deben estar listas, en cualquier orden, y tres de ellas las configuras tú:

Un trunk que acepte tu tráfico. Crea un trunk SIP y habilita las llamadas salientes. Añade los rangos de IP de tu equipo, una clave API permitida, o ambas cosas. Los clientes que no pueden guardar un secreto de larga duración pueden usar una credencial de sesión.
Un identificador de llamada verificado. Registra el número que presentas y completa su llamada de verificación, que es la forma en que un espacio de trabajo demuestra que posee los números que presenta. 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 verificación y entrega de CLI.
El país de destino habilitado. Activa los países a los que llamas en la página Destinations.
Enrutamiento asignado a tu espacio de trabajo. Bird lo configura por ti, eligiendo qué operadores sirven cada destino. Hasta que esté configurado, las llamadas se rechazan con routing_not_configured, una de las razones que cubre Llamadas rechazadas.

Qué espera Bird en el INVITE

Envía la solicitud al dominio SIP de tu trunk en uno de sus puertos admitidos. Dos cabeceras contienen todo lo que Bird necesita:

Cabecera	Qué hace Bird con ella
To	El número al que se llama. Bird lee su país para elegir un operador y tarificar la llamada
From	El número que presentas como llamante. Debe ser un identificador de llamada verificado en este espacio de trabajo

Usa números internacionales completos en formato E.164, un + inicial seguido del código de país y el número nacional, en ambas cabeceras. Es la forma en que Bird registra la llamada y la forma que espera su coincidencia de destino.

Aparte de esas dos cabeceras, se trata de una llamada SIP normal, sin cabeceras personalizadas en ninguna dirección.

Autenticación de cada llamada

Lo que atraviesa una llamada depende de cómo esté abierto el trunk:

Solo lista de IP permitidas. Una sola solicitud. Bird compara la dirección de origen con la lista y enruta la llamada, sin ningún desafío que responder.
Solo claves API permitidas. Bird solicita primero una contraseña a la llamada, mediante el intercambio Digest SIP.
Ambos. La dirección de origen se comprueba antes de que Bird envíe cualquier desafío, por lo que una llamada desde una dirección no incluida se rechaza sin importar las credenciales que lleve.
Credenciales de sesión activadas. Bird envía un desafío a la llamada venga de donde venga, incluso desde una dirección que la lista de permitidas no cubre, y responde una credencial emitida minutos antes. Los equipos ya admitidos por la lista de permitidas en un trunk sin claves permitidas siguen conectándose sin desafío.

Cuando el trunk tiene claves API permitidas, tu sistema telefónico responde con un hash del secreto de la clave API en lugar del secreto en sí, que es lo que hace la autenticación Digest SIP:

Tu PBX envía el INVITE.
Bird responde 407 Proxy Authentication Required con una línea de desafío por cada algoritmo que ofrece el trunk, SHA-256 y luego MD5 por defecto.
Tu PBX reenvía el INVITE con una cabecera Proxy-Authorization calculada con el nombre de usuario bird y el secreto de la clave API como contraseña.
Bird verifica la respuesta y continúa el enrutamiento.

Si se envía una cabecera Proxy-Authorization preventiva antes del desafío, tu equipo debe elegir un algoritmo que el trunk ofrezca. Si el trunk también tiene una lista de IP permitidas, la solicitud debe provenir igualmente de una dirección incluida.

Bird responde a un intercambio 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 el registro de llamadas, revisa las credenciales en lugar del enrutamiento.

Atestación de llamadas

Las llamadas a Estados Unidos y Francia llevan atestación STIR/SHAKEN. Los operadores usan esta firma al etiquetar llamadas. Bird aplica el nivel B por defecto sin configuración adicional. Contacta con soporte para solicitar el nivel A.

Cuando se rechaza una llamada

Bird comprueba el identificador de llamada, el destino, los límites y el saldo del monedero antes de marcar al operador. El rechazo llega a tu sistema telefónico como SIP 503; la causa específica queda en el registro de llamada autenticado. 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 continúa hasta que reduces el ritmo de marcación.

Las llamadas de emergencia no se cursan

Bird Voice no cursa llamadas a servicios de emergencia. Una llamada al 112, 911, 999 o cualquier otro número de emergencia se rechaza, en todos los trunks, en todos los países. Tu sistema telefónico debe alcanzar los servicios de emergencia por otra vía.

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

Los servicios de emergencia dependen de la ubicación registrada del llamante, que Bird no almacena para un trunk. No dependas de una ruta Bird para llamadas de emergencia.

Coste y facturación

La voz se prepaga desde el monedero de tu organización, igual que los demás canales:

El tiempo facturable va desde la respuesta hasta el fin de la llamada, sin importar cuánto tiempo sonó antes. El registro de llamada lo muestra junto a Total duration, que se cuenta desde el momento en que Bird recibió la llamada.
La tarifa depende del país de destino. Tu tarjeta de tarifas indica el precio de cada país en la moneda del monedero. Una tarifa define un tiempo mínimo facturado y el incremento que se usa tras 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 monedero se comprueba antes de marcar al operador. Una llamada que tu saldo no pueda cubrir se rechaza con insufficient_balance de inmediato, en lugar de facturársete después. Mantén un margen o activa las recargas automáticas.
Se aplica un límite diario de gasto en voz. Una vez superado, las llamadas se rechazan con daily_spend_exceeded hasta que comience el siguiente día UTC. El importe depende de tu plan.
El coste aparece en la llamada una vez tarificada, con precisión completa, neto de impuestos.

Para totalizar el gasto en llamadas, exporta la lista filtrada de llamadas como CSV desde la página Calls, o consulta tus facturas y consumo.

Siguientes pasos

Página	Qué cubre
Registro de llamadas	Consultar, filtrar y exportar tus registros de llamadas
Eventos de voz	Recibir resultados de llamadas en tus propios sistemas
Métodos de pago y monedero	Recargas, recargas automáticas y cómo se consume el monedero

Recursos relacionados

Continúa con la documentación, guías y ejemplos sobre este tema. Los recursos están en inglés.

Comprender el conceptoWhat is a voice API?Explorar la funcionalidadVoice Guía de implementaciónVoice overview

Obtener un resumen de implementación