Guia de instalação Agency Phone FiveM 2026

Este guia acompanha-o passo a passo na instalação e configuração do Agency Phone no seu servidor FiveM. Seja com QBCore, ESX ou um framework totalmente personalizado, encontrará aqui tudo o que precisa — dos pré-requisitos ao primeiro arranque, passando pelo ajuste fino do ficheiro de configuração. Para a referência técnica completa, consulte a documentação oficial em docs.agencyg.de/phone.

Pré-requisitos

Antes de instalar o Agency Phone, certifique-se de que o seu ambiente de servidor cumpre os seguintes requisitos:

• Artifact FiveM: versão 6633 ou superior (recomendado: mantenha sempre os artifacts atualizados)
• Base de dados: MySQL 5.7+ ou MariaDB 10.3+, com oxmysql (recomendado) ou mysql-async instalado e configurado
• CFX Keymaster: a chave de licença do seu servidor deve estar registada e ativa em keymaster.fivem.net
• Framework (opcional): QBCore ou ESX se pretender uma integração mais profunda. Não é necessário para funcionamento standalone.
• Compra ativa do Agency Phone: o recurso é disponibilizado através do portal de assets CFX após a compra

Passo 1 — Compra e download

Após concluir a sua compra na loja Agency Scripts, a sua licença fica automaticamente registada na sua conta CFX. Para fazer o download:

1. Inicie sessão em keymaster.fivem.net com a conta CFX associada à sua compra.
2. Aceda a Granted Assets e localize agency-phone.
3. Clique em Download para obter o ficheiro zip da versão mais recente.
4. Se adquiriu o bridge QBCore ou ESX, faça também o download de agency-phone-bridge-qb ou agency-phone-bridge-esx da mesma lista.

Passo 2 — Estrutura de pastas

Extraia o(s) ficheiro(s) zip. O seu diretório resources deverá ter este aspeto após a extração:

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

A pasta [agency] é uma pasta de categoria (os parênteses retos indicam ao FiveM que se trata de um grupo de recursos). Não é estritamente obrigatória — pode colocar o agency-phone diretamente em resources/ — mas utilizar pastas de categoria mantém tudo organizado.

Passo 3 — Configuração da base de dados

O Agency Phone cria as suas próprias tabelas de base de dados no primeiro arranque através do sistema de migração automática integrado no oxmysql. Não precisa de importar ficheiros SQL manualmente. Certifique-se apenas de que a ligação à base de dados está configurada no server.cfg:

# server.cfg — cadeia de ligação à base de dados (exemplo oxmysql)
set mysql_connection_string "mysql://user:password@localhost/fivem_db?charset=utf8mb4"

No primeiro arranque do servidor, o Agency Phone criará as seguintes tabelas: phone_contacts, phone_messages, phone_calls, phone_gallery, phone_social_posts e phone_settings. Se estiver a usar uma base de dados nova, as tabelas serão criadas automaticamente. Se estiver a migrar de outro script de telefone, verifique se não existem conflitos de nomes no seu esquema existente.

Passo 4 — Entradas no server.cfg

Adicione as seguintes linhas ensure ao seu server.cfg. A ordem é importante — o oxmysql deve carregar antes do Agency Phone:

# Dependências
ensure oxmysql

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

# Adicionar apenas se usar o bridge QBCore:
# ensure qb-core
# ensure agency-phone-bridge-qb

# Adicionar apenas se usar o bridge ESX:
# ensure es_extended
# ensure agency-phone-bridge-esx

Se estiver a usar QBCore ou ESX, certifique-se de que o próprio framework carrega antes do recurso bridge, conforme indicado nos comentários acima. O núcleo standalone (agency-phone) deve sempre ser carregado antes de qualquer recurso bridge.

Passo 5 — Configuração (config.lua)

Abra agency-phone/config.lua num editor de texto. Este é o ficheiro de configuração principal e controla quase todos os aspetos do comportamento do telefone. Segue-se uma descrição detalhada das definições mais importantes:

Config = {}

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

-- ============================================================
-- NÚMEROS DE TELEFONE
-- ============================================================
-- Formato dos números gerados automaticamente. X = dígito aleatório.
Config.PhoneNumberFormat = "555-XXXX"

-- Permitir que os jogadores paguem moeda do jogo para mudar o número
Config.AllowNumberChange = true
Config.NumberChangeCost   = 500  -- moeda padrão (ajuste conforme o framework)

-- ============================================================
-- APLICAÇÕES: ativar/desativar apps individualmente
-- ============================================================
Config.EnableBankingApp   = true
Config.EnableSocialApp    = true
Config.EnableGPSApp       = true
Config.EnableCameraApp    = true
Config.EnableMDT          = false   -- definir true apenas para servidores LEO
Config.EnableNotesApp     = true

-- ============================================================
-- MDT (relevante apenas quando Config.EnableMDT = true)
-- ============================================================
-- Profissões com acesso à app MDT
Config.MDTJobs = { "police", "sheriff", "highway_patrol" }

-- ============================================================
-- REDE SOCIAL
-- ============================================================
-- Renomear a app social para corresponder ao lore do seu servidor
Config.SocialAppName = "Chirper"
-- Comprimento máximo de uma publicação em caracteres
Config.SocialPostMaxLength = 280

-- ============================================================
-- MENSAGENS CIFRADAS
-- Requer que o jogador tenha um item específico no inventário
-- ============================================================
Config.EncryptedChat     = false
Config.EncryptedChatItem = "burner_phone"

-- ============================================================
-- INTERFACE
-- ============================================================
-- Tema padrão: "dark" ou "light"
Config.DefaultTheme = "dark"
-- Duração de exibição das notificações em milissegundos
Config.NotificationDuration = 5000
-- Tecla para abrir o telefone (nome de tecla FiveM)
Config.PhoneKey = "F1"

Notas específicas do QBCore

Ao usar o bridge QBCore (Config.Framework = "qbcore"), a aplicação bancária extrai automaticamente o saldo e os dados de transações da economia QBCore. As permissões de aplicação baseadas em profissão (como o acesso ao MDT) utilizam o sistema de profissões nativo do QBCore — não é necessária configuração adicional além de adicionar os nomes das profissões a Config.MDTJobs. Os números de telefone são armazenados por personagem e associados ao identificador de personagem do QBCore.

Notas específicas do ESX

Com o bridge ESX (Config.Framework = "esx"), a aplicação bancária liga-se às contas ESX (padrão: bank). Se a sua configuração ESX usar nomes de conta personalizados, configure-os no próprio config.lua do bridge. Os graus de profissão ESX são respeitados para o acesso ao MDT — apenas os nomes das profissões precisam de ser listados; todos os graus dessa profissão obtêm acesso automaticamente, a menos que configure restrições de grau na configuração do bridge.

Passo 6 — Verificação do primeiro arranque

Inicie o seu servidor e observe a saída da consola. Um carregamento bem-sucedido do Agency Phone tem este aspeto:

[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

Se encontrar erros nesta fase, consulte a secção de resolução de problemas abaixo. Assim que o servidor estiver a funcionar, ligue-se com um cliente e prima F1 (ou a tecla que configurou) para abrir o telefone. Na primeira utilização, o telefone solicitará ao jogador que defina o seu número caso ainda não tenha um atribuído.

Erros comuns e soluções

Erro: «oxmysql is not started»

Isto significa que o oxmysql não está a ser carregado antes do agency-phone no seu server.cfg. Mova a linha ensure oxmysql para cima da linha ensure agency-phone e reinicie o servidor.

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

Trata-se de um aviso, não de um erro fatal — significa que está a reinstalar sobre uma base de dados existente. Os dados existentes são preservados. Pode ignorar este aviso com segurança. Se pretender uma instalação limpa, elimine manualmente as tabelas phone_* na sua base de dados primeiro.

A interface do telefone não abre ao premir a tecla

Primeiro, verifique se o recurso iniciou sem erros na consola do servidor. Segundo, confirme que nenhum outro recurso está a usar o mesmo atalho de teclado (padrão: F1). Pode alterar o atalho no config.lua em Config.PhoneKey. Terceiro, verifique conflitos de foco NUI — se outro recurso estiver a capturar o foco NUI ao mesmo tempo, o telefone pode não receber corretamente a pressão da tecla.

A aplicação bancária mostra $0 / saldo vazio

Se estiver em modo standalone, a aplicação bancária usa uma carteira interna por padrão. Para a ligar à economia do QBCore ou ESX, deve usar o recurso bridge correspondente e definir corretamente Config.Framework. Se o bridge estiver carregado mas o saldo continuar a mostrar zero, verifique se o personagem do jogador está completamente carregado no framework antes de o telefone inicializar (ordem de carregamento no server.cfg).

A aplicação MDT não é visível para os agentes da polícia

Confirme que Config.EnableMDT = true no config.lua e que o nome da profissão atual do jogador corresponde exatamente a uma das entradas em Config.MDTJobs. A correspondência de nomes de profissões é sensível a maiúsculas e minúsculas. Use exatamente a cadeia de nome de profissão tal como está definida na configuração de profissões do seu framework.

Opções de configuração adicionais

O Agency Phone tem muitas mais opções de configuração além do que é abordado neste guia. Algumas das definições avançadas mais úteis incluem:

• Config.MaxContactsPerPlayer — limita o número de contactos que um jogador pode guardar (padrão: ilimitado)
• Config.GPSUpdateInterval — frequência com que o blip de localização do jogador é atualizado no GPS partilhado (em milissegundos)
• Config.SocialPostCooldown — tempo mínimo entre publicações nas redes sociais para evitar spam (em segundos)
• Config.AllowAnonCalls — se os jogadores podem fazer chamadas ocultando o número ao destinatário
• Config.CameraPhotoQuality — nível de qualidade das capturas NUI (1 a 10, afeta o tamanho das imagens na galeria do jogo)

O ficheiro de configuração completo e anotado com todas as opções está disponível na documentação oficial em docs.agencyg.de/phone. A documentação é atualizada a cada versão e inclui notas de migração específicas quando as definições mudam.

Manter o Agency Phone atualizado

Quando uma nova versão é lançada, receberá uma notificação na sua conta CFX Keymaster. Para atualizar, faça o download do novo ficheiro zip a partir da página Granted Assets, extraia-o e substitua a pasta agency-phone existente no seu servidor. Leia sempre o registo de alterações antes de atualizar num servidor em produção — lista as alterações nas chaves do config.lua que requerem a sua atenção. A sua base de dados e os dados existentes dos jogadores nunca são eliminados por uma atualização.