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.
| Function | Who can run it | What it does |
|---|---|---|
| open() | Anyone | Opens your phone window. Returns a promise. |
| close() | Anyone | Closes your phone window. Returns a promise. |
| toggle() | Anyone | Opens 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 GM | Plants 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 only | Removes 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) | Anyone | Returns 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 only | Puts 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.
| Hook | Payload | When |
|---|---|---|
| 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' });
| Field | Required | Meaning |
|---|---|---|
| kind | Yes | One of photo, image, audio, text or data. |
| name | Yes | The title shown in the list. |
| url | No | A file path or link for a photo, image or audio file. |
| body | No | The written content, for a text file. |
| caption | No | A short line shown with the item. |
| fromLabel | No | Who it appears to come from, for example "Anonymous". |
| takenAt | No | An in-story date and time as text, such as 2026-03-14T23:10:00. Leave it out to use the current story clock. |
| handoutId | No | Links 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.
| Setting | Default | What it does |
|---|---|---|
| The phone is an inventory item | Off | When 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 chat | Off | Copies 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
- Photos and files
- The GM Manage panel
- Phone as an inventory item
- Handouts macros and API
- Using Phone and Handouts together
- Frequently asked questions
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.