Preguntas frecuentes de Voice API
¿Qué es Bird Voice?
Bird Voice te permite realizar llamadas a números telefónicos a través de un troncal SIP. Tu sistema telefónico se conecta a Bird, y Bird enruta cada llamada a través de un operador hacia la red telefónica pública (la PSTN). Tú proporcionas tu propia PBX o softphone; Bird se encarga del tramo del operador.
¿Qué tan rápido puedo hacer mi primera llamada?
Unos diez minutos. Crea un troncal SIP, verifica un identificador de llamada, habilita el país de destino y apunta tu sistema telefónico a la dirección del troncal. La guía de primera llamada te lleva paso a paso por todo el proceso.
¿Qué necesito antes de poder llamar?
Tres cosas de tu lado: un troncal SIP con tu equipo autorizado (por rango de IP o clave API), un identificador de llamada verificado (el número que presentas como llamante) y el país de destino habilitado. Bird asigna el enrutamiento a tu workspace, que es el cuarto requisito y se configura del lado de Bird.
¿Necesito hardware especial?
No. Cualquier sistema telefónico compatible con SIP funciona: un softphone como Zoiper o Linphone en un portátil, una PBX como Asterisk o FreeSWITCH, o un sistema comercial como 3CX o FreePBX. Bird te asigna un dominio SIP y tú apuntas tu equipo hacia él.
¿Puedo hacer llamadas desde el navegador?
Sí. Puedes realizar llamadas desde la aplicación Phone del panel de control utilizando WebRTC.
¿Cómo se tarифican las llamadas de voz?
Por llamada, a una tarifa que depende del país de destino. Cada tarifa incluye un incremento de facturación: un tiempo mínimo facturado y luego el paso al que se redondea en adelante. Una tarifa con un mínimo de un minuto y pasos de seis segundos cobra una llamada de 10 segundos como un minuto completo.
¿Cuándo comienza la facturación?
El tiempo facturable corre desde el momento en que el número llamado contesta hasta que la llamada termina. El tiempo de timbrado no se cobra, así que una llamada que nadie contesta no tiene costo.
¿La voz es prepago o postpago?
Prepago, desde el saldo de tu organización. Bird verifica tu saldo antes de marcar al operador, por lo que una llamada que tu saldo no pueda cubrir se rechaza de antemano con insufficient_balance en lugar de facturarse después.
¿Hay un límite de gasto diario?
Sí. Se aplica un tope de gasto diario en voz por organización, que se restablece al inicio de cada día UTC. Una vez superado, las llamadas se rechazan con daily_spend_exceeded. El monto depende de tu plan, y Bird puede aumentarlo a solicitud.
¿Dónde puedo ver cuánto costó una llamada?
Abre la llamada en el registro de llamadas. El costo aparece en el registro una vez que se ha tarifado, con precisión completa y sin impuestos. Para totales entre varias llamadas, exporta la lista filtrada como CSV desde la página de Llamadas, o consulta tus facturas y consumo.
¿Qué límites aplican a mis llamadas?
Tres topes: cuántas llamadas puedes tener en curso a la vez (llamadas concurrentes), cuántas llamadas nuevas puedes iniciar por segundo (llamadas por segundo) y cuánto puedes gastar en voz en un día UTC (gasto diario). Cada uno se establece por organización y los montos dependen de tu plan.
¿Qué pasa cuando alcanzo un límite?
La llamada se rechaza en la configuración, antes de que se marque a un operador. El registro de la llamada indica qué límite se alcanzó: concurrent_calls_exceeded, calls_per_second_exceeded o daily_spend_exceeded. Tu sistema telefónico recibe un SIP 503.
¿Puedo aumentar mis límites?
Sí. Contacta a soporte para solicitar un tope más alto de llamadas concurrentes o de llamadas por segundo. El tope de gasto diario depende de tu plan y también puede aumentarse.
Un marcador de campañas está siendo rechazado, pero tengo mucho margen de llamadas concurrentes. ¿Por qué?
Revisa qué motivo tiene el registro de la llamada. Un marcador puede alcanzar calls_per_second_exceeded sin estar ni cerca del tope de llamadas concurrentes, porque los dos límites son independientes. Reduce la velocidad de marcación y reintenta; reintentar de inmediato obtiene la misma respuesta.
¿Qué es un SIP trunk?
Un SIP trunk es la conexión entre tu sistema telefónico y Bird. SIP (Session Initiation Protocol) es el lenguaje que usan los sistemas telefónicos para establecer llamadas, y un trunk es la línea por la que viajan esas llamadas. Bird asigna a tu workspace una dirección de trunk, y tú apuntas tu sistema telefónico hacia ella.
¿Cuántos trunks necesito?
La mayoría de los workspaces solo necesitan uno. Crea más cuando quieras reglas de acceso separadas por sede o por sistema, ya que la lista de IPs permitidas, las API keys autorizadas y la configuración de Digest son por trunk.
¿Qué datos de conexión necesita mi PBX?
El dominio SIP del trunk (copiado desde la página del trunk), el nombre de usuario bird y la contraseña (el secreto de una clave API autorizada en el trunk). Envíe las llamadas al dominio SIP en el puerto 5060 (UDP o TCP) o 5061 (TLS).
¿Puedo restringir quién envía llamadas a mi trunk?
Sí, con una lista de IPs permitidas, API keys autorizadas, o ambas. Agrega las direcciones públicas desde las que tu equipo envía SIP, o exige que cada llamada se autentique con una API key mediante SIP Digest. Ambas opciones se aplican en la siguiente llamada.
¿Qué sucede cuando elimino un trunk?
El dominio SIP del trunk deja de aceptar nuevas llamadas inmediatamente. Las llamadas en curso continúan, y los registros de llamadas realizados a través del trunk permanecen en tu registro de llamadas.
¿Cómo funciona la autenticación SIP Digest?
Su PBX envía la llamada, Bird responde con un desafío 407 y su PBX reenvía la llamada con un encabezado Proxy-Authorization calculado a partir del nombre de usuario bird y el secreto de su API key como contraseña. Su PBX envía un hash de la contraseña, nunca la contraseña en sí.
¿Qué algoritmos Digest son compatibles?
SHA-256 y MD5. Bird ofrece SHA-256 primero y MD5 segundo de forma predeterminada, y su PBX elige el primero que admita. Si su equipo solo maneja MD5 y gestiona incorrectamente un desafío que comienza con SHA-256, configure el trunk solo para MD5.
¿Puedo usar tanto la lista de IP permitidas como la autenticación con API key?
Sí. Cuando un trunk tiene ambos, la dirección de origen se verifica antes de que Bird solicite una contraseña, por lo que una llamada desde una dirección no incluida en la lista se rechaza independientemente de las credenciales que lleve.
¿Cómo roto una API key sin tiempo de inactividad?
Añada la nueva clave al trunk primero, migre su equipo y luego revoque la antigua. Revocar o eliminar una clave elimina su capacidad de autenticación de inmediato en todos los trunks que la permitían.
¿Qué es un caller ID?
Un caller ID es un número de teléfono que su workspace puede presentar como el llamante en llamadas salientes. Bird verifica el número de origen que su equipo coloca en el encabezado SIP From contra esta lista en cada llamada, por lo que las llamadas solo salen con números que usted ha verificado.
¿Cómo verifico un caller ID?
Añada el número en la página de Números en formato E.164. Bird realizará una llamada de verificación de inmediato. Responda la llamada, escuche un código de seis dígitos e introdúzcalo en el panel. Tiene cinco intentos y el número quedará disponible en cuanto uno sea aceptado.
La llamada de verificación nunca llegó. ¿Qué hago?
Si se agotaron los intentos, utilice Obtener un nuevo código en la fila del número para recibir una nueva llamada de verificación. Si el número aún está esperando su código, elimine el identificador de llamada y añada el número de nuevo.
¿Cómo verifico un número que suena en un sistema desatendido?
Redirija el número a un teléfono que pueda contestar durante el minuto que tarda la verificación y luego restáurelo. Para un número que no recibe llamadas en absoluto, contacte a soporte.
¿Qué sucede cuando elimino un caller ID?
Desde ese momento, cualquier llamada que presente ese número se rechaza con caller_id_not_verified. Las llamadas ya en curso continúan y los registros de llamadas que usaron el número permanecen tal como están.
¿Por qué tengo que habilitar países antes de llamar?
El fraude de peaje funciona marcando países costosos a los que nunca tuvo intención de llamar. Los países que habilita son en los que puede acumular cargos, así que dejar todo lo demás desactivado limita su exposición si alguien compromete su sistema telefónico.
¿Cómo habilito un país de destino?
Busque el país en la página de Destinos usando el cuadro de búsqueda (busca por nombre o código de dos letras) y active su interruptor. El cambio se aplica desde ese momento.
¿Qué significa la insignia de Alto riesgo?
Las llamadas a países de alto riesgo son costosas, y quien opera el número que marca recibe una parte del costo. Estos son los países que un atacante apunta si compromete un sistema telefónico. Déjelos desactivados a menos que tenga negocios allí, y revise la tarifa antes de habilitar uno.
Un país que necesito aparece como No compatible. ¿Qué hago?
Contacte a soporte para que lo habiliten en su cuenta. Available significa que puede habilitarlo; Not supported significa que Bird actualmente no puede realizar llamadas a ese país desde su cuenta.
Mi llamada falló con no_route_found pero el país está habilitado. ¿Por qué?
Un país disponible aún puede tener destinos específicos dentro de él que el enrutamiento todavía no alcanza. Envíe el ID de la llamada a soporte y extenderán el enrutamiento para cubrirlo.
¿Qué espera Bird en el SIP INVITE?
Dos encabezados: To (el número al que se llama) y From (el número que presentas como llamante, que debe ser un identificador de llamada verificado). Ambos deben ser números internacionales completos en formato E.164: un + inicial seguido del código de país y el número nacional. No se necesitan encabezados personalizados.
¿Qué es la atestación STIR/SHAKEN?
STIR/SHAKEN es una firma que los operadores usan para decidir si dejan pasar una llamada sin etiqueta. Las llamadas a Estados Unidos y Francia la incluyen automáticamente sin que tengas que configurar nada. Las llamadas llevan nivel B por defecto; el nivel A (el más fuerte) está disponible bajo solicitud.
Mi llamada fue rechazada. ¿Cómo averiguo por qué?
Abre la llamada en el registro de llamadas. Tu sistema telefónico solo ve un SIP 503 genérico, pero el motivo específico queda en el registro de la llamada, donde solo tú puedes leerlo. Un panel sobre los detalles indica la causa y enlaza a la configuración que la corrige.
¿Debería reintentar una llamada rechazada?
Solo cuando la causa haya desaparecido. Una llamada rechazada por calls_per_second_exceeded obtiene la misma respuesta hasta que reduzcas la velocidad de marcación. Lee el motivo de rechazo antes de reintentar.
¿Qué estados de llamada existen?
Cinco: Answered (el número llamado contestó), No answer (sonó sin respuesta), Failed (la llamada no se completó, ya sea porque Bird la rechazó o un operador falló), Rejected (el operador rechazó la llamada directamente) y Unknown (no se pudo determinar el resultado).
¿Cómo distingo un rechazo de Bird de un fallo del operador?
Ambos aparecen como Failed. El motivo de rechazo es lo que los diferencia: solo un rechazo de Bird incluye uno. Una llamada fallida con motivo de rechazo apunta a una configuración de su lado o del de Bird; una sin motivo de rechazo generalmente apunta al número que marcó.
¿Puedo ver las llamadas que están en curso?
Sí. La pestaña En vivo en la página de Llamadas muestra las llamadas en sus trunks en ese momento, con un contador. Una llamada en vivo se muestra como Ringing (esperando que el otro lado conteste) o In progress (conectada). La pestaña se actualiza cada pocos segundos.
¿Cuál es la diferencia entre duración total y tiempo facturable?
La duración total va desde el momento en que Bird recibió la llamada hasta el cuelgue. El tiempo facturable va desde la respuesta hasta el cuelgue. La diferencia es el tiempo de timbre sin respuesta, por lo que una diferencia grande merece revisar lo que está marcando. Una llamada que nadie contestó no tiene costo.
¿Cómo exporto los registros de llamadas?
Tres formas: descargar CSV desde la página de Llamadas (exporta todos los registros que coincidan con sus filtros actuales, no solo la página visible), leerlos a través de la API con una API key con permisos de voice:read, o usar el Bird CLI con bird voice list.
¿Qué eventos de voz emite Bird?
Tres: voice_call.initiated (Bird aceptó la llamada y comenzó el enrutamiento), voice_call.answered (el número llamado contestó) y voice_call.ended (la llamada terminó, con el resultado). Una llamada no contestada nunca emite el evento answered.
¿Una llamada rechazada emite eventos?
Una llamada que Bird rechaza después de aceptar el INVITE aún termina con voice_call.ended, con estado failed y sip_response_code 503. Así que toda llamada de la que te enteras que se abrió, también se cierra. Una llamada que Bird no puede admitir en absoluto (rechazada en la capa SIP) nunca produce ningún evento.
¿Pueden llegar los eventos desordenados?
Sí. Las entregas no están ordenadas, por lo que answered puede llegarte después de ended. Ordena por el campo timestamp y haz que un evento que llega después con un timestamp anterior pierda.
¿Cómo evito contar eventos dos veces?
Deduplica usando el encabezado HTTP webhook-id. Bird entrega al menos una vez, y el evento initiated de una llamada puede publicarse más de una vez cuando un reintento de señalización lo reproduce. Misma llamada, misma etapa, mismo webhook-id.
¿Dónde están el costo y el motivo de rechazo en los eventos?
Están en el registro de la llamada, no en el evento. Un estado failed en voice_call.ended no indica si lo causó Bird o un operador. Abre la llamada en el registro de llamadas para ver el motivo del rechazo; el costo aparece allí una vez que la llamada ha sido tarifada.
Mi llamada no aparece en el registro de llamadas. ¿Dónde está?
Una llamada que Bird no puede admitir se rechaza en la capa SIP, antes de que exista un registro. Verifica cuatro cosas: el trunk tiene un rango de IPs o una API key que autorice tu equipo, la llamada llegó desde una dirección en la lista de IPs permitidas del trunk (detrás de NAT, esa es la dirección pública del router), las credenciales Digest son correctas (nombre de usuario bird, el secreto de API key correcto, un algoritmo que el trunk ofrezca), y el dominio SIP coincide exactamente con el dominio del trunk.
Mi llamada falló con un motivo de rechazo. ¿Qué hago?
Abre la llamada en el registro de llamadas. El panel sobre los detalles indica la causa y enlaza a la configuración que la corrige. Las siete razones que puedes solucionar son source_not_allowed, caller_id_not_verified, destination_not_enabled, insufficient_balance, daily_spend_exceeded, concurrent_calls_exceeded y calls_per_second_exceeded.
Mi cliente responde al desafío Digest con MD5 y no funciona.
Algunos equipos gestionan mal un desafío que comienza con SHA-256. Configura el algoritmo Digest del trunk solo como MD5, y tu PBX recibirá un desafío que pueda procesar.
Las llamadas se conectan pero el audio va en una sola dirección. ¿Qué pasa?
Tu cliente está detrás de NAT (un router o firewall que reescribe direcciones) y el audio se dirige a una dirección privada que el otro lado no puede alcanzar. Activa el manejo de NAT o STUN en tu cliente para que anuncie su dirección pública en la oferta de medios.
¿La conexión SIP está cifrada?
Puede serlo. Bird admite TLS en el puerto 5061 para la señalización SIP, de modo que la configuración de la llamada se cifra en tránsito. UDP y TCP en el puerto 5060 no están cifrados. Elija el transporte que se ajuste a sus requisitos de seguridad.
¿Cómo verifico que un webhook realmente provino de Bird?
Cada evento se firma con HMAC. Verifica la firma con el secreto de tu endpoint antes de actuar sobre el payload, y rota ese secreto desde el panel de control cuando lo necesites.
¿Dónde se almacenan mis datos?
En la región donde está alojada tu organización, ya sea us1 o eu1. Tu API key lo indica en su prefijo (bk_us1_, bk_eu1_), que es como los SDK y la CLI seleccionan el endpoint correcto sin que tengas que configurar uno.
¿Qué puede hacer una API key utilizada para voz?
Solo lo que le asignes en su alcance. Una clave lleva una lista de scopes, cada uno con permisos de lectura o escritura. Una clave con voice:write puede autenticar llamadas en un trunk; una con voice:read puede listar registros de llamadas. Una clave no puede acceder a canales o configuraciones fuera de sus scopes.
¿Por qué una llamada rechazada devuelve un SIP 503 simple sin detalles?
La razón específica se registra en el registro de llamada, donde solo tú puedes leerla. Devolver un 503 genérico en la capa SIP evita que alguien que explore tu trunk descubra qué trunks, números y destinos existen.
¿Dónde obtengo la documentación de seguridad y protección de datos de Bird?
Las certificaciones y la documentación de seguridad están en el Trust Center en trust.bird.com. El acuerdo de procesamiento de datos, la declaración de privacidad y la política de uso aceptable se publican en bird.com/legal. Para un cuestionario de proveedor, tu equipo de cuenta de Bird se encarga.