Troncales SIP
Una troncal SIP conecta tu sistema telefónico con Bird. Le da a tu PBX una dirección para llamadas salientes, define cómo Bird las autentica y también puede recibir las llamadas que llegan a los números que tienes asignados. Configura las troncales en Voice > SIP Trunks.
La mayoría de las configuraciones solo necesitan una troncal. Crea troncales separadas cuando los sitios o sistemas requieran listas de IP permitidas, claves API, configuraciones de credenciales de sesión o algoritmos Digest diferentes.
Crear una troncal
Selecciona Create trunk e introduce un nombre. Puedes cambiar esta etiqueta del panel más adelante; no se envía con las llamadas.
Bird asigna un dominio SIP fijo a la troncal. Introduce este dominio en tu sistema telefónico para que Bird pueda asociar las llamadas con la troncal.
Una troncal nueva rechaza todas las llamadas hasta que le indiques quién puede realizarlas: un rango de IP, una clave API, credenciales de sesión o una combinación.
Dirección de llamada
Una troncal maneja cada dirección por separado, y una troncal nueva no maneja ninguna. La página de la troncal tiene una sección por dirección, y una dirección desactivada solo muestra el control para activarla.
Llamadas salientes es tu PBX realizando llamadas a través de Bird. Selecciona Enable outbound. Mientras no esté habilitado, la troncal rechaza todo intento saliente sin importar sus credenciales. Los datos de conexión, las listas de permitidos, las claves, las credenciales de sesión y la oferta Digest de la troncal están todos en esta sección, porque controlan qué puede conectarse.
Llamadas entrantes es Bird entregando llamadas a tu PBX para los números que esta troncal atiende. Selecciona Enable inbound y luego agrega al menos una pasarela de entrega: una troncal sin pasarela rechaza toda llamada entrante a sus números. La lista Inbound numbers de la sección muestra cuáles de tus números envían sus llamadas aquí.
Apuntar un número a la troncal se hace desde el número, no desde aquí. Consulta Recibir llamadas para eso y para saber qué hacen los formatos de número de una pasarela.
Warning: turning inbound calling off puts every number pointing at this trunk back on reject, and turning it back on does not restore them. Deleting the trunk does the same.
Datos de conexión
Abre una troncal para ver qué introducir en tu PBX:
| Ajuste | Valor |
|---|---|
| Dominio SIP | El dominio propio de la troncal. Cópialo completo desde la página de la troncal |
| Username | Siempre bird |
| Password | El secreto de una clave API permitida en esta troncal (consulta Autenticación con clave API) |
Note: with the IP allow list alone, the SIP domain and a port are all you need: the username and password are for API key authentication. A client holding a session credential uses the password from that credential instead.
Envía tus llamadas al dominio SIP en uno de estos puertos:
| Transporte | Puerto | Notas |
|---|---|---|
| UDP | 5060 | El predeterminado que asume la mayoría de los equipos |
| TCP | 5060 | Mismo puerto que UDP, así que elige el transporte en tu PBX |
| TLS | 5061 | SIP sobre TLS, para señalización que quieras cifrar en tránsito |
Controlar quién puede enviar llamadas
Una troncal puede autenticar equipos por dirección IP de origen, clave API o una credencial de sesión de corta duración. Habilita los métodos que tus clientes necesiten.
Configúralos en IP allow list, Allowed API keys y Session credentials. Los cambios guardados se aplican a las llamadas nuevas.
Lista de IP permitidas
Agrega las direcciones públicas desde las que tu equipo envía SIP, como direcciones individuales o rangos CIDR, cada una con una descripción opcional. El filtrado por IP se activa en cuanto la lista tiene una entrada: a partir de ese momento, solo los rangos listados pueden enviar llamadas a esta troncal.
Agrega la dirección pública de origen que llega a Bird. Para equipos detrás de NAT, usa la dirección pública del router en lugar de la dirección privada del sistema telefónico. Bird rechaza las llamadas de direcciones no listadas en la capa SIP, por lo que normalmente no aparecen en el registro de llamadas. Consulta solución de problemas de voz para llamadas faltantes.
Autenticación con clave API
Bird puede, en su lugar (o además), pedir una contraseña en cada llamada. El intercambio es autenticación Digest SIP: Bird envía un desafío, tu sistema telefónico responde con un hash de la contraseña en lugar de la contraseña misma, y Bird lo verifica contra una clave API de Bird.
- Dale a una clave API el permiso voice en nivel write, que es el nivel contra el que una troncal se autentica. Agrégalo a una clave que ya tengas o crea una nueva. En ambos casos, el secreto de la clave sigue funcionando igual: una clave ya desplegada conserva el secreto con el que tus sistemas están configurados, y una clave nueva muestra su secreto una sola vez, al crearla, así que guárdalo en ese momento. Consulta Claves API.
- En la página de la troncal, dentro de Allowed API keys, agrega esa clave.
- En tu PBX, establece el nombre de usuario como bird y la contraseña como el secreto de la clave.
La autenticación con clave API se activa en cuanto la lista tiene una clave: a partir de ese momento, solo las claves que listes pueden autenticarse.
Quitar el permiso voice de una clave detiene su autenticación de inmediato, pero la troncal la conserva en la lista de permitidas. Vuelve a agregar el permiso y la troncal funciona de nuevo con el mismo secreto, sin necesidad de cambiar nada en la troncal ni en tu PBX. Mientras falta el permiso, la página de la troncal marca esa clave para que la lista de permitidas nunca se muestre como funcional cuando no lo es.
Revocar o eliminar una clave API elimina su capacidad de autenticación de forma inmediata, en cada troncal que la permitía, y esa acción es permanente. Para rotar, agrega primero la nueva clave a la troncal, migra tu equipo y luego revoca la antigua.
Credenciales de sesión
Una credencial de sesión es un nombre de usuario y contraseña SIP de corta duración. Responde al mismo desafío Digest que una clave API sin exponer un secreto de larga duración.
Actívalas en Session credentials en la página de la troncal; están desactivadas en una troncal nueva. Lo que admiten:
- El teléfono del panel, que genera una por llamada automáticamente.
- Un cliente SIP controlado por la CLI: bird voice tools test-call genera una para la llamada que realiza, y bird voice session-credentials create genera una para pegar en cualquier otro cliente. Ambos necesitan acceso de voz en nivel write.
Una credencial pertenece al espacio de trabajo y no a una sola troncal, así que un cliente puede usarla en las troncales elegibles. El cliente debe presentar la credencial y la troncal debe tener las credenciales de sesión habilitadas. Bird devuelve la contraseña solo al generarla.
Activarlas no cambia cómo se conecta el equipo de la lista de IP permitidas: una llamada desde una dirección listada, en una troncal sin claves API permitidas, sigue siendo admitida sin desafío de contraseña.
Algoritmo Digest
Por defecto, Bird ofrece SHA-256 primero y MD5 segundo. Tu PBX responde con el primer algoritmo que soporte.
Cambia la oferta en Digest algorithm cuando tu equipo lo requiera. Para un PBX que maneja mal un desafío que comienza con SHA-256, selecciona MD5 only. Una troncal solo acepta los algoritmos que ofrece. Las claves API funcionan con cualquiera de los dos algoritmos y no necesitan reemitirse.
Mantén MD5 en la oferta en cualquier troncal desde la que llames con el teléfono: un navegador responde solo con MD5, así que una troncal que ofrezca solo SHA-256 rechaza todas las llamadas del navegador.
Eliminar una troncal
Eliminar una troncal surte efecto de inmediato: su dominio SIP deja de aceptar llamadas nuevas y todos los números que apuntaban a ella vuelven a rechazar llamadas. Las llamadas en curso continúan, y los registros de llamadas realizadas a través de la troncal permanecen en tu Registro de llamadas.
Siguientes pasos
| Página | Qué cubre |
|---|---|
| Realiza tu primera llamada | Desde un espacio de trabajo vacío hasta un teléfono sonando |
| Teléfono | Llamar desde el panel, a través de una troncal que acepta credenciales de sesión |
| Realizar llamadas | Lo que Bird espera en la INVITE y cuánto cuesta una llamada |
| Recibir llamadas | Apuntar un número a esta troncal y sus pasarelas de entrega |
| Caller IDs | Registrar un número y demostrar que es tuyo con una llamada de verificación |
| Claves API | Crear una clave, elegir sus alcances y rotarla |
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 funcionalidadVoiceGuía de implementaciónVoice overview
Obtener un resumen de implementación