Bloque de Firebase, Firestore y Cloud Messaging en tu chatbot

Visión general

El bloque de Firebase conecta tu chatbot de ChatMaxima directamente con un proyecto de Firebase. Permite que tu flujo lea y escriba documentos en Cloud Firestore y envíe notificaciones push de FCM a los usuarios de tu app móvil o web, todo desde un único bloque. Cualquier operación que configures se ejecuta en el punto exacto de la conversación donde colocas el bloque, de modo que tu bot puede extraer datos de Firestore, almacenar el estado de vuelta en él o activar una notificación push en respuesta a un estado concreto de la conversación.

Los casos de uso habituales incluyen almacenar datos de leads en tus propias colecciones de Firestore, buscar el perfil de un usuario autenticado por su ID, comprobar el estado de un pedido o una reserva desde el backend de tu app y enviar notificaciones a los dispositivos de un usuario cuando la conversación alcanza un hito (pedido confirmado, cita reservada, ticket de soporte resuelto). El bloque gestiona la autenticación, el almacenamiento en caché de tokens y el enrutamiento de errores automáticamente, así que solo necesitas elegir una operación y completar los campos relevantes para ella.

Requisitos previos

Antes de añadir el bloque de Firebase a un flujo, asegúrate de tener:

• Un proyecto de Firebase con Cloud Firestore habilitado. Realtime Database no es compatible con este bloque (la v1 cubre solo Firestore).
• Una clave JSON de cuenta de servicio descargada de tu proyecto de Firebase. En la consola de Firebase ve a Configuración del proyecto, abre la pestaña Cuentas de servicio y haz clic en Generar nueva clave privada. Guarda el archivo JSON descargado. Pegarás su contenido en ChatMaxima en el siguiente paso.
• FCM configurado en tu app cliente si planeas enviar notificaciones push. Cada dispositivo debe estar registrado en Firebase y su token de registro de FCM almacenado en un lugar que el bot pueda obtener (normalmente un array users/{user_id}.tokens de Firestore).

Nota: La clave de cuenta de servicio es un secreto de larga duración. Trátala igual que tratarías una contraseña de base de datos de producción. No la subas al control de versiones ni la compartas en un chat.

Paso 1: Conecta Firebase como integración

1. Ve a Panel → Integraciones y haz clic en Añadir integración
2. Selecciona Firebase en el desplegable de plataformas
3. Introduce un nombre (por ejemplo, Production Firebase o My App Firestore) para reconocerlo después
4. Pega el contenido completo del archivo JSON de la cuenta de servicio en el campo JSON de la cuenta de servicio
5. Haz clic en Verificar y guardar

ChatMaxima valida la credencial firmando un JWT con la clave privada, intercambiándolo por un token de acceso de OAuth y haciendo una llamada de prueba al endpoint listCollectionIds de Firestore. Si el proyecto tiene Firestore habilitado y la cuenta de servicio tiene acceso, verás Integración de Firebase conectada. La integración queda ahora disponible para todos los bots de tu equipo.

Nota: El token de acceso se almacena en caché dentro de ChatMaxima y se renueva automáticamente antes de que expire. No necesitas rotar ni volver a introducir el JSON de la cuenta de servicio a menos que quieras pasar a un proyecto de Firebase diferente.

Paso 2: Añade el bloque de Firebase a un flujo

1. Abre tu chatbot en Studio
2. Haz clic con el botón derecho en el lienzo (o arrastra desde la barra lateral izquierda) y elige Firebase en Integraciones externas
3. Haz doble clic en el bloque para abrir su configuración
4. Selecciona la integración que creaste en el paso 1 en el desplegable Seleccionar integración
5. Elige una operación y completa los campos que se describen a continuación

Operaciones disponibles

El bloque de Firebase admite siete operaciones. Las primeras seis funcionan con Cloud Firestore. La séptima envía una notificación push de Cloud Messaging (FCM).

Operación	Categoría	Qué hace
Obtener documento	Firestore	Lee un solo documento por colección e ID de documento
Añadir documento	Firestore	Crea un nuevo documento. Firestore genera el ID automáticamente si lo dejas en blanco
Establecer documento	Firestore	Sobrescribe el documento de un ID específico. Reemplaza todos los campos
Actualizar documento	Firestore	Fusiona solo los campos que proporcionas en un documento existente
Eliminar documento	Firestore	Elimina un documento de un ID específico
Consultar colección	Firestore	Filtra, ordena y limita una colección de documentos
Enviar notificación	Cloud Messaging	Envía una notificación push a un dispositivo, a muchos o a un tema

Cada entrada (colección, ID de documento, valores de campo, token de FCM, título y cuerpo de la notificación) admite variables de ChatMaxima con la sintaxis {variable}, de modo que puedes completarlas desde bloques de pregunta anteriores, llamadas a la API previas o datos recibidos en un bloque de webhook.

Configuración de las operaciones

Obtener documento

Lee un documento por su ID. Úsalo para buscar el perfil de un usuario, obtener el estado actual de un pedido o extraer cualquier registro del que ya tengas el ID.

Campo	Descripción
Colección	Nombre de la colección de Firestore (por ejemplo, users, orders). Elige de la lista detectada o escribe uno nuevo
ID de documento	El ID a leer. Admite variables como {user_id}
Guardar la respuesta en la variable	Nombre de la variable de ChatMaxima que contiene el resultado

Añadir documento

Crea un nuevo documento en una colección. Deja ID de documento en blanco para que Firestore lo genere automáticamente, o proporciona el tuyo (por ejemplo, {lead_id}).

Campo	Descripción
Colección	Colección de destino
ID de documento (opcional)	Déjalo en blanco para un ID automático, o proporciona uno personalizado
Asignación de campos	Filas de clave/valor. Las claves son nombres de campo de Firestore, los valores pueden ser literales o referencias {variable}
Guardar la respuesta en la variable	El documento guardado (con su ID generado) se almacena aquí

Establecer documento

Sobrescribe el documento en collection/document_id con exactamente los campos que indicas. Cualquier campo que estuviera antes en el documento pero no en tu asignación se elimina. Úsalo cuando quieras un reemplazo limpio en lugar de una fusión.

Actualizar documento

Fusiona solo los campos que proporcionas en un documento existente. Los campos que no están en tu asignación quedan intactos. Es la operación de escritura más segura para actualizar de forma incremental el perfil de un usuario o un registro de pedido.

Eliminar documento

Elimina el documento en collection/document_id. La variable de respuesta contendrá {"success": true} si la eliminación tuvo éxito.

Consultar colección

Ejecuta una consulta estructurada de Firestore contra una colección. Admite filtros, orden y un límite de filas.

Campo	Descripción
Colección	Colección a consultar
Filtros de consulta	Filas de field, operator, value. Se combinan con AND
Campo de orden	Nombre de campo opcional por el que ordenar
Dirección del orden	Ascendente o descendente
Límite	Número máximo de documentos a devolver. Déjalo en blanco para no aplicar límite

Operadores de filtro admitidos:

Operador	Significado
EQUAL	El campo es igual al valor
NOT_EQUAL	El campo no es igual al valor
LESS_THAN	El campo es menor que el valor
LESS_THAN_OR_EQUAL	El campo es menor o igual que el valor
GREATER_THAN	El campo es mayor que el valor
GREATER_THAN_OR_EQUAL	El campo es mayor o igual que el valor
ARRAY_CONTAINS	El campo es un array que contiene el valor
IN	El valor del campo es uno de los valores listados
ARRAY_CONTAINS_ANY	El array del campo contiene cualquiera de los valores listados
NOT_IN	El valor del campo no es ninguno de los valores listados

Enviar notificación

Envía una notificación push de FCM. Elige uno de tres destinos:

Enviar a	Cuándo usarlo
Un solo dispositivo	Un token de registro de FCM específico
Varios dispositivos	Envío múltiple a muchos tokens en un solo paso. Acepta una variable que se resuelva en un array JSON, una cadena separada por comas o un array nativo
Un tema	Difusión a cada dispositivo suscrito a un tema (por ejemplo, premium-users)

Campos de configuración:

Campo	Descripción
Token / Tokens / Tema de FCM	El destinatario, según el tipo de destino. Admite variables
Título de la notificación	Titular en negrita que se muestra en la notificación push
Cuerpo de la notificación	Texto del mensaje que se muestra bajo el título
Carga de datos	Pares clave/valor opcionales entregados de forma silenciosa junto a la notificación. Útil para enlaces profundos (por ejemplo, screen=orders, order_id={order_id}). Los valores se convierten a cadena antes de enviarse, según las reglas de FCM

Formato de la variable de respuesta

Cada operación almacena un resultado JSON en la variable que nombras en Guardar la respuesta en la variable. Los bloques posteriores pueden referenciar campos con notación de puntos; por ejemplo, {user_data.data.email}.

Lecturas de Firestore (Obtener documento)

{
  "id": "user_42",
  "name": "projects/my-project/databases/(default)/documents/users/user_42",
  "data": {
    "name": "Priya",
    "email": "priya@example.com",
    "tokens": ["iphone_tok", "ipad_tok"]
  },
  "create_time": "2026-04-20T10:30:00Z",
  "update_time": "2026-04-21T14:15:00Z"
}

Escrituras de Firestore (Añadir / Establecer / Actualizar)

La misma forma que Obtener documento. El campo id refleja el ID final del documento (generado automáticamente si no proporcionaste uno).

Eliminación de Firestore

{ "success": true }

Consultar colección

Un array de objetos de documento, cada uno con la forma anterior:

[
  { "id": "order_1", "data": { "status": "confirmed", "amount": 900 }, "create_time": "..." },
  { "id": "order_2", "data": { "status": "confirmed", "amount": 1200 }, "create_time": "..." }
]

Enviar notificación (único / tema)

{
  "success": true,
  "message_name": "projects/my-project/messages/0:17045...",
  "target_type": "token",
  "target_value": "iphone_tok"
}

Enviar notificación (envío múltiple)

{
  "success": true,
  "sent": 2,
  "failed": 1,
  "invalid_tokens": ["stale_tok"],
  "results": [
    { "token": "iphone_tok", "success": true, "message_name": "..." },
    { "token": "ipad_tok",   "success": true, "message_name": "..." },
    { "token": "stale_tok",  "success": false, "error": "Requested entity was not found.", "error_code": "UNREGISTERED" }
  ]
}

El array invalid_tokens lista los tokens que Firebase marcó como obsoletos (UNREGISTERED, INVALID_ARGUMENT, NOT_FOUND). Usa un bloque de Firebase de seguimiento con Actualizar documento para depurarlos de tu propia colección users de Firestore y dejar de apuntar a dispositivos muertos.

Casos de uso comunes

Notificación push de confirmación de pedido

Un cliente completa la compra dentro de la app y quieres que el bot envíe una confirmación a cada dispositivo que el usuario tenga registrado.

1. Bloque de pregunta: captura o verifica {user_id}
2. Bloque de Firebase (Obtener documento): colección users, ID de documento {user_id}, guarda el resultado en {user_data}
3. Bloque de condición: ramifica según {order_status} == "confirmed"
4. Bloque de Firebase (Enviar notificación, varios dispositivos): tokens {user_data.data.tokens}, título Order confirmed, cuerpo Hi {user_data.data.name}, your order {order_id} is on its way
5. Bloque de mensaje: We have sent a confirmation to your devices

Escribir leads del chatbot en Firestore

Usa Firestore como fuente de verdad para los leads entrantes, de modo que tu propia app móvil pueda reaccionar en tiempo real.

1. Bloque de pregunta: pide {name}, {email}, {phone}
2. Bloque de Firebase (Añadir documento): colección chatbot_leads, campos name={name}, email={email}, phone={phone}, source=chatbot
3. Bloque de mensaje: Thanks {name}, we will be in touch shortly

Comprobar la disponibilidad de una reserva

Antes de confirmar una reserva, consulta Firestore para asegurarte de que la franja sigue libre.

1. Bloque de Firebase (Consultar colección): colección bookings, filtro slot_id EQUAL {slot_id} y status NOT_EQUAL cancelled, límite 1, guarda en {existing_bookings}
2. Bloque de condición: ramifica según si {existing_bookings} está vacío
3. Si está vacío: bloque de Firebase (Añadir documento) para crear la reserva, luego bloque de mensaje para confirmar
4. Si hay coincidencia: bloque de mensaje That slot was just taken, please pick another

Difundir a un tema

Envía un anuncio de uno a muchos a cada dispositivo suscrito a un tema.

1. Bloque de activación: un administrador activa el flujo con una campaña
2. Bloque de Firebase (Enviar notificación, tema): tema premium-users, título New feature released, cuerpo Tap to try it out, datos screen=whats_new

Limpiar tokens de FCM obsoletos

Tras un envío múltiple, elimina los tokens muertos del perfil del usuario para que los próximos envíos solo lleguen a dispositivos activos.

1. Bloque de Firebase (Enviar notificación, varios dispositivos): guarda el resultado en {push_result}
2. Bloque de condición: ramifica según si {push_result.invalid_tokens} no está vacío
3. Bloque de código o bloque de API: calcula la lista de tokens depurada
4. Bloque de Firebase (Actualizar documento): colección users, ID de documento {user_id}, campo tokens={pruned_tokens}

Buenas prácticas

• Limita el alcance de la cuenta de servicio adecuadamente. Crea una cuenta de servicio dedicada para ChatMaxima y otórgale solo los roles de Firestore y FCM que necesita. No uses la clave predeterminada del Admin SDK para producción
• Almacena los tokens de FCM como un array. Los usuarios suelen tener varios dispositivos. Mantenerlos en un único campo tokens por usuario hace que los envíos múltiples sean triviales
• Gestiona la rama de error. Cada bloque de Firebase tiene una segunda salida que se activa cuando la operación falla. Enrútala a un mensaje de recuperación o a un reintento, en lugar de dejar que el flujo se detenga
• Depura los tokens obsoletos. FCM devuelve UNREGISTERED cuando un token está muerto. Usa el campo invalid_tokens de la respuesta del envío múltiple para limpiar tus perfiles de usuario
• Mantén pequeños los valores de la carga de datos. FCM exige que todos los valores de la carga de datos sean cadenas y que el tamaño total del mensaje se mantenga por debajo de 4 KB. ChatMaxima convierte los valores a cadena automáticamente, pero los bloques JSON grandes serán rechazados por Firebase
• No filtres el JSON de la cuenta de servicio. Una vez guardado en ChatMaxima, el JSON no se vuelve a exponer en la interfaz. Trata el archivo descargado con el mismo cuidado que cualquier otro secreto de producción

Preguntas frecuentes

¿Qué productos de Firebase admite el bloque?

Cloud Firestore (lectura / escritura / consulta) y Cloud Messaging (API FCM HTTP v1). Realtime Database, Firebase Authentication, Cloud Functions e In-App Messaging no son gestionados por este bloque.

¿Puedo usar el mismo bloque para Firestore y FCM?

Sí. Una sola credencial de integración de Firebase autoriza ambos productos. Coloca bloques de Firebase separados para cada operación que necesites (por ejemplo, un bloque Obtener documento para buscar los tokens del usuario, y luego un bloque Enviar notificación para enviar a esos tokens).

¿Dónde se almacena mi JSON de cuenta de servicio?

Dentro de la tabla chatbot_integration_tokens, acotado a tu equipo. El JSON nunca se devuelve al navegador después de guardarlo. ChatMaxima lo usa del lado del servidor para generar tokens de acceso de OAuth de corta duración para Firebase.

¿Por qué llega la notificación pero falta la carga de datos?

FCM exige que los valores de la carga de datos sean cadenas. Si pasas directamente una variable numérica o booleana, ChatMaxima la convierte a cadena por ti, pero algunas apps cliente esperan formatos específicos. Vuelve a comprobar cómo lee tu app RemoteMessage.getData() en Android o userInfo en iOS.

Mi envío múltiple muestra que algunos tokens fallaron. ¿Qué hago?

Mira el array invalid_tokens en la variable de respuesta. Son tokens que Firebase considera muertos. Usa un bloque Actualizar documento para eliminarlos del array tokens del usuario en Firestore y que no se vuelvan a usar.

¿Puede el bloque enviar a un ID de usuario en lugar de a un token de FCM?

No directamente. FCM direcciona los dispositivos por token de registro, no por usuario. El patrón habitual es: almacenar los tokens del usuario en Firestore bajo users/{user_id}, usar un bloque Obtener documento para obtenerlos y luego pasar el array de tokens al bloque Enviar notificación.

¿Puedo consultar subcolecciones?

El bloque actual consulta colecciones de nivel superior. Las consultas anidadas o de subcolecciones (por ejemplo, users/{uid}/orders) están en la hoja de ruta. Como solución temporal, almacena datos desnormalizados en una colección de nivel superior con la clave del ID de usuario.

¿Cómo pruebo el bloque antes de ponerlo en producción?

Crea un proyecto de Firebase de pruebas con unos pocos documentos de prueba. Conéctalo como una integración de ChatMaxima separada, apunta el bloque a él y ejecuta el flujo desde el modo Vista previa en Studio. Cambia el bloque a la integración de producción cuando estés conforme.

Solución de problemas

Verificar y guardar falla con "Credencial rechazada por Firestore"

1. Abre tu proyecto de Firebase y confirma que Cloud Firestore está habilitado (Consola → Firestore Database)
2. Comprueba que la cuenta de servicio tiene al menos el rol Usuario de Cloud Datastore (IAM → Cuentas de servicio)
3. Asegúrate de haber pegado el archivo JSON completo, incluido el campo private_key con los escapes de salto de línea \n intactos
4. Vuelve a generar la clave privada si el archivo original fue editado o copiado parcialmente

El bloque muestra "Integración de Firebase no encontrada"

1. Confirma que la integración existe en Panel → Integraciones y está activa
2. Si creaste la integración recientemente, actualiza el modal del bloque con el botón de actualizar junto al desplegable de integraciones
3. Elimina y vuelve a crear la integración si la credencial se rotó en Firebase

Firestore devuelve "Documento no encontrado" (404)

1. Verifica que el nombre de la colección está escrito exactamente como aparece en Firebase (sensible a mayúsculas)
2. Comprueba el ID del documento. Si proviene de una variable, inspecciona el registro de la conversación para ver el valor real que se sustituye
3. Recuerda que Firestore trata un documento ausente de forma distinta a uno vacío. El bloque devuelve not_found: true en la variable de respuesta para que puedas ramificar según ello

La notificación de FCM no llega al dispositivo

1. Confirma que el token de FCM es válido. Los tokens expiran cuando la app se desinstala o se reinstala
2. Comprueba que el dispositivo tiene concedidos los permisos de notificación para tu app
3. Inspecciona la variable de respuesta. Un envío exitoso devuelve message_name. Un fallo devuelve error y, a menudo, un error_code como UNREGISTERED
4. Verifica que el dispositivo no está en modo de ahorro de batería ni bloqueado por el modo No molestar del sistema

El envío al tema tiene éxito pero nadie lo recibe

1. La entrega a temas es de mejor esfuerzo y puede tardar hasta un minuto
2. Confirma que los dispositivos están realmente suscritos al tema (messaging().subscribeToTopic('premium-users') en el cliente)
3. Los nombres de tema son sensibles a mayúsculas y no pueden empezar por /topics/ en la API v1. Usa solo el nombre; por ejemplo, premium-users

La variable de respuesta está vacía

1. Asegúrate de haber completado el campo Guardar la respuesta en la variable del bloque
2. Comprueba que el nombre de la variable no choca con una palabra clave reservada ni con la variable de otro bloque
3. Inspecciona el registro de la conversación para ver el resultado sin procesar de la llamada a Firebase

Próximos pasos

• Bloque de API: llama a cualquier API REST externa desde tu flujo
• Bloque de webhook: recibe llamadas HTTP entrantes en tu flujo
• Bloque de condición: ramifica el flujo según los valores de las variables
• Visión general de Studio: explora todos los tipos de bloque y las funciones del constructor de flujos