Crear una skill de Alexa con Firebase Functions, paso a paso

Vamos a construir una skill que cuente un relato y entienda «otro relato», «ayuda» y «parar». El código está preparado para probar la lógica en tu ordenador antes de conectar una cuenta de Amazon o un proyecto de Firebase.

El proyecto usa TypeScript, el SDK de Alexa y una función HTTP de Firebase. Los relatos incluidos son ficción de demostración, inspirada en talleres de imprenta y mapas. No son una fuente de historia documentada ni se generan automáticamente con IA.

Código: relatos-alexa-firebase en GitHub.

Qué hemos probado y qué falta

Se han ejecutado los handlers con el SDK real, las pruebas de respuestas y rechazos, y el simulador local en Chrome. Las capturas de este tutorial pertenecen a esa herramienta propia. No se ha creado una skill en Amazon ni desplegado una función: la conexión con el simulador oficial y la firma real de una petición de Alexa quedan para la instalación de cada lector. Las instrucciones de consola se han contrastado con documentación oficial, no con una sesión autenticada.

La parte local no necesita cuentas cloud. Para conectar Alexa necesitarás una cuenta de desarrollador de Amazon y un proyecto Firebase propio. Firebase exige plan Blaze para desplegar Functions; existen costes y cuotas según uso. Revisa la guía de despliegue y los precios antes de decidir. No necesitas contratar nada para seguir los primeros pasos.

1. Descarga el proyecto

En GitHub, pulsa Code → Download ZIP y descomprime el archivo. Abre la carpeta en tu editor. También puedes clonar el repositorio si utilizas Git habitualmente.

Esta guía es técnica y está dirigida a quien administra su propio proyecto. Necesitas Node.js 22 y npm. El runtime de Firebase está fijado a Node 22 en functions/package.json; comprueba los runtimes admitidos antes de desplegar en otra fecha.

2. Instala y ejecuta las pruebas

Abre una terminal en la carpeta que contiene el package.json principal:

npm ci
npm test

Se compila TypeScript y se ejecutan cinco pruebas. Comprueban, entre otras cosas, que Stop termina la sesión, que un almacén vacío responde de forma controlada y que el endpoint rechaza cuerpos sin firma, timestamps antiguos o IDs incorrectos.

No confundas este resultado con una certificación de Amazon. Son pruebas de nuestro código; la comunicación de extremo a extremo necesita un endpoint propio.

3. Prueba la conversación sin salir de tu equipo

npm run demo

Abre http://127.0.0.1:4415. Pulsa Abrir la skill: a la izquierda aparece el relato y a la derecha el JSON producido por el SDK. Pulsa Otro relato y después Parar.

Captura real del simulador propio. No es la consola de Alexa ni una captura de un altavoz.

El botón Parar debe mostrar «La sesión termina». En el JSON verás shouldEndSession: true. Esa es una comprobación visible y concreta del comportamiento.

4. Localiza las piezas del proyecto

Archivo	Para qué sirve
skill/interaction-model.es-ES.json	Las intenciones y frases que reconocerá Alexa.
functions/src/skill.ts	Decide qué respuesta corresponde a cada petición.
functions/src/stories.ts	Proporciona un relato de ejemplo o de Firestore.
functions/src/security.ts	Comprueba quién envía la petición y si es reciente.
functions/src/index.ts	Expone la función HTTP relatos.

El recorrido es sencillo: Alexa reconoce una intención, envía una petición firmada, la función la valida, el handler obtiene un relato y el SDK prepara la respuesta.

5. Crea la skill en la consola de Amazon

Si decides continuar con cuentas propias, abre la Alexa Developer Console. Crea una skill personalizada, con idioma Español (ES) y alojamiento propio del backend. La consola puede cambiar sus textos y opciones: la documentación de creación de skills es la referencia.

Ponle un nombre de proyecto que reconozcas. El nombre visible de la skill y la frase de invocación son conceptos distintos. El modelo incluido utiliza relatos de historia como invocación.

No la publiques todavía. Primero vamos a comprobar el modelo y el endpoint.

6. Importa el modelo de interacción

En Build, busca el editor JSON del modelo de interacción. Sustituye su contenido por el archivo skill/interaction-model.es-ES.json, guarda y construye el modelo.

Deberías encontrar StoryIntent y las intenciones integradas de ayuda, parar, cancelar y fallback. Dentro de StoryIntent hay frases como «cuéntame un relato» y «otro relato».

Si cambias el nombre de la intención, actualízalo también en skill.ts. Cambiar solo el texto de las frases de ejemplo no exige renombrar el handler.

7. Copia el ID de tu skill

Obtén el Skill ID de tu skill en la consola. Tiene el prefijo amzn1.ask.skill.. No copies el ID de un tutorial ni el valor ficticio de las pruebas.

En la carpeta functions, crea un archivo .env.TU_PROJECT_ID usando functions/.env.example como plantilla. Sustituye el sufijo por el ID real de tu proyecto Firebase y el valor por el ID de la skill:

ALEXA_SKILL_ID=amzn1.ask.skill.TU-ID-REAL
STORY_SOURCE=sample

Los archivos de entorno están excluidos de Git. El ID de skill no sustituye a una firma: el endpoint exige ambas comprobaciones. Consulta el uso de variables de entorno en Functions.

8. Prepara tu proyecto de Firebase

Usa un proyecto separado para la prueba. La edición incluye firebase.json, reglas de Firestore cerradas y la función; no necesitas ejecutar un asistente que sobrescriba estos archivos.

Con Firebase CLI instalada y autenticada en tu cuenta, selecciona el proyecto que has decidido utilizar. Puedes pasar su ID explícitamente en cada comando para reducir errores de destino.

La opción STORY_SOURCE=sample evita necesitar una base de datos para la primera conversación. No se incluye ninguna credencial de servicio ni debes descargar una para añadirla al repositorio.

9. Despliega solo la función de esta prueba

Haz este paso únicamente si ya has revisado el proyecto, el plan de facturación y los costes. La preparación de este tutorial no ha ejecutado este comando:

firebase deploy --only functions:relatos --project TU_PROJECT_ID

La CLI debe devolver una Function URL. Copia exactamente esa URL; no construyas una a mano ni reutilices la de otra persona. El endpoint tiene invocación pública para que Alexa pueda alcanzarlo, pero rechaza peticiones sin firma válida. Configura alertas de presupuesto en tu proyecto; una alerta no impide automáticamente el gasto.

minInstances: 0 evita reservar instancias calientes en esta configuración. maxInstances: 2 limita la escala de la función, pero no constituye un límite monetario total.

10. Configura el endpoint HTTPS en Alexa

Vuelve a Build → Endpoint, elige HTTPS y pega la URL de la función como endpoint de la región que corresponda. Selecciona la opción de certificado coherente con el certificado presentado por esa URL: de autoridad de confianza o de subdominio cubierto por un wildcard. No elijas un certificado autofirmado para un endpoint de Firebase gestionado.

Amazon exige un servicio accesible por HTTPS, certificado adecuado y validación de peticiones. La guía oficial de web services detalla las opciones de certificado y la validación. El cuerpo original se conserva para verificar la firma; no lo vuelvas a serializar antes de comprobarla.

11. Prueba en el simulador oficial

Activa el modo de pruebas de desarrollo de la skill y usa Español (ES). Prueba estas frases:

abre relatos de historia
otro relato
ayuda
parar

Comprueba el texto reconocido, la intención enviada y la respuesta. Después de Parar, la sesión debe terminar. Si dispones de un dispositivo compatible asociado a la cuenta de pruebas, puedes comprobar también la voz; esa prueba no se ha realizado en este tutorial.

Un curl sin firma contra el endpoint debe ser rechazado. No desactives la verificación para conseguir un 200: para probar sin Alexa ya existe npm run demo.

12. Añade tus propios relatos revisados

La vía más sencilla es editar examples en stories.ts, ejecutar las pruebas y volver a desplegar. Para una colección editable por el administrador puedes activar STORY_SOURCE=firestore.

En una base Firestore propia, un documento de la colección stories tiene esta forma:

{
  "title": "Un título propio",
  "text": "El relato revisado que tienes permiso para utilizar.",
  "published": true
}

La función solo lee documentos publicados y limita la consulta a 100. Las reglas incluidas no permiten acceso desde clientes web; Firebase Admin utiliza la identidad de ejecución y sus permisos IAM. Si añades Firestore, configura la base, revisa sus costes y despliega únicamente las reglas que correspondan a este proyecto de prueba. No sobrescribas reglas de una aplicación que ya esté en uso.

Para historia real, añade un proceso editorial con fuentes y revisión: ni el nombre de una skill ni una salida de IA convierten un relato en un hecho verificado.

Si algo falla

Síntoma	Qué comprobar
La demo local no abre	Que npm run demo siga activo y el puerto 4415 esté libre.
Respuesta 503 del endpoint	Que ALEXA_SKILL_ID esté configurado con el ID real y se haya vuelto a desplegar.
Respuesta 403	Que la petición pertenezca a la skill configurada.
Respuesta 400	Firma, cuerpo original y timestamp. No modifiques el cuerpo ni aceptes solicitudes antiguas.
Alexa no reconoce la frase	Idioma, invocación, modelo guardado y construido.
«Todavía no hay relatos»	Colección stories, published=true y campos válidos.
«No he podido leer el relato»	Configuración de Firestore y permisos de la identidad de ejecución.

Una mejora pequeña para empezar

Añade una intención que explique de dónde proceden los relatos. Antes de programar, escribe dos frases que podría decir la persona y la respuesta que debería escuchar. Después añade la intención al modelo, implementa el handler y crea una prueba.

Si utilizas una IA como ayuda, puedes copiar este prompt:

Revisa este proyecto de Alexa y Firebase Functions. Quiero añadir SourcesIntent,
con las frases «de dónde salen los relatos» y «qué fuentes utilizas».
Primero explícame qué archivos cambiarás. Mantén la verificación de firma,
timestamp e ID. No añadas servicios externos ni publiques nada. Incluye una
prueba del nuevo handler y distingue los relatos ficticios de contenido histórico.

Fuentes consultadas el 28 de septiembre de 2026: documentación oficial de Amazon y Firebase enlazada en cada paso. Los textos exactos de las consolas y las condiciones de servicio pueden cambiar; las capturas aquí mostradas corresponden exclusivamente a la prueba local realizada.