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.
#Checked links
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'
},
- The phone asks the server for an upload slot (type, size, mime).
- The server requests a presigned URL from Fivemanage, valid for 60 seconds, with your key.
- The phone posts the file to that URL as the multipart field
fileand reads the link from the answer. - The server accepts the link only on
r2.fivemanage.comor yourCdnHost.
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:
- On the first upload the server enrols itself at the relay with a fingerprint (your
web_baseUrlconvar, or a random id kept in the resource KVP), the resource name and version. - The relay answers with a key; the server keeps it in the resource KVP.
- Uploads ask the relay for a presigned URL; the player uploads to the URL it returns.
- If the relay refuses the key, the server forgets it and enrols again on the next upload.
- 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.