Guide d'installation Agency Phone FiveM 2026

Ce guide vous accompagne pas à pas dans l'installation et la configuration d'Agency Phone sur votre serveur FiveM. Que vous utilisiez QBCore, ESX ou un framework entièrement personnalisé, vous trouverez ici tout ce dont vous avez besoin — des prérequis au premier démarrage, en passant par le réglage fin du fichier de configuration. Pour la référence technique complète, consultez la documentation officielle sur docs.agencyg.de/phone.

Prérequis

Avant d'installer Agency Phone, assurez-vous que votre environnement serveur répond aux exigences suivantes :

• Artifact FiveM : version 6633 ou supérieure (recommandé : maintenez toujours vos artifacts à jour)
• Base de données : MySQL 5.7+ ou MariaDB 10.3+, avec oxmysql (recommandé) ou mysql-async installé et configuré
• CFX Keymaster : la clé de licence de votre serveur doit être enregistrée et active sur keymaster.fivem.net
• Framework (optionnel) : QBCore ou ESX si vous souhaitez une intégration approfondie. Non requis pour le fonctionnement en mode standalone.
• Achat Agency Phone actif : la ressource est fournie via le portail d'assets CFX après l'achat

Étape 1 — Achat et téléchargement

Après avoir finalisé votre achat sur la boutique Agency Scripts, votre licence est automatiquement enregistrée dans votre compte CFX. Pour télécharger la ressource :

1. Connectez-vous sur keymaster.fivem.net avec le compte CFX associé à votre achat.
2. Rendez-vous dans Granted Assets et recherchez agency-phone.
3. Cliquez sur Download pour obtenir l'archive zip de la dernière version.
4. Si vous avez acheté le bridge QBCore ou ESX, téléchargez également agency-phone-bridge-qb ou agency-phone-bridge-esx depuis la même liste.

Étape 2 — Structure des dossiers

Extrayez le ou les fichiers zip. Votre répertoire resources doit ressembler à ceci après extraction :

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

Le dossier [agency] est un dossier de catégorie (les crochets indiquent à FiveM qu'il s'agit d'un groupe de ressources). Ce n'est pas strictement obligatoire — vous pouvez placer agency-phone directement dans resources/ — mais l'utilisation de dossiers de catégorie facilite l'organisation.

Étape 3 — Configuration de la base de données

Agency Phone crée ses propres tables de base de données au premier lancement grâce au système de migration automatique intégré à oxmysql. Vous n'avez pas besoin d'importer manuellement de fichiers SQL. Assurez-vous simplement que la connexion à votre base de données est correctement configurée dans server.cfg :

# server.cfg — chaîne de connexion à la base de données (exemple oxmysql)
set mysql_connection_string "mysql://user:password@localhost/fivem_db?charset=utf8mb4"

Au premier démarrage du serveur, Agency Phone créera les tables suivantes : phone_contacts, phone_messages, phone_calls, phone_gallery, phone_social_posts et phone_settings. Si vous utilisez une base de données vierge, les tables seront créées automatiquement. Si vous migrez depuis un autre script téléphonique, vérifiez qu'il n'y a pas de conflits de noms dans votre schéma existant.

Étape 4 — Entrées dans server.cfg

Ajoutez les lignes ensure suivantes à votre server.cfg. L'ordre est important — oxmysql doit se charger avant Agency Phone :

# Dépendances
ensure oxmysql

# Agency Phone (standalone ou avec bridge framework)
ensure agency-phone

# Ajoutez uniquement si vous utilisez le bridge QBCore :
# ensure qb-core
# ensure agency-phone-bridge-qb

# Ajoutez uniquement si vous utilisez le bridge ESX :
# ensure es_extended
# ensure agency-phone-bridge-esx

Si vous utilisez QBCore ou ESX, assurez-vous que le framework lui-même se charge avant la ressource bridge, comme indiqué dans les commentaires ci-dessus. Le cœur standalone (agency-phone) doit toujours être chargé avant toute ressource bridge.

Étape 5 — Configuration (config.lua)

Ouvrez agency-phone/config.lua dans un éditeur de texte. C'est le fichier de configuration principal qui contrôle presque tous les aspects du comportement du téléphone. Voici un guide détaillé des paramètres les plus importants :

Config = {}

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

-- ============================================================
-- NUMÉROS DE TÉLÉPHONE
-- ============================================================
-- Format des numéros générés automatiquement. X = chiffre aléatoire.
Config.PhoneNumberFormat = "555-XXXX"

-- Autoriser les joueurs à payer en monnaie in-game pour changer de numéro
Config.AllowNumberChange = true
Config.NumberChangeCost   = 500  -- monnaie par défaut (à ajuster selon le framework)

-- ============================================================
-- APPLICATIONS : activer/désactiver chaque app individuellement
-- ============================================================
Config.EnableBankingApp   = true
Config.EnableSocialApp    = true
Config.EnableGPSApp       = true
Config.EnableCameraApp    = true
Config.EnableMDT          = false   -- mettre true uniquement pour les serveurs LEO
Config.EnableNotesApp     = true

-- ============================================================
-- MDT (pertinent uniquement si Config.EnableMDT = true)
-- ============================================================
-- Métiers ayant accès à l'app MDT
Config.MDTJobs = { "police", "sheriff", "highway_patrol" }

-- ============================================================
-- RÉSEAU SOCIAL
-- ============================================================
-- Renommer l'app sociale pour correspondre au lore de votre serveur
Config.SocialAppName = "Chirper"
-- Longueur maximale d'un post en caractères
Config.SocialPostMaxLength = 280

-- ============================================================
-- MESSAGERIE CHIFFRÉE
-- Nécessite que le joueur possède un objet spécifique dans l'inventaire
-- ============================================================
Config.EncryptedChat     = false
Config.EncryptedChatItem = "burner_phone"

-- ============================================================
-- INTERFACE UTILISATEUR
-- ============================================================
-- Thème par défaut : "dark" ou "light"
Config.DefaultTheme = "dark"
-- Durée d'affichage des notifications en millisecondes
Config.NotificationDuration = 5000
-- Touche pour ouvrir le téléphone (nom de touche FiveM)
Config.PhoneKey = "F1"

Notes spécifiques à QBCore

Lorsque vous utilisez le bridge QBCore (Config.Framework = "qbcore"), l'application bancaire récupère automatiquement le solde et les données de transaction depuis l'économie QBCore. Les autorisations d'application basées sur le métier (comme l'accès au MDT) utilisent le système de métiers natif de QBCore — aucune configuration supplémentaire n'est nécessaire au-delà de l'ajout des noms de métiers dans Config.MDTJobs. Les numéros de téléphone sont stockés par personnage et liés à l'identifiant de personnage QBCore.

Notes spécifiques à ESX

Avec le bridge ESX (Config.Framework = "esx"), l'application bancaire se connecte aux comptes ESX (par défaut : bank). Si votre configuration ESX utilise des noms de comptes personnalisés, configurez-les dans le propre fichier config.lua du bridge. Les grades de métier ESX sont pris en compte pour l'accès au MDT — seuls les noms de métiers doivent être listés ; tous les grades de ce métier obtiennent l'accès automatiquement, sauf si vous configurez des restrictions de grade dans la configuration du bridge.

Étape 6 — Vérification du premier démarrage

Démarrez votre serveur et observez la sortie de la console. Un chargement réussi d'Agency Phone ressemble à ceci :

[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 vous observez des erreurs à cette étape, consultez la section de dépannage ci-dessous. Une fois le serveur démarré, connectez-vous avec un client et appuyez sur F1 (ou la touche que vous avez configurée) pour ouvrir le téléphone. Lors de la première utilisation, le téléphone invite le joueur à définir son numéro s'il n'en a pas encore un d'attribué.

Erreurs courantes et solutions

Erreur : « oxmysql is not started »

Cela signifie qu'oxmysql n'est pas chargé avant agency-phone dans votre server.cfg. Déplacez la ligne ensure oxmysql au-dessus de ensure agency-phone et redémarrez le serveur.

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

Il s'agit d'un avertissement, pas d'une erreur fatale — cela signifie que vous réinstallez sur une base de données existante. Les données existantes sont préservées. Vous pouvez ignorer cet avertissement en toute sécurité. Si vous souhaitez une installation propre, supprimez manuellement les tables phone_* dans votre base de données au préalable.

L'interface du téléphone ne s'ouvre pas lors de l'appui sur la touche

Vérifiez d'abord que la ressource a démarré sans erreur dans la console serveur. Ensuite, assurez-vous qu'aucune autre ressource n'utilise le même raccourci clavier (par défaut : F1). Vous pouvez changer le raccourci dans config.lua sous Config.PhoneKey. Vérifiez également les conflits de focus NUI — si une autre ressource capture le focus NUI au même moment, le téléphone peut ne pas recevoir correctement la pression de touche.

L'application bancaire affiche 0 $ / solde vide

Si vous utilisez le mode standalone, l'application bancaire utilise un portefeuille interne par défaut. Pour la connecter à l'économie QBCore ou ESX, vous devez utiliser la ressource bridge correspondante et définir correctement Config.Framework. Si le bridge est chargé mais que le solde reste à zéro, vérifiez que le personnage du joueur est entièrement chargé dans le framework avant l'initialisation du téléphone (vérifiez l'ordre de chargement dans server.cfg).

L'application MDT n'est pas visible pour les officiers de police

Confirmez que Config.EnableMDT = true dans config.lua et que le nom du métier actuel du joueur correspond exactement à l'une des entrées de Config.MDTJobs. La correspondance des noms de métiers est sensible à la casse. Utilisez exactement la chaîne de nom de métier telle que définie dans la configuration des métiers de votre framework.

Options de configuration supplémentaires

Agency Phone dispose de nombreuses autres options de configuration au-delà de ce qui est couvert dans ce guide. Parmi les paramètres avancés les plus utiles :

• Config.MaxContactsPerPlayer — limite le nombre de contacts qu'un joueur peut stocker (par défaut : illimité)
• Config.GPSUpdateInterval — fréquence de mise à jour du blip de position du joueur sur le GPS partagé (en millisecondes)
• Config.SocialPostCooldown — délai minimum entre les publications sur les réseaux sociaux pour éviter le spam (en secondes)
• Config.AllowAnonCalls — permet aux joueurs de passer des appels en masquant leur numéro au destinataire
• Config.CameraPhotoQuality — niveau de qualité des captures NUI (1 à 10, affecte la taille des images dans la galerie in-game)

Le fichier de configuration complet et annoté avec toutes les options est disponible dans la documentation officielle sur docs.agencyg.de/phone. La documentation est mise à jour à chaque version et inclut des notes de migration spécifiques lorsque des paramètres changent.

Maintenir Agency Phone à jour

Lorsqu'une nouvelle version est publiée, vous recevez une notification dans votre compte CFX Keymaster. Pour mettre à jour, téléchargez le nouvel archive zip depuis la page Granted Assets, extrayez-la et remplacez le dossier agency-phone existant sur votre serveur. Lisez toujours le journal des modifications avant de mettre à jour sur un serveur en production — il liste les changements de clés dans config.lua qui nécessitent votre attention. Vos données de base de données et les données existantes des joueurs ne sont jamais supprimées lors d'une mise à jour.