Integration

Upload

Upload providers for photos, videos and voice messages: Fivemanage, the Fixitfy relay or your own host.

Photos, videos, voice messages, profile pictures and listing images are stored by an upload provider. The database only keeps the links.

lua-- config_server.lua
ServerConfig.Upload.Provider = 'fivemanage'   -- 'fivemanage' | 'fmapi' | 'relay' | 'custom' | 'none'
Provider Key How the file travels
fivemanage Fivemanage v3 API key Player to Fivemanage with a presigned URL
fmapi Fivemanage v2 token Player to Fivemanage with a presigned URL
relay None (enrols itself) Player to the relay's storage with a presigned URL
custom Your service's headers Player to the game server in small parts, then server to your service
none Uploads are off; the camera works, nothing can be saved or sent

Keys stay on the server in config_server.lua. Never put them in config.lua or a file in configs/.

#Accepted files

Kind Types
Photos image/jpeg, image/png, image/webp
Videos video/webm, video/mp4
Audio audio/webm, audio/ogg, audio/mpeg, audio/wav

The largest file is Config.Limits.UploadBytes (6 MiB by default). Files sent through the game server (the custom provider without presigning) are limited to 1 MiB.

After an upload the server checks that the link is on the provider's host before it is saved. Players cannot make the phone store a link to somewhere else.

Links typed or pasted by players, and links passed by scripts (photos, avatars, attachments, listing images), must be on the active provider's host or on a host in AllowedHosts:

luaAllowedHosts = { 'fivemanage.com', 'imgur.com', 'tenor.com', 'giphy.com' },   -- subdomains included
BlockedHosts = { 'cdn.discordapp.com', 'media.discordapp.net' },              -- wins over AllowedHosts

Other players load those images, so the list is limited to known hosts. Discord's CDN stays blocked because its attachment links are signed and expire within a day; a saved photo would break the next morning. Add your own image host to AllowedHosts if players or scripts use one.

#Fivemanage v3

luaFivemanage = {
    Image = 'your-api-key',   -- one key is enough for every type
    Video = '',               -- optional separate keys
    Audio = '',
    CdnHost = '',             -- your custom Fivemanage CDN domain, e.g. 'cdn.myserver.com'
},
  1. The phone asks the server for an upload slot (type, size, mime).
  2. The server requests a presigned URL from Fivemanage, valid for 60 seconds, with your key.
  3. The phone posts the file to that URL as the multipart field file and reads the link from the answer.
  4. The server accepts the link only on r2.fivemanage.com or your CdnHost.

Files never pass through the game server. If presigning fails, the console shows [fx-phone:media] fivemanage presign failed: <reason>.

#Fivemanage v2

For tokens created before v3. Same flow with the v2 API; the multipart field is the file type (image, video, audio).

luaProvider = 'fmapi',
FmApi = { Token = 'your-v2-token' },

#Fixitfy relay

luaProvider = 'relay',
Relay = { Url = 'https://relay.example.com', Key = '' },

Url is the relay address Fixitfy gives you. No key ships with the resource:

  1. On the first upload the server enrols itself at the relay with a fingerprint (your web_baseUrl convar, or a random id kept in the resource KVP), the resource name and version.
  2. The relay answers with a key; the server keeps it in the resource KVP.
  3. Uploads ask the relay for a presigned URL; the player uploads to the URL it returns.
  4. If the relay refuses the key, the server forgets it and enrols again on the next upload.
  5. A refused enrolment backs off: 6 hours after a 403 answer, 1 hour after 429, 15 minutes otherwise.

Set Key only if Fixitfy gave you one; it is then used as-is and nothing is enrolled.

#Custom provider

luaProvider = 'custom',
Custom = {
    Url = 'https://upload.example.com/api/upload',
    Field = 'file',
    Headers = { Authorization = 'Bearer your-token' },
    Hosts = { 'cdn.example.com' },   -- when files are served from another host than Url
},

The server posts the file as multipart field Field with Headers and reads the link from the JSON answer at the first of url, data.url, link, data.link, files.1.url, attachments.1.url. Only https links on the host of Url or a host in Hosts are accepted.

#Presigning with your own service

server/integrations/upload_custom.lua is open for editing. To let players upload straight to your service, set CanPresign = true and make Presign(kind, bytes, mime) return a single-use target:

lua-- { url, method = 'PUT' | 'POST', headers?, fields?, fileField?, result?, publicUrl?, expires? }
function adapter.Presign(kind, bytes, mime)
    local status, body = Integration.Upload.Request('POST', 'https://upload.example.com/sign',
        json.encode({ kind = kind, bytes = bytes, mime = mime }),
        { Authorization = 'Bearer your-token', ['Content-Type'] = 'application/json' })
    local data = status == 200 and Integration.Upload.Json(body)
    if not data then return nil, ('sign answered %s'):format(status) end
    return { url = data.uploadUrl, method = 'PUT', headers = { ['Content-Type'] = mime }, publicUrl = data.publicUrl }
end
Field Meaning
url, method Where and how the player sends the file
headers Headers for that request
fields, fileField Extra multipart fields and the file's field name. Leave fileField out for a raw PUT
result Dotted path of the link in the answer, for example 'data.url'
publicUrl The final link when you know it in advance

The player sees everything in this table. Never return a long-lived token.

#Troubleshooting

Console Fix
uploads are off: ServerConfig.Upload.Provider "x" is not available The name is not one of the five
fivemanage presign failed: no API key in ServerConfig.Upload.Fivemanage Add the key
fivemanage presign failed: presigned URL request answered 401 Wrong or revoked key
player 12 finished upload ... with a URL that does not match fivemanage A custom CDN domain is in use; set CdnHost
relay enrolment answered 403, retrying in 360 minutes The relay refused this server; contact Fixitfy
custom upload failed: no accepted URL in the reply The answer has no https link on an allowed host; add it to Hosts

Settings reference: config_server.lua. Media exports: Media exports.