Foundry modules / Documentation

Macros and the phone API

Last checked 2026-10-12

The phone API

The phone exposes a small set of functions on the module object. In a script macro, reach them with game.modules.get('shawnsvtts-phone').api. The object is created when the world finishes loading, so use it from macros and other modules, not from code that runs earlier. It only exists if the free ShawnsVTTs Library is installed and enabled; without the Library the phone shows an error and does not start.

FunctionWho can run itWhat it does
open()AnyoneOpens your phone window. Returns a promise.
close()AnyoneCloses your phone window. Returns a promise.
toggle()AnyoneOpens the window if it is closed and closes it if it is open. Returns a promise.
sendFile(actorOrId, file)The character's owner or a GMPlants a photo or file on a character's phone. Takes an actor or an actor id. Returns a promise that resolves with the new entry's id. It throws "Unknown handset" if no actor matches.
compact()GM onlyRemoves superseded read marks and similar bookkeeping entries from the phone logs. Resolves with how many entries were removed. It throws for a player.
getNumber(actorOrId)AnyoneReturns the phone number the phone shows for that actor, or null if it has none. ShawnsVTTs Handouts uses it to print the number on a business card.
shareContact(npc, characters)GM onlyPuts an NPC in the contacts of one character or several. characters is one actor or id, or an array of them. It throws if the first argument is not an NPC or a listed actor is not a character. It resolves when the contacts are saved.

Each function applies to the phone on the machine where the macro runs. There is no function for texting, calling or paying: those happen in the phone itself, and the GM texts as an NPC from the GM phone.

Hooks the phone calls

The phone announces two things with Foundry's Hooks.callAll, so other modules and macros can react.

HookPayloadWhen
shawnsvtts-phone.contactShared{ npcId, characterIds }After shareContact adds an NPC to characters' contacts. characterIds lists only the characters who did not have the NPC before. It is not called if nobody was added.
shawnsvtts-phone.openHandout{ handoutId }A player presses OPEN HANDOUT on a file that came from a handout. It is only called when ShawnsVTTs Handouts is enabled. Handouts answers it by opening the handout.

The Handouts module has its own API. See Handouts macros and API.

Macro: open the phone

Create a new macro, set its type to Script, paste this line, and drag the macro to your hotbar.

game.modules.get('shawnsvtts-phone').api.open();

Use game.modules.get('shawnsvtts-phone').api.toggle(); instead if you want the same button to close the phone again.

Macro: plant a photo or file for a player

This puts a photo on a character's phone, in the Photos app, as if it had been taken or received in the story. Change the character name, the picture path and the captions. The name must match the character exactly.

await game.modules.get('shawnsvtts-phone').api.sendFile(game.actors.getName('Aria'), { kind: 'photo', name: 'Dock at night', url: 'uploads/dock.png', caption: 'Taken from the roof', fromLabel: 'Anonymous', takenAt: '2026-03-14T23:10:00' });

A text file works the same way, with a body instead of a picture: await game.modules.get('shawnsvtts-phone').api.sendFile('ACTOR_ID', { kind: 'text', name: 'Shipping ledger', body: 'Pier 9: 4 crates' });

FieldRequiredMeaning
kindYesOne of photo, image, audio, text or data.
nameYesThe title shown in the list.
urlNoA file path or link for a photo, image or audio file.
bodyNoThe written content, for a text file.
captionNoA short line shown with the item.
fromLabelNoWho it appears to come from, for example "Anonymous".
takenAtNoAn in-story date and time as text, such as 2026-03-14T23:10:00. Leave it out to use the current story clock.
handoutIdNoLinks the item to a handout.

There is no screen in the phone for planting files. A macro is the only way. The player sees the item arrive on their handset; see Photos and files.

Keyboard shortcut and toolbar button

  • The P key opens and closes the phone. It is registered as "Open or close the phone" in Foundry's Configure Controls window, where each player can rebind it.
  • A mobile phone icon labelled "Phone" sits at the bottom of the Token controls group in the scene controls. While something is waiting for you (a new message or a call), the button pulses and shows a count.
  • The phone opens in a normal Foundry window, 400 by 800 pixels to start, that you can drag, resize and minimise.

Module settings

Open Game Settings, then Configure Settings, then the ShawnsVTTs Phone section. Both settings are world settings, so only the GM can change them.

SettingDefaultWhat it does
The phone is an inventory itemOffWhen on, a character's phone only works while they carry an item named Phone, Smartphone, Cell phone, Mobile, Handset, Burner or Commlink, or an item flagged as a phone. See Phone as an inventory item.
Echo phone messages to chatOffCopies texts, group chats and party messages into the Foundry chat log. Choices: Off, GM only (a whisper to the GM) or Everyone (public). See Echo to chat.

Everything else, including the battery, signal zones, notices, era, app switches, phone numbers and voicemail greetings, lives in the Manage panel on the GM's phone, not in the settings window. The module also keeps its own saved state in hidden world settings that are not shown in the settings window, so there is nothing to edit there.

Related

Foundry Virtual Tabletop belongs to Foundry Gaming LLC. ShawnsVTTs modules are independent add-ons and are not made, endorsed or supported by Foundry Gaming LLC.