Twilio ya te dice en la API con qué atestación STIR/SHAKEN salió cada llamada: así lo aprovecha tu agente de voz

Twilio anunció el 5 de noviembre en su changelog que el recurso Call de su Voice API ahora devuelve el estado STIR/SHAKEN de cada llamada en un campo nuevo, stir_verstat. Suena a detalle de letra chiquita, pero no lo es si tienes un agente de voz con IA, un sistema de recordatorios o un marcador de ventas que llama a teléfonos en Estados Unidos: la atestación STIR/SHAKEN es lo que los operadores usan para decidir si tu identificador de llamada es confiable o si tu número termina con la etiqueta de "posible spam" en la pantalla de quien recibe. Hasta ahora, para saberlo había que capturar los webhooks en el momento. Ahora se puede consultar después, llamada por llamada o en lote, desde la misma API que ya usas.

Qué anunció Twilio exactamente

El aviso es corto y está marcado como disponible para todos (GA) en Voice API. Dice tres cosas:

• El recurso Call devuelve el estado STIR/SHAKEN de cada llamada en la propiedad stir_verstat.
• Aparece cuando consultas una llamada o lees una lista de llamadas, y está integrado en los SDK de servidor de Twilio.
• El uso que propone Twilio: confirmar que tus llamadas llevan atestación A y encontrar las que se firmaron con B o C para corregirlas.

En la referencia del recurso Call, el campo aparece como texto, con un ejemplo como TN-Validation-Passed-A, y la nota de que viene vacío si la llamada no traía información STIR/SHAKEN. Todos los ejemplos de respuesta de esa página ya lo incluyen.

STIR/SHAKEN en dos minutos

Según la guía de Twilio sobre llamadas confiables, STIR (Secure Telephone Identity Revisited) es un protocolo del IETF para autenticar llamadas de extremo a extremo, y SHAKEN es la especificación de ATIS que aterriza ese protocolo para que los operadores puedan verificarse entre sí. Juntos sirven para combatir la suplantación del identificador de llamada: el operador que origina la llamada la firma con criptografía y el que la termina puede comprobar que nadie la alteró en el camino. Twilio dice que hoy firma todas sus llamadas de Estados Unidos con la atestación que corresponde para cumplir con sus obligaciones bajo la TRACED Act, la ley estadounidense contra las llamadas automáticas fraudulentas.

La firma lleva un nivel de atestación:

• A: el operador conoce al cliente y sabe que tiene derecho a usar ese número como identificador.
• B: el cliente es conocido, pero no consta que tenga derecho a usar ese número.
• C: no cumple ni A ni B; aquí entran, por ejemplo, las llamadas internacionales.

Twilio aclara un dato que importa mucho a quien lee esto desde México: su soporte de STIR/SHAKEN solo está desplegado en Estados Unidos y Francia. Si tu bot de voz llama a números mexicanos con números mexicanos, este campo no te va a decir gran cosa. Si llamas a Estados Unidos, por ejemplo para clientes allá o con números de Twilio de ese país, sí.

Cómo consigues una A (y por qué a veces sale B o C)

La guía de onboarding explica qué decide el nivel con el que Twilio firma tus llamadas salientes:

• A: Business Profile aprobado, un Trust Product de SHAKEN/STIR aprobado y ligado a ese perfil, y el número asignado a ambos. Solo las llamadas que salen de esos números asignados se firman con A.
• B: como mínimo, un Business Profile primario aprobado y un Trust Product de SHAKEN/STIR ligado a la cuenta padre. No hace falta asignar números. Además, B es lo máximo posible si usas números que no son de Twilio, porque Twilio no puede dar fe de que tengas derecho a usarlos.
• C: sin perfiles aprobados, o con perfiles rechazados.

El equipo de cumplimiento de Twilio tarda hasta 24 horas en revisar el Business Profile y hasta 72 horas en revisar el Trust Product de SHAKEN/STIR, según esa misma guía. Y aquí está el error típico: aprobar el perfil y olvidar asignar un número nuevo. Ese número sigue saliendo con B y nadie se entera hasta que baja la tasa de respuesta.

Qué valores puede traer stir_verstat

La guía de Twilio enumera los valores posibles, que se comparten con el parámetro StirVerstat de los webhooks y el encabezado X-Twilio-VerStat de Elastic SIP Trunking:

Un matiz: la descripción del campo en la referencia de la API habla de la llamada entrante ("vacío si la llamada entrante no tenía información STIR/SHAKEN"), mientras que el changelog lo presenta como la forma de revisar la atestación de tus llamadas. Mi lectura es que el campo refleja el estado STIR/SHAKEN que Twilio tiene registrado para cada pierna de la llamada, pero la documentación no lo deja del todo claro para cada dirección. Antes de construir alertas encima, conviene ver qué devuelve en tus propias llamadas salientes y entrantes.

Cómo usarlo en un bot de voz

No lo probé; esto sale de la documentación oficial de Twilio. El campo viene en la respuesta de siempre:

GET https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Calls/{CallSid}.json

{
  "sid": "CA…",
  "status": "completed",
  "direction": "outbound-api",
  "stir_verstat": "TN-Validation-Passed-A"
}

Tres usos que se me ocurren para quien opera bots y agentes de voz:

1. Auditoría diaria. Lee la lista de llamadas del día y cuenta cuántas salieron con A, B, C o sin dato. Si aparece B en un número que debería tener A, casi seguro le falta asignarse al Business Profile y al Trust Product.
2. Correlación con resultados. Cruza stir_verstat con status (no-answer, busy, completed) y con answered_by si usas detección de contestadora. Si las llamadas con B o C se contestan menos, ya tienes el argumento con datos para hacer el trámite de A.
3. Decisiones en llamadas entrantes. Para la llamada entrante, Twilio ya mandaba StirVerstat en el webhook, y su guía sugiere usarlo para mostrar un indicador de confianza o para decidir la ruta, por ejemplo saltarse un IVR o una verificación si la llamada viene con A. Ahora ese mismo dato queda guardado en el recurso Call, así que tu bot puede revisarlo después sin haberlo guardado en su momento.

Si ya escuchabas los status callbacks, Twilio también manda StirStatus con valores A, B, C o nulo en los eventos ringing e in-progress. El campo nuevo no lo reemplaza: lo complementa con algo que puedes consultar cuando quieras.

Lo que esto significa

Mi lectura: el valor real está en la observabilidad. La atestación siempre existió, pero vivía en un webhook que muchos no guardaban, así que el diagnóstico de "nadie contesta mis llamadas" se quedaba en suposiciones. La propia Twilio dice en su guía que, para agentes de IA y notificaciones automáticas, una atestación alta ayuda a que no te filtren los algoritmos de seguridad de los operadores ni te marquen como spam. Con stir_verstat en la API, ya puedes medirlo en lugar de suponerlo.

Para el público de osky.dj en México hay que repetir el asterisco: esto aplica a llamadas que pasan por la red de Estados Unidos (o Francia). Si tu operación es local, el campo te sirve sobre todo para entender cómo se ven tus llamadas cuando cruzan la frontera.

Fuentes

• Twilio Changelog: Voice API Call resource now returns STIR/SHAKEN status
• Twilio Docs: Call resource
• Twilio Docs: Trusted calling with SHAKEN/STIR
• Twilio Docs: SHAKEN/STIR Onboarding