Guía de instalación Agency Phone FiveM 2026

Esta guía te acompaña paso a paso en la instalación y configuración de Agency Phone en tu servidor FiveM. Ya sea que uses QBCore, ESX o un framework completamente personalizado, aquí encontrarás todo lo que necesitas: desde los requisitos previos hasta el primer arranque y el ajuste fino del archivo de configuración. Para la referencia técnica completa, consulta la documentación oficial en docs.agencyg.de/phone.

Requisitos previos

Antes de instalar Agency Phone, asegúrate de que tu entorno de servidor cumple los siguientes requisitos:

• Artifact de FiveM: versión 6633 o superior (recomendado: mantén siempre los artifacts actualizados)
• Base de datos: MySQL 5.7+ o MariaDB 10.3+, con oxmysql (recomendado) o mysql-async instalado y configurado
• CFX Keymaster: la clave de licencia de tu servidor debe estar registrada y activa en keymaster.fivem.net
• Framework (opcional): QBCore o ESX si deseas una integración más profunda. No es necesario para el funcionamiento en modo standalone.
• Compra activa de Agency Phone: el recurso se entrega a través del portal de assets de CFX tras la compra

Paso 1 — Compra y descarga

Tras completar tu compra en la tienda de Agency Scripts, tu licencia queda registrada automáticamente en tu cuenta CFX. Para descargar el recurso:

1. Inicia sesión en keymaster.fivem.net con la cuenta CFX vinculada a tu compra.
2. Ve a Granted Assets y localiza agency-phone.
3. Haz clic en Download para obtener el archivo zip de la última versión.
4. Si adquiriste el bridge de QBCore o ESX, descarga también agency-phone-bridge-qb o agency-phone-bridge-esx desde la misma lista.

Paso 2 — Estructura de carpetas

Extrae el archivo zip. Tu directorio resources debería verse así tras la extracción:

resources/
  [agency]/
    agency-phone/
      client/
      server/
      html/
      config.lua
      fxmanifest.lua
    agency-phone-bridge-qb/   (solo QBCore)
      client/
      server/
      fxmanifest.lua

La carpeta [agency] es una carpeta de categoría (los corchetes indican a FiveM que se trata de un grupo de recursos). No es estrictamente obligatoria — puedes colocar agency-phone directamente en resources/ — pero usar carpetas de categoría mantiene todo organizado.

Paso 3 — Configuración de la base de datos

Agency Phone crea sus propias tablas de base de datos en el primer inicio gracias al sistema de migración automática integrado en oxmysql. No necesitas importar ningún archivo SQL manualmente. Simplemente asegúrate de que la conexión a tu base de datos está configurada en server.cfg:

# server.cfg — cadena de conexión a la base de datos (ejemplo oxmysql)
set mysql_connection_string "mysql://user:password@localhost/fivem_db?charset=utf8mb4"

En el primer inicio del servidor, Agency Phone creará las siguientes tablas: phone_contacts, phone_messages, phone_calls, phone_gallery, phone_social_posts y phone_settings. Si usas una base de datos limpia, las tablas se crearán automáticamente. Si estás migrando desde otro script de teléfono, verifica que no haya conflictos de nombres en tu esquema existente.

Paso 4 — Entradas en server.cfg

Añade las siguientes líneas ensure a tu server.cfg. El orden importa — oxmysql debe cargarse antes que Agency Phone:

# Dependencias
ensure oxmysql

# Agency Phone (standalone o con bridge de framework)
ensure agency-phone

# Añadir solo si usas el bridge de QBCore:
# ensure qb-core
# ensure agency-phone-bridge-qb

# Añadir solo si usas el bridge de ESX:
# ensure es_extended
# ensure agency-phone-bridge-esx

Si usas QBCore o ESX, asegúrate de que el propio framework se cargue antes que el recurso bridge, como se indica en los comentarios anteriores. El núcleo standalone (agency-phone) siempre debe cargarse antes que cualquier recurso bridge.

Paso 5 — Configuración (config.lua)

Abre agency-phone/config.lua en un editor de texto. Este es el archivo de configuración principal que controla prácticamente todos los aspectos del comportamiento del teléfono. A continuación, un recorrido detallado por los ajustes más importantes:

Config = {}

-- ============================================================
-- FRAMEWORK
-- "standalone" | "qbcore" | "esx"
-- ============================================================
Config.Framework = "standalone"

-- ============================================================
-- NÚMEROS DE TELÉFONO
-- ============================================================
-- Formato de números generados automáticamente. X = dígito aleatorio.
Config.PhoneNumberFormat = "555-XXXX"

-- Permitir que los jugadores paguen moneda del juego para cambiar su número
Config.AllowNumberChange = true
Config.NumberChangeCost   = 500  -- moneda por defecto (ajustar según framework)

-- ============================================================
-- APLICACIONES: activar/desactivar cada app individualmente
-- ============================================================
Config.EnableBankingApp   = true
Config.EnableSocialApp    = true
Config.EnableGPSApp       = true
Config.EnableCameraApp    = true
Config.EnableMDT          = false   -- poner true solo para servidores LEO
Config.EnableNotesApp     = true

-- ============================================================
-- MDT (relevante solo cuando Config.EnableMDT = true)
-- ============================================================
-- Trabajos que pueden acceder a la app MDT
Config.MDTJobs = { "police", "sheriff", "highway_patrol" }

-- ============================================================
-- REDES SOCIALES
-- ============================================================
-- Renombrar la app social para que coincida con el lore de tu servidor
Config.SocialAppName = "Chirper"
-- Longitud máxima de una publicación en caracteres
Config.SocialPostMaxLength = 280

-- ============================================================
-- MENSAJERÍA CIFRADA
-- Requiere que el jugador tenga un objeto específico en el inventario
-- ============================================================
Config.EncryptedChat     = false
Config.EncryptedChatItem = "burner_phone"

-- ============================================================
-- INTERFAZ DE USUARIO
-- ============================================================
-- Tema por defecto: "dark" o "light"
Config.DefaultTheme = "dark"
-- Duración de visualización de notificaciones en milisegundos
Config.NotificationDuration = 5000
-- Tecla para abrir el teléfono (nombre de tecla de FiveM)
Config.PhoneKey = "F1"

Notas específicas de QBCore

Al usar el bridge de QBCore (Config.Framework = "qbcore"), la aplicación bancaria extrae automáticamente el saldo y los datos de transacciones de la economía QBCore. Los permisos de aplicación basados en el trabajo (como el acceso al MDT) utilizan el sistema de trabajos nativo de QBCore — no se necesita configuración adicional más allá de añadir los nombres de trabajos a Config.MDTJobs. Los números de teléfono se almacenan por personaje y están vinculados al identificador de personaje de QBCore.

Notas específicas de ESX

Con el bridge de ESX (Config.Framework = "esx"), la aplicación bancaria se conecta a las cuentas de ESX (por defecto: bank). Si tu configuración de ESX utiliza nombres de cuenta personalizados, configúralos en el propio archivo config.lua del bridge. Los rangos de trabajo de ESX se respetan para el acceso al MDT — solo necesitas listar los nombres de trabajos; todos los grados dentro de ese trabajo obtienen acceso automáticamente, a menos que configures restricciones de grado en la configuración del bridge.

Paso 6 — Verificación del primer inicio

Inicia tu servidor y observa la salida de la consola. Una carga exitosa de Agency Phone tiene este aspecto:

[agency-phone] Database tables verified/created — OK
[agency-phone] Framework: standalone
[agency-phone] Loaded 0 contacts, 0 messages (fresh install)
[agency-phone] Resource started successfully — v2.x.x

Si ves errores en esta etapa, consulta la sección de solución de problemas a continuación. Una vez que el servidor esté en marcha, conéctate con un cliente y pulsa F1 (o la tecla que hayas configurado) para abrir el teléfono. En el primer uso, el teléfono le pedirá al jugador que configure su número si aún no tiene uno asignado.

Errores comunes y soluciones

Error: «oxmysql is not started»

Esto significa que oxmysql no se está cargando antes que agency-phone en tu server.cfg. Mueve la línea ensure oxmysql por encima de ensure agency-phone y reinicia el servidor.

Error: «Failed to create table phone_contacts — Table already exists»

Esto es una advertencia, no un error fatal — significa que estás reinstalando sobre una base de datos existente. Los datos existentes se conservan. Puedes ignorar esta advertencia con seguridad. Si deseas una instalación limpia, elimina manualmente las tablas phone_* de tu base de datos primero.

La interfaz del teléfono no se abre al pulsar la tecla

Primero, verifica que el recurso se haya iniciado sin errores en la consola del servidor. Segundo, comprueba que ningún otro recurso esté usando el mismo atajo de teclado (por defecto: F1). Puedes cambiar el atajo en config.lua bajo Config.PhoneKey. Tercero, revisa los conflictos de foco NUI — si otro recurso está capturando el foco NUI al mismo tiempo, el teléfono puede no recibir correctamente la pulsación de tecla.

La aplicación bancaria muestra $0 / saldo vacío

Si estás en modo standalone, la aplicación bancaria utiliza un monedero interno por defecto. Para conectarla a la economía de QBCore o ESX, debes usar el recurso bridge correspondiente y establecer Config.Framework correctamente. Si el bridge está cargado pero el saldo sigue mostrando cero, verifica que el personaje del jugador esté completamente cargado en el framework antes de que el teléfono se inicialice (orden de carga en server.cfg).

La aplicación MDT no es visible para los agentes de policía

Confirma que Config.EnableMDT = true en config.lua y que el nombre del trabajo actual del jugador coincide exactamente con una de las entradas en Config.MDTJobs. La coincidencia de nombres de trabajos distingue entre mayúsculas y minúsculas. Usa exactamente la cadena de nombre de trabajo tal como está definida en la configuración de trabajos de tu framework.

Opciones de configuración adicionales

Agency Phone tiene muchas más opciones de configuración más allá de lo que se cubre en esta guía. Algunos de los ajustes avanzados más útiles incluyen:

• Config.MaxContactsPerPlayer — limita el número de contactos que un jugador puede almacenar (por defecto: ilimitado)
• Config.GPSUpdateInterval — con qué frecuencia se actualiza el blip de ubicación del jugador en el GPS compartido (en milisegundos)
• Config.SocialPostCooldown — tiempo mínimo entre publicaciones en redes sociales para evitar spam (en segundos)
• Config.AllowAnonCalls — si los jugadores pueden realizar llamadas ocultando su número al destinatario
• Config.CameraPhotoQuality — nivel de calidad de las capturas NUI (1 a 10, afecta al tamaño de las imágenes en la galería del juego)

El archivo de configuración completo y anotado con todas las opciones está disponible en la documentación oficial en docs.agencyg.de/phone. La documentación se actualiza con cada versión e incluye notas de migración específicas cuando cambian los ajustes.

Mantener Agency Phone actualizado

Cuando se publica una nueva versión, recibirás una notificación en tu cuenta de CFX Keymaster. Para actualizar, descarga el nuevo archivo zip desde la página Granted Assets, extráelo y reemplaza la carpeta agency-phone existente en tu servidor. Lee siempre el registro de cambios antes de actualizar en un servidor en producción — enumera los cambios en las claves de config.lua que requieren tu atención. Tu base de datos y los datos existentes de los jugadores nunca se eliminan con una actualización.