Character Vault
Any Concept / Any System
Compendium
Your System Come To Life
Roll20 for Android
Streamlined for your Tablet
Roll20 for iPad
Streamlined for your Tablet

Personal tools

Difference between revisions of "Mod:Chat"

From Roll20 Wiki

Jump to: navigation, search
m (Chat Events: Added rolltemplate property.)
m (1223200 moved page API:Chat to Mod:Chat)
 
(34 intermediate revisions by 10 users not shown)
Line 1: Line 1:
{{apibox}}
+
{{revdate}}{{HCbox| {{hc|articles/360037256754-API-Chat Here}} }}
 +
{{API dev}}{{apibox}}
 
===Chat Events===
 
===Chat Events===
  
 
'''chat:message'''
 
'''chat:message'''
  
Triggered whenever a new chat message is received. Note that if the message is of type "rollresult", you will need to call <code>JSON.parse()</code> on the content of the message to get an object which contains information on the roll results.  
+
Triggered whenever a new chat message is received. Note that if the message is of type {{c|rollresult}} or {{c|gmrollresult}}, you will need to call <code>JSON.parse()</code> on the content of the message to get an object which contains information on the roll results.  
  
''Note:'' If a player enters a chat message beginning with an exclamation mark (!), that message will have the type of "api" and not be shown to anyone. It's intended that this functionality can be used to provide commands that API scripts respond to. So, if the message is of type "api", then it hasn't been shown to anyone, and the player who sent the chat message is probably expecting an API script to do something as a result of the message.
+
''Note:'' If a player enters a chat message beginning with an exclamation mark (!), that message will have the type of "api" and not be shown to anyone. It's intended that this functionality can be used to provide commands that Mod scripts respond to. So, if the message is of type "api", then it hasn't been shown to anyone, and the player who sent the chat message is probably expecting an Mod script to do something as a result of the message.
  
 
Callback parameter:
 
Callback parameter:
Line 25: Line 26:
 
| type
 
| type
 
| "general"
 
| "general"
| One of "general", "rollresult", "emote", "whisper", "desc", or "api".
+
| One of "general", "rollresult", "gmrollresult", "emote", "whisper", "desc", or "api".
 
|-
 
|-
 
| content
 
| content
Line 33: Line 34:
 
| origRoll
 
| origRoll
 
|
 
|
| ''(type "rollresult" only)'' The original text of the roll, eg: "2d10+5 fire damage" when the player types "/r 2d10+5 fire damage". This is equivalent to the use of <code>content</code> on messages with types other than "rollresult".
+
| ''(type "rollresult" or "gmrollresult" only)'' The original text of the roll, eg: <code>2d10+5 fire damage</code> when the player types <code>/r 2d10+5 fire damage</code>. This is equivalent to the use of <code>content</code> on messages with types other than "rollresult" or "gmrollresult".
 
|-
 
|-
| inlinerolls
+
| [[Inline Rolls|inlinerolls]]
 
|
 
|
 
| ''(content contains one or more inline rolls only)'' An array of objects containing information about all inline rolls in the message.
 
| ''(content contains one or more inline rolls only)'' An array of objects containing information about all inline rolls in the message.
 
|-
 
|-
| rolltemplate
+
| [[Roll Template|rolltemplate]]
 
|
 
|
 
|''(content contains one or more roll templates only)'' The name of the template specified.
 
|''(content contains one or more roll templates only)'' The name of the template specified.
Line 45: Line 46:
 
| target
 
| target
 
|
 
|
| ''(type "whisper" only)'' The player ID of the person the whisper is sent to. If the whisper was sent to the GM without using his or her display name (ie, "/w gm text" instead of "/w Riley text" when Riley is the GM), or if the whisper was sent to a character without any controlling players, the value will be "gm".
+
| ''(type "whisper" only)'' The player ID of the person the whisper is sent to. If the whisper was sent to the [[GM]] without using his or her display name (ie, <code>/w gm text</code> instead of <code>/w Riley text</code> when Riley is the GM), or if the whisper was sent to a character without any controlling [[players]], the value will be "gm".
 
|-
 
|-
 
| target_name
 
| target_name
Line 62: Line 63:
 
''Roll Result Structure Example 1''
 
''Roll Result Structure Example 1''
  
After you call <code>JSON.parse</code> on the <code>content</code> property of a "rollresult" message, you'll get an object with the following format (this is the result from the command <code> /roll {2d6}+5+1t[weather] Attack!</code>)
+
After you call <code>JSON.parse</code> on the <code>content</code> property of a "rollresult" or "gmrollresult" message, you'll get an object with the following format (this is the result from the command <code>/roll {2d6}+5+1t[weather] Attack!</code>)
 
<div class="mw-collapsible-content">
 
<div class="mw-collapsible-content">
 
<pre data-language="javascript">
 
<pre data-language="javascript">
Line 196: Line 197:
 
</pre>
 
</pre>
  
Note that you can also use the "token_id" attribute with @selected and @target variables in your API commands to pass in the token ID of a selected or targeted token. For example:
+
=== sendChat(speakingAs, input [,callback [, options]] ) {{Asynchronous}} ===
 
+
<pre data-language="javascript">
+
!attack @{target|token_id}
+
</pre>
+
 
+
===Chat Functions===
+
 
+
 
+
'''sendChat(speakingAs, input)'''
+
  
 
You can use this function to send a chat message.  
 
You can use this function to send a chat message.  
  
<code>speakingAs</code> should be one of:
+
<code style="font-size: 1.1em;font-weight:bold;">speakingAs</code> can be one of:
* Any string, in which case that will be used as the name of the person who sent the message. E.g. "Riley"
+
* Any string, in which case that will be used as the name of the person who sent the message. E.g. <code>"Riley"</code>
* A player's ID, formatted as "player|-Abc123" where "-Abc123" is the ID of the player. If you do this it will automatically use the avatar and name of the player.
+
* A player's ID, formatted as <code>"player|-Abc123"</code> where {{code|-Abc123}} is the ID of the player. If you do this it will automatically use the avatar and name of the player.
* A character's ID, formatted as "character|-Abc123". If you do this it will automatically use the avatar and name of the Character.
+
* A character's ID, formatted as <code>"character|-Abc123"</code>. If you do this it will automatically use the avatar and name of the Character.
  
  
<code>input</code> should be any valid expression just like the ones used in the Roll20 App. You enter text to send a basic message, or use slash-commands such as "/roll", "/em", "/w", etc. In addition:
+
<code style="font-size: 1.1em;font-weight:bold;">input</code> should be any valid expression just like the ones used in the Roll20 App. You enter text to send a basic message, or use slash-commands such as {{code|/roll}}, {{code|/em}}, {{code|/w}}, etc. In addition:
* You can use Character Attributes with the format <code>@{CharacterName|AttributeName}</code>.
+
* You can use [[Character#Attributes]] with the format <code>@{CharacterName|AttributeName}</code>.
* You can use Character Abilities with the format: <code>%{CharacterName|AbilityName}</code>.
+
* You can use [[Character#Abilities]] with the format: <code>%{CharacterName|AbilityName}</code>.
 
* You '''cannot''' use macros.
 
* You '''cannot''' use macros.
* You can use the "/direct <msg>" command to send a message without any processing (e.g. autolinking of URLs), and you can use the following HTML tags in the message: <pre><code><span><div><label><a><br><br /><p><b><i><del><strike><u><img><blockquote><mark><cite><small><ul><ol><li><hr><dl><dt><dd><sup><sub><big><pre><code><figure><figcaption><strong><em><table><tr><td><th><tbody><thead><tfoot><h1><h2><h3><h4><h5><h6></pre>
+
* You can use the "/direct <msg>" command to send a message without any processing (e.g. autolinking of URLs), and you can use the following HTML tags in the message: <pre><code><span><div><label><a><br><br /><p><b><i><del><strike><u><img><blockquote><mark><cite><small><ul><ol><li><hr><dl><dt><dd><sup><sub><big></pre><pre><pre><figure><figcaption><strong><em><table><tr><td><th><tbody><thead><tfoot><h1><h2><h3><h4><h5><h6></pre>
 +
* You can use a whitelisted set of inline CSS styles. The following tables list the full set of allowed properties and values:
 +
{| class="wikitable mw-collapsible mw-collapsed" id="css-sanitizer-key"
 +
|+ class="nowrap" | CSS Value Types Key
 +
|-
 +
!Category!!Description!!Examples
 +
|-
 +
|'''Colors'''||Accepted format for colors is any of the following:
 +
*rgb(x,y,z) - percentage or numeric
 +
*rgba(x,y,z,a) - percentage or numeric
 +
*hex - 3 or 6 alpha-numeric characters
 +
*literal - any of the following color literals may be used:<br>''aliceblue, antiquewhite, aqua, aquamarine, azure, beige, bisque, black, blanchedalmond, blue, blueviolet, brown, burlywood, cadetblue, chartreuse, chocolate, coral, cornflowerblue, cornsilk, crimson, cyan, darkblue, darkcyan, darkgoldenrod, darkgray, darkgreen, darkkhaki, darkmagenta, darkolivegreen, darkorange, darkorchid, darkred, darksalmon, darkseagreen, darkslateblue, darkslategray, darkturquoise, darkviolet, deeppink, deepskyblue, dimgray, dodgerblue, firebrick, floralwhite, forestgreen, fuchsia, gainsboro, ghostwhite, gold, goldenrod, gray, green, greenyellow, honeydew, hotpink, indianred, indigo, ivory, khaki, lavender, lavenderblush, lawngreen, lemonchiffon, lightblue, lightcoral, lightcyan, lightgoldenrodyellow, lightgreen, lightgrey, lightpink, lightsalmon, lightseagreen, lightskyblue, lightslategray, lightsteelblue, lightyellow, lime, limegreen, linen, magenta, maroon, mediumaquamarine, mediumblue, mediumorchid, mediumpurple, mediumseagreen, mediumslateblue, mediumspringgreen, mediumturquoise, mediumvioletred, midnightblue, mintcream, mistyrose, moccasin, navajowhite, navy, oldlace, olive, olivedrab, orange, orangered, orchid, palegoldenrod, palegreen, paleturquoise, palevioletred, papayawhip, peachpuff, peru, pink, plum, powderblue, purple, red, rosybrown, royalblue, saddlebrown, salmon, sandybrown, seagreen, seashell, sienna, silver, skyblue, slateblue, slategray, snow, springgreen, steelblue, tan, teal, thistle, tomato, turquoise, violet, wheat, white, whitesmoke, yellow, yellowgreen''
 +
|color: rgb(10,255,10)<br>color: rgba(50%,50%,50%,0%)<br>color: #aa99cc<br>color: aliceblue
 +
|-
 +
|'''Quantity'''||A positive number - integer or float. Must start with a digit, but can be suffixed with non-number word characters like rem/px/pt||border-radius: 5px<br>font-size: 5.5rem
 +
|-
 +
|'''Negative Quantity'''||The same as Quantity, but with a leading "-". No whitespace is allowed between the negative sign and the digits.||margin-left: -5px<br>
 +
|-
 +
|'''URL'''||Accepts a web URL using http:// or https:// - the resulting URL will be sanitized run through ''<u>imgsrv.roll20.net</u>'' || background: <nowiki>url(https://app.roll20.net/v2/images/roll20-logo.png</nowiki>)
 +
|-
 +
|'''String Content'''||Rarely used, this allows most word characters through in the value. Still sanitized to remove any control characters, though. Strips any apostrophes and quotes from the ends and wraps the result in "quotations"||font: this font doesnt exist <i>(passes the sanitizer but doesn't achieve anything)</i>
 +
|-
 +
|'''Z-Index'''||Any integer containing 1 to 7 digits. Only used for the z-index property itself||z-index: 1234567
 +
|}
  
You can also add a third parameter consisting of a callback function which will be passed the results of the sendChat() call instead of sending the commands to the game. The results of the sendChat command will be an ARRAY of operations, and each individual object will be just like an object you receive during a <code>chat:message</code> event (see above).
+
{| class="wikitable mw-collapsible mw-collapsed" id="css-standard-props"
 +
|+ class="nowrap" | CSS Standard Properties
 +
|-
 +
!CSS Property!!Allowed Values
 +
|-
 +
|azimuth||[[{{FULLPAGENAME}}#css-sanitizer-key|Quantity]]<br>[[{{FULLPAGENAME}}#css-sanitizer-key|Negative Quantity]]<br><i>Literals: </i>behind, center-left, center-right, far-left, far-right, left-side, leftwards, right-side, rightwards, left, right, center, inherit
 +
|-
 +
|background||[[{{FULLPAGENAME}}#css-sanitizer-key|Colors]]<br>[[{{FULLPAGENAME}}#css-sanitizer-key|Quantity]]<br>[[{{FULLPAGENAME}}#css-sanitizer-key|Negative Quantity]]<br>[[{{FULLPAGENAME}}#css-sanitizer-key|URL]]<br><i>Literals: </i>border-box, contain, content-box, cover, padding-box, no-repeat, repeat-x, repeat-y, round, space, bottom, top, left, right, ",", "/", auto, center, fixed, inherit, local, none, repeat, scroll, transparent
 +
|-
 +
|background-size||[[{{FULLPAGENAME}}#css-sanitizer-key|Colors]]<br>[[{{FULLPAGENAME}}#css-sanitizer-key|Quantity]]<br>[[{{FULLPAGENAME}}#css-sanitizer-key|Negative Quantity]]<br>[[{{FULLPAGENAME}}#css-sanitizer-key|URL]]<br><i>Literals: </i>border-box, contain, content-box, cover, padding-box, no-repeat, repeat-x, repeat-y, round, space, bottom, top, left, right, ",", "/", auto, center, fixed, inherit, local, none, repeat, scroll, transparent
 +
|-
 +
|background-attachment||<i>Literals: </i>",", fixed, local, scroll
 +
|-
 +
|background-color||[[{{FULLPAGENAME}}#css-sanitizer-key|Colors]]<br><i>Literals: </i>inherit, transparent
 +
|-
 +
|background-image||[[{{FULLPAGENAME}}#css-sanitizer-key|URL]]<br><i>Literals: </i>",", none
 +
|-
 +
|background-position||[[{{FULLPAGENAME}}#css-sanitizer-key|Quantity]]<br>[[{{FULLPAGENAME}}#css-sanitizer-key|Negative Quantity]]<br><i>Literals: </i>bottom, top, left, right, ",", center
 +
|-
 +
|background-repeat||<i>Literals: </i>no-repeat, repeat-x, repeat-y, round, space, ",", repeat
 +
|-
 +
|border||[[{{FULLPAGENAME}}#css-sanitizer-key|Colors]]<br>[[{{FULLPAGENAME}}#css-sanitizer-key|Quantity]]<br>[[{{FULLPAGENAME}}#css-sanitizer-key|Negative Quantity]]<br><i>Literals: </i>dashed, dotted, double, groove, outset, ridge, solid, thick, thin, hidden, inherit, inset, medium, none, transparent
 +
|-
 +
|border-bottom||[[{{FULLPAGENAME}}#css-sanitizer-key|Colors]]<br>[[{{FULLPAGENAME}}#css-sanitizer-key|Quantity]]<br>[[{{FULLPAGENAME}}#css-sanitizer-key|Negative Quantity]]<br><i>Literals: </i>dashed, dotted, double, groove, outset, ridge, solid, thick, thin, hidden, inherit, inset, medium, none, transparent
 +
|-
 +
|border-bottom-color||[[{{FULLPAGENAME}}#css-sanitizer-key|Colors]]<br><i>Literals: </i>inherit, transparent
 +
|-
 +
|border-bottom-left-radius||[[{{FULLPAGENAME}}#css-sanitizer-key|Quantity]]<br>[[{{FULLPAGENAME}}#css-sanitizer-key|Negative Quantity]]
 +
|-
 +
|border-bottom-right-radius||[[{{FULLPAGENAME}}#css-sanitizer-key|Quantity]]<br>[[{{FULLPAGENAME}}#css-sanitizer-key|Negative Quantity]]
 +
|-
 +
|border-bottom-style||<i>Literals: </i>dashed, dotted, double, groove, outset, ridge, solid, hidden, inherit, inset, none
 +
|-
 +
|border-bottom-width||[[{{FULLPAGENAME}}#css-sanitizer-key|Quantity]]<br>[[{{FULLPAGENAME}}#css-sanitizer-key|Negative Quantity]]<br><i>Literals: </i>thick, thin, inherit, medium
 +
|-
 +
|border-collapse||<i>Literals: </i>collapse, inherit, separate
 +
|-
 +
|border-color||[[{{FULLPAGENAME}}#css-sanitizer-key|Colors]]<br><i>Literals: </i>inherit, transparent
 +
|-
 +
|border-left||[[{{FULLPAGENAME}}#css-sanitizer-key|Colors]]<br>[[{{FULLPAGENAME}}#css-sanitizer-key|Quantity]]<br>[[{{FULLPAGENAME}}#css-sanitizer-key|Negative Quantity]]<br><i>Literals: </i>dashed, dotted, double, groove, outset, ridge, solid, thick, thin, hidden, inherit, inset, medium, none, transparent
 +
|-
 +
|border-left-color||[[{{FULLPAGENAME}}#css-sanitizer-key|Colors]]<br><i>Literals: </i>inherit, transparent
 +
|-
 +
|border-left-style||<i>Literals: </i>dashed, dotted, double, groove, outset, ridge, solid, hidden, inherit, inset, none
 +
|-
 +
|border-left-width||[[{{FULLPAGENAME}}#css-sanitizer-key|Quantity]]<br>[[{{FULLPAGENAME}}#css-sanitizer-key|Negative Quantity]]<br><i>Literals: </i>thick, thin, inherit, medium
 +
|-
 +
|border-radius||[[{{FULLPAGENAME}}#css-sanitizer-key|Quantity]]<br>[[{{FULLPAGENAME}}#css-sanitizer-key|Negative Quantity]]<br><i>Literals: </i>"/"
 +
|-
 +
|border-right||[[{{FULLPAGENAME}}#css-sanitizer-key|Colors]]<br>[[{{FULLPAGENAME}}#css-sanitizer-key|Quantity]]<br>[[{{FULLPAGENAME}}#css-sanitizer-key|Negative Quantity]]<br><i>Literals: </i>dashed, dotted, double, groove, outset, ridge, solid, thick, thin, hidden, inherit, inset, medium, none, transparent
 +
|-
 +
|border-right-color||[[{{FULLPAGENAME}}#css-sanitizer-key|Colors]]<br><i>Literals: </i>inherit, transparent
 +
|-
 +
|border-right-style||<i>Literals: </i>dashed, dotted, double, groove, outset, ridge, solid, hidden, inherit, inset, none
 +
|-
 +
|border-right-width||[[{{FULLPAGENAME}}#css-sanitizer-key|Quantity]]<br>[[{{FULLPAGENAME}}#css-sanitizer-key|Negative Quantity]]<br><i>Literals: </i>thick, thin, inherit, medium
 +
|-
 +
|border-spacing||[[{{FULLPAGENAME}}#css-sanitizer-key|Quantity]]<br>[[{{FULLPAGENAME}}#css-sanitizer-key|Negative Quantity]]<br><i>Literals: </i>inherit
 +
|-
 +
|border-style||<i>Literals: </i>dashed, dotted, double, groove, outset, ridge, solid, hidden, inherit, inset, none
 +
|-
 +
|border-top||[[{{FULLPAGENAME}}#css-sanitizer-key|Colors]]<br>[[{{FULLPAGENAME}}#css-sanitizer-key|Quantity]]<br>[[{{FULLPAGENAME}}#css-sanitizer-key|Negative Quantity]]<br><i>Literals: </i>dashed, dotted, double, groove, outset, ridge, solid, thick, thin, hidden, inherit, inset, medium, none, transparent
 +
|-
 +
|border-top-color||[[{{FULLPAGENAME}}#css-sanitizer-key|Colors]]<br><i>Literals: </i>inherit, transparent
 +
|-
 +
|border-top-left-radius||[[{{FULLPAGENAME}}#css-sanitizer-key|Quantity]]<br>[[{{FULLPAGENAME}}#css-sanitizer-key|Negative Quantity]]
 +
|-
 +
|border-top-right-radius||[[{{FULLPAGENAME}}#css-sanitizer-key|Quantity]]<br>[[{{FULLPAGENAME}}#css-sanitizer-key|Negative Quantity]]
 +
|-
 +
|border-top-style||<i>Literals: </i>dashed, dotted, double, groove, outset, ridge, solid, hidden, inherit, inset, none
 +
|-
 +
|border-top-width||[[{{FULLPAGENAME}}#css-sanitizer-key|Quantity]]<br>[[{{FULLPAGENAME}}#css-sanitizer-key|Negative Quantity]]<br><i>Literals: </i>thick, thin, inherit, medium
 +
|-
 +
|border-width||[[{{FULLPAGENAME}}#css-sanitizer-key|Quantity]]<br>[[{{FULLPAGENAME}}#css-sanitizer-key|Negative Quantity]]<br><i>Literals: </i>thick, thin, inherit, medium
 +
|-
 +
|bottom||[[{{FULLPAGENAME}}#css-sanitizer-key|Quantity]]<br>[[{{FULLPAGENAME}}#css-sanitizer-key|Negative Quantity]]<br><i>Literals: </i>auto, inherit
 +
|-
 +
|box-shadow||[[{{FULLPAGENAME}}#css-sanitizer-key|Colors]]<br>[[{{FULLPAGENAME}}#css-sanitizer-key|Quantity]]<br>[[{{FULLPAGENAME}}#css-sanitizer-key|Negative Quantity]]<br><i>Literals: </i>",", inset, none
 +
|-
 +
|caption-side||<i>Literals: </i>bottom, top, inherit
 +
|-
 +
|clear||<i>Literals: </i>left, right, both, inherit, none
 +
|-
 +
|clip||<i>Literals: </i>auto, inherit
 +
|-
 +
|color||[[{{FULLPAGENAME}}#css-sanitizer-key|Colors]]<br><i>Literals: </i>inherit
 +
|-
 +
|content||[[{{FULLPAGENAME}}#css-sanitizer-key|String Content]]<br><i>Literals: </i>none, normal
 +
|-
 +
|counter-increment||[[{{FULLPAGENAME}}#css-sanitizer-key|Quantity]]<br>[[{{FULLPAGENAME}}#css-sanitizer-key|Negative Quantity]]<br><i>Literals: </i>inherit, none
 +
|-
 +
|counter-reset||[[{{FULLPAGENAME}}#css-sanitizer-key|Quantity]]<br>[[{{FULLPAGENAME}}#css-sanitizer-key|Negative Quantity]]<br><i>Literals: </i>inherit, none
 +
|-
 +
|cue||[[{{FULLPAGENAME}}#css-sanitizer-key|URL]]<br><i>Literals: </i>inherit, none
 +
|-
 +
|cue-after||[[{{FULLPAGENAME}}#css-sanitizer-key|URL]]<br><i>Literals: </i>inherit, none
 +
|-
 +
|cue-before||[[{{FULLPAGENAME}}#css-sanitizer-key|URL]]<br><i>Literals: </i>inherit, none
 +
|-
 +
|cursor||[[{{FULLPAGENAME}}#css-sanitizer-key|URL]]<br><i>Literals: </i>all-scroll, col-resize, crosshair, default, e-resize, hand, help, move, n-resize, ne-resize, no-drop, not-allowed, nw-resize, pointer, progress, row-resize, s-resize, se-resize, sw-resize, text, vertical-text, w-resize, wait, ",", auto, inherit
 +
|-
 +
|direction||<i>Literals: </i>ltr, rtl, inherit
 +
|-
 +
|display||<i>Literals: </i>-moz-inline-box, -moz-inline-stack, block, inline, inline-block, inline-table, list-item, run-in, table, table-caption, table-cell, table-column, table-column-group, table-footer-group, table-header-group, table-row, table-row-group, inherit, none
 +
|-
 +
|elevation||[[{{FULLPAGENAME}}#css-sanitizer-key|Quantity]]<br>[[{{FULLPAGENAME}}#css-sanitizer-key|Negative Quantity]]<br><i>Literals: </i>above, below, higher, level, lower, inherit
 +
|-
 +
|empty-cells||<i>Literals: </i>hide, show, inherit
 +
|-
 +
|filter||-
 +
|-
 +
|float||<i>Literals: </i>left, right, inherit, none
 +
|-
 +
|font||[[{{FULLPAGENAME}}#css-sanitizer-key|Quantity]]<br>[[{{FULLPAGENAME}}#css-sanitizer-key|String Content]]<br><i>Literals: </i>100, 200, 300, 400, 500, 600, 700, 800, 900, bold, bolder, lighter, large, larger, small, smaller, x-large, x-small, xx-large, xx-small, caption, icon, menu, message-box, small-caption, status-bar, cursive, fantasy, monospace, sans-serif, serif, italic, oblique, ",", "/", inherit, medium, normal, small-caps
 +
|-
 +
|font-family||[[{{FULLPAGENAME}}#css-sanitizer-key|String Content]]<br><i>Literals: </i>cursive, fantasy, monospace, sans-serif, serif, ",", inherit
 +
|-
 +
|font-size||[[{{FULLPAGENAME}}#css-sanitizer-key|Quantity]]<br><i>Literals: </i>large, larger, small, smaller, x-large, x-small, xx-large, xx-small, inherit, medium
 +
|-
 +
|font-stretch||<i>Literals: </i>condensed, expanded, extra-condensed, extra-expanded, narrower, semi-condensed, semi-expanded, ultra-condensed, ultra-expanded, wider, normal
 +
|-
 +
|font-style||<i>Literals: </i>italic, oblique, inherit, normal
 +
|-
 +
|font-variant||<i>Literals: </i>inherit, normal, small-caps
 +
|-
 +
|font-weight||<i>Literals: </i>100, 200, 300, 400, 500, 600, 700, 800, 900, bold, bolder, lighter, inherit, normal
 +
|-
 +
|height||[[{{FULLPAGENAME}}#css-sanitizer-key|Quantity]]<br>[[{{FULLPAGENAME}}#css-sanitizer-key|Negative Quantity]]<br><i>Literals: </i>auto, inherit
 +
|-
 +
|left||[[{{FULLPAGENAME}}#css-sanitizer-key|Quantity]]<br>[[{{FULLPAGENAME}}#css-sanitizer-key|Negative Quantity]]<br><i>Literals: </i>auto, inherit
 +
|-
 +
|letter-spacing||[[{{FULLPAGENAME}}#css-sanitizer-key|Quantity]]<br>[[{{FULLPAGENAME}}#css-sanitizer-key|Negative Quantity]]<br><i>Literals: </i>inherit, normal
 +
|-
 +
|line-height||[[{{FULLPAGENAME}}#css-sanitizer-key|Quantity]]<br><i>Literals: </i>inherit, normal
 +
|-
 +
|list-style||[[{{FULLPAGENAME}}#css-sanitizer-key|URL]]<br><i>Literals: </i>armenian, circle, decimal, decimal-leading-zero, disc, georgian, lower-alpha, lower-greek, lower-latin, lower-roman, square, upper-alpha, upper-latin, upper-roman, inside, outside, inherit, none
 +
|-
 +
|list-style-image||[[{{FULLPAGENAME}}#css-sanitizer-key|URL]]<br><i>Literals: </i>inherit, none
 +
|-
 +
|list-style-position||<i>Literals: </i>inside, outside, inherit
 +
|-
 +
|list-style-type||<i>Literals: </i>armenian, circle, decimal, decimal-leading-zero, disc, georgian, lower-alpha, lower-greek, lower-latin, lower-roman, square, upper-alpha, upper-latin, upper-roman, inherit, none
 +
|-
 +
|margin||[[{{FULLPAGENAME}}#css-sanitizer-key|Quantity]]<br>[[{{FULLPAGENAME}}#css-sanitizer-key|Negative Quantity]]<br><i>Literals: </i>auto, inherit
 +
|-
 +
|margin-bottom||[[{{FULLPAGENAME}}#css-sanitizer-key|Quantity]]<br>[[{{FULLPAGENAME}}#css-sanitizer-key|Negative Quantity]]<br><i>Literals: </i>auto, inherit
 +
|-
 +
|margin-left||[[{{FULLPAGENAME}}#css-sanitizer-key|Quantity]]<br>[[{{FULLPAGENAME}}#css-sanitizer-key|Negative Quantity]]<br><i>Literals: </i>auto, inherit
 +
|-
 +
|margin-right||[[{{FULLPAGENAME}}#css-sanitizer-key|Quantity]]<br>[[{{FULLPAGENAME}}#css-sanitizer-key|Negative Quantity]]<br><i>Literals: </i>auto, inherit
 +
|-
 +
|margin-top||[[{{FULLPAGENAME}}#css-sanitizer-key|Quantity]]<br>[[{{FULLPAGENAME}}#css-sanitizer-key|Negative Quantity]]<br><i>Literals: </i>auto, inherit
 +
|-
 +
|max-height||[[{{FULLPAGENAME}}#css-sanitizer-key|Quantity]]<br><i>Literals: </i>auto, inherit, none
 +
|-
 +
|max-width||[[{{FULLPAGENAME}}#css-sanitizer-key|Quantity]]<br><i>Literals: </i>auto, inherit, none
 +
|-
 +
|min-height||[[{{FULLPAGENAME}}#css-sanitizer-key|Quantity]]<br><i>Literals: </i>auto, inherit
 +
|-
 +
|min-width||[[{{FULLPAGENAME}}#css-sanitizer-key|Quantity]]<br><i>Literals: </i>auto, inherit
 +
|-
 +
|opacity||[[{{FULLPAGENAME}}#css-sanitizer-key|Quantity]]<br><i>Literals: </i>inherit
 +
|-
 +
|outline||[[{{FULLPAGENAME}}#css-sanitizer-key|Colors]]<br>[[{{FULLPAGENAME}}#css-sanitizer-key|Quantity]]<br>[[{{FULLPAGENAME}}#css-sanitizer-key|Negative Quantity]]<br><i>Literals: </i>dashed, dotted, double, groove, outset, ridge, solid, thick, thin, hidden, inherit, inset, invert, medium, none
 +
|-
 +
|outline-color||[[{{FULLPAGENAME}}#css-sanitizer-key|Colors]]<br><i>Literals: </i>inherit, invert
 +
|-
 +
|outline-style||<i>Literals: </i>dashed, dotted, double, groove, outset, ridge, solid, hidden, inherit, inset, none
 +
|-
 +
|outline-width||[[{{FULLPAGENAME}}#css-sanitizer-key|Quantity]]<br>[[{{FULLPAGENAME}}#css-sanitizer-key|Negative Quantity]]<br><i>Literals: </i>thick, thin, inherit, medium
 +
|-
 +
|overflow||<i>Literals: </i>auto, hidden, inherit, scroll, visible
 +
|-
 +
|overflow-x||<i>Literals: </i>no-content, no-display, auto, hidden, scroll, visible
 +
|-
 +
|overflow-y||<i>Literals: </i>no-content, no-display, auto, hidden, scroll, visible
 +
|-
 +
|padding||[[{{FULLPAGENAME}}#css-sanitizer-key|Quantity]]<br><i>Literals: </i>inherit
 +
|-
 +
|padding-bottom||[[{{FULLPAGENAME}}#css-sanitizer-key|Quantity]]<br><i>Literals: </i>inherit
 +
|-
 +
|padding-left||[[{{FULLPAGENAME}}#css-sanitizer-key|Quantity]]<br><i>Literals: </i>inherit
 +
|-
 +
|padding-right||[[{{FULLPAGENAME}}#css-sanitizer-key|Quantity]]<br><i>Literals: </i>inherit
 +
|-
 +
|padding-top||[[{{FULLPAGENAME}}#css-sanitizer-key|Quantity]]<br><i>Literals: </i>inherit
 +
|-
 +
|page-break-after||<i>Literals: </i>left, right, always, auto, avoid, inherit
 +
|-
 +
|page-break-before||<i>Literals: </i>left, right, always, auto, avoid, inherit
 +
|-
 +
|page-break-inside||<i>Literals: </i>auto, avoid, inherit
 +
|-
 +
|pause||[[{{FULLPAGENAME}}#css-sanitizer-key|Quantity]]<br>[[{{FULLPAGENAME}}#css-sanitizer-key|Negative Quantity]]<br><i>Literals: </i>inherit
 +
|-
 +
|pause-after||[[{{FULLPAGENAME}}#css-sanitizer-key|Quantity]]<br>[[{{FULLPAGENAME}}#css-sanitizer-key|Negative Quantity]]<br><i>Literals: </i>inherit
 +
|-
 +
|pause-before||[[{{FULLPAGENAME}}#css-sanitizer-key|Quantity]]<br>[[{{FULLPAGENAME}}#css-sanitizer-key|Negative Quantity]]<br><i>Literals: </i>inherit
 +
|-
 +
|pitch||[[{{FULLPAGENAME}}#css-sanitizer-key|Quantity]]<br>[[{{FULLPAGENAME}}#css-sanitizer-key|Negative Quantity]]<br><i>Literals: </i>high, low, x-high, x-low, inherit, medium
 +
|-
 +
|pitch-range||[[{{FULLPAGENAME}}#css-sanitizer-key|Quantity]]<br>[[{{FULLPAGENAME}}#css-sanitizer-key|Negative Quantity]]<br><i>Literals: </i>inherit
 +
|-
 +
|play-during||[[{{FULLPAGENAME}}#css-sanitizer-key|URL]]<br><i>Literals: </i>auto, inherit, mix, none, repeat
 +
|-
 +
|position||<i>Literals: </i>absolute, relative, static, inherit
 +
|-
 +
|quotes||[[{{FULLPAGENAME}}#css-sanitizer-key|String Content]]<br><i>Literals: </i>inherit, none
 +
|-
 +
|richness||[[{{FULLPAGENAME}}#css-sanitizer-key|Quantity]]<br>[[{{FULLPAGENAME}}#css-sanitizer-key|Negative Quantity]]<br><i>Literals: </i>inherit
 +
|-
 +
|right||[[{{FULLPAGENAME}}#css-sanitizer-key|Quantity]]<br>[[{{FULLPAGENAME}}#css-sanitizer-key|Negative Quantity]]<br><i>Literals: </i>auto, inherit
 +
|-
 +
|speak||<i>Literals: </i>inherit, none, normal, spell-out
 +
|-
 +
|speak-header||<i>Literals: </i>always, inherit, once
 +
|-
 +
|speak-numeral||<i>Literals: </i>continuous, digits, inherit
 +
|-
 +
|speak-punctuation||<i>Literals: </i>code, inherit, none
 +
|-
 +
|speech-rate||[[{{FULLPAGENAME}}#css-sanitizer-key|Quantity]]<br>[[{{FULLPAGENAME}}#css-sanitizer-key|Negative Quantity]]<br><i>Literals: </i>fast, faster, slow, slower, x-fast, x-slow, inherit, medium
 +
|-
 +
|stress||[[{{FULLPAGENAME}}#css-sanitizer-key|Quantity]]<br>[[{{FULLPAGENAME}}#css-sanitizer-key|Negative Quantity]]<br><i>Literals: </i>inherit
 +
|-
 +
|table-layout||<i>Literals: </i>auto, fixed, inherit
 +
|-
 +
|text-align||<i>Literals: </i>left, right, center, inherit, justify
 +
|-
 +
|text-decoration||<i>Literals: </i>blink, line-through, overline, underline, inherit, none
 +
|-
 +
|text-indent||[[{{FULLPAGENAME}}#css-sanitizer-key|Quantity]]<br>[[{{FULLPAGENAME}}#css-sanitizer-key|Negative Quantity]]<br><i>Literals: </i>inherit
 +
|-
 +
|text-overflow||<i>Literals: </i>clip, ellipsis
 +
|-
 +
|text-shadow||[[{{FULLPAGENAME}}#css-sanitizer-key|Colors]]<br>[[{{FULLPAGENAME}}#css-sanitizer-key|Quantity]]<br>[[{{FULLPAGENAME}}#css-sanitizer-key|Negative Quantity]]<br><i>Literals: </i>",", inset, none
 +
|-
 +
|text-transform||<i>Literals: </i>capitalize, lowercase, uppercase, inherit, none
 +
|-
 +
|text-wrap||<i>Literals: </i>suppress, unrestricted, none, normal
 +
|-
 +
|top||[[{{FULLPAGENAME}}#css-sanitizer-key|Quantity]]<br>[[{{FULLPAGENAME}}#css-sanitizer-key|Negative Quantity]]<br><i>Literals: </i>auto, inherit
 +
|-
 +
|unicode-bidi||<i>Literals: </i>bidi-override, embed, inherit, normal
 +
|-
 +
|vertical-align||[[{{FULLPAGENAME}}#css-sanitizer-key|Quantity]]<br>[[{{FULLPAGENAME}}#css-sanitizer-key|Negative Quantity]]<br><i>Literals: </i>baseline, middle, sub, super, text-bottom, text-top, bottom, top, inherit
 +
|-
 +
|visibility||<i>Literals: </i>collapse, hidden, inherit, visible
 +
|-
 +
|voice-family||[[{{FULLPAGENAME}}#css-sanitizer-key|String Content]]<br><i>Literals: </i>child, female, male, ",", inherit
 +
|-
 +
|volume||[[{{FULLPAGENAME}}#css-sanitizer-key|Quantity]]<br><i>Literals: </i>loud, silent, soft, x-loud, x-soft, inherit, medium
 +
|-
 +
|white-space||<i>Literals: </i>-moz-pre-wrap, -o-pre-wrap, -pre-wrap, nowrap, pre, pre-line, pre-wrap, inherit, normal
 +
|-
 +
|width||[[{{FULLPAGENAME}}#css-sanitizer-key|Quantity]]<br><i>Literals: </i>auto, inherit
 +
|-
 +
|word-spacing||[[{{FULLPAGENAME}}#css-sanitizer-key|Quantity]]<br>[[{{FULLPAGENAME}}#css-sanitizer-key|Negative Quantity]]<br><i>Literals: </i>inherit, normal
 +
|-
 +
|word-wrap||<i>Literals: </i>break-word, normal
 +
|-
 +
|z-index||[[{{FULLPAGENAME}}#css-sanitizer-key|Quantity]]<br>[[{{FULLPAGENAME}}#css-sanitizer-key|Negative Quantity]]<br>[[{{FULLPAGENAME}}#css-sanitizer-key|Z-Index]]<br><i>Literals: </i>auto, inherit
 +
|-
 +
|zoom||[[{{FULLPAGENAME}}#css-sanitizer-key|Quantity]]<br><i>Literals: </i>normal
 +
|}
 +
 
 +
{| class="wikitable mw-collapsible mw-collapsed" id="css-vendor-props"
 +
|+ class="nowrap" | CSS Vendor-Specific Properties
 +
!CSS Property!!Allowed Values
 +
|-
 +
| -moz-border-radius||[[{{FULLPAGENAME}}#css-sanitizer-key|Quantity]]<br>[[{{FULLPAGENAME}}#css-sanitizer-key|Negative Quantity]]<br><i>Literals: </i>"/"
 +
|-
 +
| -moz-border-radius-bottomleft||[[{{FULLPAGENAME}}#css-sanitizer-key|Quantity]]<br>[[{{FULLPAGENAME}}#css-sanitizer-key|Negative Quantity]]
 +
|-
 +
| -moz-border-radius-bottomright||[[{{FULLPAGENAME}}#css-sanitizer-key|Quantity]]<br>[[{{FULLPAGENAME}}#css-sanitizer-key|Negative Quantity]]
 +
|-
 +
| -moz-border-radius-topleft||[[{{FULLPAGENAME}}#css-sanitizer-key|Quantity]]<br>[[{{FULLPAGENAME}}#css-sanitizer-key|Negative Quantity]]
 +
|-
 +
| -moz-border-radius-topright||[[{{FULLPAGENAME}}#css-sanitizer-key|Quantity]]<br>[[{{FULLPAGENAME}}#css-sanitizer-key|Negative Quantity]]
 +
|-
 +
| -moz-box-shadow||[[{{FULLPAGENAME}}#css-sanitizer-key|Colors]]<br>[[{{FULLPAGENAME}}#css-sanitizer-key|Quantity]]<br>[[{{FULLPAGENAME}}#css-sanitizer-key|Negative Quantity]]<br><i>Literals: </i>",", inset, none
 +
|-
 +
| -moz-opacity||[[{{FULLPAGENAME}}#css-sanitizer-key|Quantity]]<br><i>Literals: </i>inherit
 +
|-
 +
| -moz-outline||[[{{FULLPAGENAME}}#css-sanitizer-key|Colors]]<br>[[{{FULLPAGENAME}}#css-sanitizer-key|Quantity]]<br>[[{{FULLPAGENAME}}#css-sanitizer-key|Negative Quantity]]<br><i>Literals: </i>dashed, dotted, double, groove, outset, ridge, solid, thick, thin, hidden, inherit, inset, invert, medium, none
 +
|-
 +
| -moz-outline-color||[[{{FULLPAGENAME}}#css-sanitizer-key|Colors]]<br><i>Literals: </i>inherit, invert
 +
|-
 +
| -moz-outline-style||<i>Literals: </i>dashed, dotted, double, groove, outset, ridge, solid, hidden, inherit, inset, none
 +
|-
 +
| -moz-outline-width||[[{{FULLPAGENAME}}#css-sanitizer-key|Quantity]]<br>[[{{FULLPAGENAME}}#css-sanitizer-key|Negative Quantity]]<br><i>Literals: </i>thick, thin, inherit, medium
 +
|-
 +
| -o-text-overflow||<i>Literals: </i>clip, ellipsis
 +
|-
 +
| -webkit-border-bottom-left-radius||[[{{FULLPAGENAME}}#css-sanitizer-key|Quantity]]<br>[[{{FULLPAGENAME}}#css-sanitizer-key|Negative Quantity]]
 +
|-
 +
| -webkit-border-bottom-right-radius||[[{{FULLPAGENAME}}#css-sanitizer-key|Quantity]]<br>[[{{FULLPAGENAME}}#css-sanitizer-key|Negative Quantity]]
 +
|-
 +
| -webkit-border-radius||[[{{FULLPAGENAME}}#css-sanitizer-key|Quantity]]<br>[[{{FULLPAGENAME}}#css-sanitizer-key|Negative Quantity]]<br><i>Literals: </i>"/"
 +
|-
 +
| -webkit-border-radius-bottom-left||[[{{FULLPAGENAME}}#css-sanitizer-key|Quantity]]<br>[[{{FULLPAGENAME}}#css-sanitizer-key|Negative Quantity]]
 +
|-
 +
| -webkit-border-radius-bottom-right||[[{{FULLPAGENAME}}#css-sanitizer-key|Quantity]]<br>[[{{FULLPAGENAME}}#css-sanitizer-key|Negative Quantity]]
 +
|-
 +
| -webkit-border-radius-top-left||[[{{FULLPAGENAME}}#css-sanitizer-key|Quantity]]<br>[[{{FULLPAGENAME}}#css-sanitizer-key|Negative Quantity]]
 +
|-
 +
| -webkit-border-radius-top-right||[[{{FULLPAGENAME}}#css-sanitizer-key|Quantity]]<br>[[{{FULLPAGENAME}}#css-sanitizer-key|Negative Quantity]]
 +
|-
 +
| -webkit-border-top-left-radius||[[{{FULLPAGENAME}}#css-sanitizer-key|Quantity]]<br>[[{{FULLPAGENAME}}#css-sanitizer-key|Negative Quantity]]
 +
|-
 +
| -webkit-border-top-right-radius||[[{{FULLPAGENAME}}#css-sanitizer-key|Quantity]]<br>[[{{FULLPAGENAME}}#css-sanitizer-key|Negative Quantity]]
 +
|-
 +
| -webkit-box-shadow||[[{{FULLPAGENAME}}#css-sanitizer-key|Colors]]<br>[[{{FULLPAGENAME}}#css-sanitizer-key|Quantity]]<br>[[{{FULLPAGENAME}}#css-sanitizer-key|Negative Quantity]]<br><i>Literals: </i>",", inset, none
 +
|}
 +
<br><br>
 +
<code style="font-size: 1.1em;font-weight:bold;">callback</code> is an optional third parameter consisting of a callback function which will be passed the results of the <code>sendChat()</code> call instead of sending the commands to the game. Using <code>sendChat()</code> in this way is asynchronous.  The results of the <code>sendChat()</code> command will be an ARRAY of operations, and each individual object will be just like an object you receive during a <code>chat:message</code> event (see above).
  
 
You can use this, for example, to perform a roll using the Roll20 roll engine, then get the results of the roll immediately. You could then perform additional modifications to the roll before sending it to the players in the game.  
 
You can use this, for example, to perform a roll using the Roll20 roll engine, then get the results of the roll immediately. You could then perform additional modifications to the roll before sending it to the players in the game.  
Line 231: Line 561:
 
     //Now do something with rollresult, just like you would during a chat:message event...
 
     //Now do something with rollresult, just like you would during a chat:message event...
 
});
 
});
 +
</pre>
 +
 +
<code style="font-size: 1.1em;font-weight:bold;">options</code>is an optional fourth parameter to set options for how the message is handled.  Options are specified as a javascript object with who's properties are the names of the options to set and whose values are the settings for them, generally <code>true</code> as they default to false.
 +
 +
Available options:
 +
* <code>noarchive</code> -- set this to true to prevent the message from being stored in the chat log.  This is particularly useful for output that is not part of the story, such as API Button menus and state information.
 +
 +
* <code>use3d</code> -- You can now generate [[3D Dice]] rolls using the sendChat() function. The syntax is simply: <code>sendChat("Name", "Rolling <nowiki>[[3d6]]</nowiki>", null, {use3d: true});</code> If you pass a player ID to the name parameter, such as <code>sendChat("player|-ABC123",...)</code> the player's color will be used for the dice. Otherwise a default white color will be used. <br>'''Note:''' Clients can only show the result of one 3D roll at a time, so making a bunch of separate 3D rolls in a row is not useful. Also note that using 3D rolls does place a bit more strain on the [[QuantumRoll]] server, so use your judgement and don't perform 100 3D rolls in the space of a second. Use 3D rolls when the roll will "matter" to the player and make an impact on the game.  '''Warning:''' The use3d parameter does not seem to be working as of July 2021, c.f.: https://app.roll20.net/forum/post/9017606/slug%7D.
 +
 +
If you want to adjust these options but do not want to use a <code>callback</code> parameter (third parameter--see above), you can simply pass <code>null</code> in it's place:
 +
<pre data-language="javascript">
 +
sendChat("Status", "All players are logged in.", null, {noarchive:true} );
 
</pre>
 
</pre>
  
 
===API Command Buttons===
 
===API Command Buttons===
 +
{{main|Complete Guide to Macros & Rolls}}
  
Now available with the Update of Holding you can take advantage of the new text chat formatting (in both your API-generated messages and those generated by macros and abilities) to create "API command buttons" in the chat.  
+
You can take advantage of the {{Text Chat}}-formatting (in both your API-generated messages and those generated by macros and abilities) to create "API command buttons" in the chat.  
  
 
[[File:API_Button.png|right]]
 
[[File:API_Button.png|right]]
Line 243: Line 586:
 
<code>[Attack Roll](!attackroll)</code>
 
<code>[Attack Roll](!attackroll)</code>
  
The text in between the brackets will show up in the button, and part in the parentheses is the command to be executed. You can include anything in a normal roll (macros, abilities, queries, etc.), but keep in mind that the command itself will be executed by the player who clicks on it. For example, don't include @{Character|AC} if everyone who can see the message can't access that character. Instead, include the actual value as it existed when you sent the command by filling it in yourself before you send the chat message. These buttons will work in all message types, general messages, whispers, gmwhispers, etc.
+
The text in between the brackets will show up in the button, and part in the parentheses is the command to be executed. You can include anything in a normal roll (macros, abilities, queries, etc.), but keep in mind that the command itself will be executed by the player who clicks on it. For example, don't include <code>@{Character|AC}</code> if everyone who can see the message can't access that character. Instead, include the actual value as it existed when you sent the command by filling it in yourself before you send the chat message. These buttons will work in all message types, general messages, whispers, gmwhispers, etc.
  
 
Note that if you use /direct to send a message, we won't do any Markdown parsing on it, so you need to include your own <a> tags. Here's an example of that:
 
Note that if you use /direct to send a message, we won't do any Markdown parsing on it, so you need to include your own <a> tags. Here's an example of that:
Line 249: Line 592:
 
<code><a href="!attackroll">Attack Roll</a></code>
 
<code><a href="!attackroll">Attack Roll</a></code>
  
[[Category:API|Chat]]
+
====Entering API Buttons In Chat====
 +
You can also type Markdown syntax API buttons into chat for others to use.  Because they will be interpreted by the chat parser, if you want attributes, queries and rolls to be expanded when the button is clicked, you must enter parts of the command with a special syntax ([[HTML Entities]]):
 +
 +
{| class="wikitable"
 +
|-
 +
! Character !! Replacement
 +
|-
 +
| % || &amp;#37;
 +
|-
 +
| ) || &amp;#41;
 +
|-
 +
| ? || &amp;#63;
 +
|-
 +
| @ || &amp;#64;
 +
|-
 +
| [ || &amp;#91; or &amp;lbrack;
 +
|-
 +
| ] || &amp;#93; or &amp;rbrack;
 +
|}
 +
 
 +
This sample button uses some of them:
 +
 
 +
<code>[Attack Roll](!attackroll &amp;#64;{target|token_id} &amp;#91;[1d6+&amp;#63;{Bonus|0}]&amp;#93;)</code>
 +
 
 +
You can actually use the API Buttons to call Macros or Abilities.
 +
{| class="wikitable"
 +
|-
 +
! Character !! Replacement
 +
|-
 +
| <carriage return> || &amp;#13;
 +
|}
 +
 
 +
To do so, you simply begin the command portion with the special code <code>!&amp;#13;</code> then add the macro call with <code>#</code> or the ability call with <code>&amp;#37;</code> (<code>%</code>):
 +
 
 +
<code>[Macro](!&amp;#13;#MacroName)</code>
 +
 
 +
<code>[Ability](!&amp;#13;&amp;#37;{CharName|AbilityName})</code>
 +
 
 +
'''Note:''' At this time, reopening a [[Macro]] saved under the {{Collections}}-tab of the [[Sidebar]] causes HTML entities within to be reverted; if the Macro is then saved, so are those reversions. This behavior is not present within [[Journal#Abilities|Abilities]] or Ability Command Buttons.
 +
 
 +
For [[Macros#Ability_Command_Buttons|Ability Command Buttons]], if the Ability that creates the button and the Ability it references are both on the same sheet, the syntax is very simple:
 +
 
 +
<code>[Ability](~AbilityName)</code>
 +
 
 +
====More====
 +
* [https://app.roll20.net/forum/post/10798001/looking-for-workaround-special-characters-in-api-buttons looking-for-workaround-special-characters-in-api-buttons April 2022]
 +
 
 +
==See Also==
 +
* {{Text Chat}}
 +
* [[Chat Menus]]
 +
* [[Complete Macro Guide]]
 +
 
 +
[[Category:API Development]]

Latest revision as of 08:35, 9 June 2024

Attention: This page is community-maintained. For the official Roll20 version of this article, see the Help Center for assistance: Here .

Contents

[edit] Chat Events

chat:message

Triggered whenever a new chat message is received. Note that if the message is of type rollresult or gmrollresult, you will need to call JSON.parse() on the content of the message to get an object which contains information on the roll results.

Note: If a player enters a chat message beginning with an exclamation mark (!), that message will have the type of "api" and not be shown to anyone. It's intended that this functionality can be used to provide commands that Mod scripts respond to. So, if the message is of type "api", then it hasn't been shown to anyone, and the player who sent the chat message is probably expecting an Mod script to do something as a result of the message.

Callback parameter:

Property Default Value Notes
who "" The display name of the player or character that sent the message.
playerid The ID of the player that sent the message.
type "general" One of "general", "rollresult", "gmrollresult", "emote", "whisper", "desc", or "api".
content "" The contents of the chat message. If type is "rollresult", this will be a JSON string of data about the roll.
origRoll (type "rollresult" or "gmrollresult" only) The original text of the roll, eg: 2d10+5 fire damage when the player types /r 2d10+5 fire damage. This is equivalent to the use of content on messages with types other than "rollresult" or "gmrollresult".
inlinerolls (content contains one or more inline rolls only) An array of objects containing information about all inline rolls in the message.
rolltemplate (content contains one or more roll templates only) The name of the template specified.
target (type "whisper" only) The player ID of the person the whisper is sent to. If the whisper was sent to the GM without using his or her display name (ie, /w gm text instead of /w Riley text when Riley is the GM), or if the whisper was sent to a character without any controlling players, the value will be "gm".
target_name (type "whisper" only) The display name of the player or character the whisper was sent to.
selected (type "api" only) An array of objects the user had selected when the command was entered.


Note: You probably don't need all of this information. In most cases you'll only be interested in the overall result of the roll (see the bottom of the first example). However all of it is provided if you want to really dig deeper into the results of a roll.

Roll Result Structure Example 1

After you call JSON.parse on the content property of a "rollresult" or "gmrollresult" message, you'll get an object with the following format (this is the result from the command /roll {2d6}+5+1t[weather] Attack!)

{
  "type":"V", //"V" = "Validated Roll" (this will always be "V" right now)
  "rolls": [
    {
      "type":"G", //"G" indicates a grouped roll. A group is like a series of "sub-rolls" within a roll.
      "rolls": [
        [
          {
            "type":"R", //"R" = "Roll"
            "dice":2, // Number of dice rolled (2dX means 2 dice)
            "sides":6, //Number of sides for the dice (Xd6 means 6 sides)
            "mods":{},
            "results": [ //An array of the results of each roll.
             {
               "v":1 // We rolled a 1 for our first 2d6
             },
             {
               "v":5 //We rolled a 5 for our second 2d6
             }
            ]
          }
        ]
      ],
      "mods":{},
      "resultType":"sum", //The result is a sum (as opposed to a success check)
      "results": [
        {
          "v":6 // In this case, the overall result (total) of the group.
        }
      ]
    },
    {
      "type":"M", //"M" = Math Expression
      "expr":"+5+"
    },
    {
      "type":"R", //"R" = Roll
      "dice":1,
      "table":"weather", //The table property is set to the name of the table used if this roll was made against a table
      "mods":{},
      "sides":2, //You can probably just ignore this for table rolls.
      "results": [
        {
          "v":0, //The "value" of the table item rolled. For text tables this is always 0.
          "tableidx":1, //The index of the item in the table that was rolled.
          "tableItem": { //A copy of the table item object as it existed when the table was rolled.
            "name":"rainy", 
            "avatar":"", //This will be a URL to an image if the rollable table uses image icons
            "weight":1,
            "id":"-IpzPx2j_9piP09ceyOv"
          }
        }
      ]
    },
    {
      "type":"C", // "C" = Comment
      "text":" Attack!"
    }
  ],
  "resultType":"sum", //The overall result type of the entire roll
  "total":11 // The overall total of the entire roll (including all sub-groups)
}

Roll Result Structure Example 2

An annotated structure for the result of /roll {1d6!!>5}>6 (showing exploding modifications and target successes):

{
  "type":"V",
  "rolls": [
    {
      "type":"G",
      "rolls": [
        [
          {
            "type":"R",
            "dice":1,
            "sides":6,
            "mods": { //Modifications to the roll
              "compounding": { //"compounding" = "Compounding exploding (!!)"
                "comp":">=", //Comparison type
                "point":5 //Comparison point
              }
            },
            "results": [
              {
                "v":13 //Overall dice result. Note that since this is compounding exploding there is only one dice result.
              }
            ]
          }
        ]
      ],
      "mods": {
        "success": {
          "comp":">=",
          "point":6
        }
      },
      "resultType":"sum",
      "results": [
        {
          "v":13
        }
      ]
    }
  ],
  "resultType":"success", // In this case, the result is a count of successes
  "total":1 //Total number of successes
}

Chat Event Example (Implementing Custom Roll Type)

on("chat:message", function(msg) {
  //This allows players to enter !sr <number> to roll a number of d6 dice with a target of 4.
  if(msg.type == "api" && msg.content.indexOf("!sr ") !== -1) {
    var numdice = msg.content.replace("!sr ", "");
    sendChat(msg.who, "/roll " + numdice + "d6>4");
  }
});

[edit] sendChat(speakingAs, input [,callback [, options]] ) [Asynchronous]

You can use this function to send a chat message.

speakingAs can be one of:

  • Any string, in which case that will be used as the name of the person who sent the message. E.g. "Riley"
  • A player's ID, formatted as "player|-Abc123" where -Abc123 is the ID of the player. If you do this it will automatically use the avatar and name of the player.
  • A character's ID, formatted as "character|-Abc123". If you do this it will automatically use the avatar and name of the Character.


input should be any valid expression just like the ones used in the Roll20 App. You enter text to send a basic message, or use slash-commands such as /roll, /em, /w, etc. In addition:

  • You can use Character#Attributes with the format @{CharacterName|AttributeName}.
  • You can use Character#Abilities with the format: %{CharacterName|AbilityName}.
  • You cannot use macros.
  • You can use the "/direct <msg>" command to send a message without any processing (e.g. autolinking of URLs), and you can use the following HTML tags in the message:
    <code><span><div><label><a><br><br /><p><b><i><del><strike><u><img><blockquote><mark><cite><small><ul><ol><li><hr><dl><dt><dd><sup><sub><big>
    <pre><figure><figcaption><strong><em><table><tr><td><th><tbody><thead><tfoot><h1><h2><h3><h4><h5><h6>
  • You can use a whitelisted set of inline CSS styles. The following tables list the full set of allowed properties and values:
CSS Value Types Key
Category Description Examples
Colors Accepted format for colors is any of the following:
  • rgb(x,y,z) - percentage or numeric
  • rgba(x,y,z,a) - percentage or numeric
  • hex - 3 or 6 alpha-numeric characters
  • literal - any of the following color literals may be used:
    aliceblue, antiquewhite, aqua, aquamarine, azure, beige, bisque, black, blanchedalmond, blue, blueviolet, brown, burlywood, cadetblue, chartreuse, chocolate, coral, cornflowerblue, cornsilk, crimson, cyan, darkblue, darkcyan, darkgoldenrod, darkgray, darkgreen, darkkhaki, darkmagenta, darkolivegreen, darkorange, darkorchid, darkred, darksalmon, darkseagreen, darkslateblue, darkslategray, darkturquoise, darkviolet, deeppink, deepskyblue, dimgray, dodgerblue, firebrick, floralwhite, forestgreen, fuchsia, gainsboro, ghostwhite, gold, goldenrod, gray, green, greenyellow, honeydew, hotpink, indianred, indigo, ivory, khaki, lavender, lavenderblush, lawngreen, lemonchiffon, lightblue, lightcoral, lightcyan, lightgoldenrodyellow, lightgreen, lightgrey, lightpink, lightsalmon, lightseagreen, lightskyblue, lightslategray, lightsteelblue, lightyellow, lime, limegreen, linen, magenta, maroon, mediumaquamarine, mediumblue, mediumorchid, mediumpurple, mediumseagreen, mediumslateblue, mediumspringgreen, mediumturquoise, mediumvioletred, midnightblue, mintcream, mistyrose, moccasin, navajowhite, navy, oldlace, olive, olivedrab, orange, orangered, orchid, palegoldenrod, palegreen, paleturquoise, palevioletred, papayawhip, peachpuff, peru, pink, plum, powderblue, purple, red, rosybrown, royalblue, saddlebrown, salmon, sandybrown, seagreen, seashell, sienna, silver, skyblue, slateblue, slategray, snow, springgreen, steelblue, tan, teal, thistle, tomato, turquoise, violet, wheat, white, whitesmoke, yellow, yellowgreen
color: rgb(10,255,10)
color: rgba(50%,50%,50%,0%)
color: #aa99cc
color: aliceblue
Quantity A positive number - integer or float. Must start with a digit, but can be suffixed with non-number word characters like rem/px/pt border-radius: 5px
font-size: 5.5rem
Negative Quantity The same as Quantity, but with a leading "-". No whitespace is allowed between the negative sign and the digits. margin-left: -5px
URL Accepts a web URL using http:// or https:// - the resulting URL will be sanitized run through imgsrv.roll20.net background: url(https://app.roll20.net/v2/images/roll20-logo.png)
String Content Rarely used, this allows most word characters through in the value. Still sanitized to remove any control characters, though. Strips any apostrophes and quotes from the ends and wraps the result in "quotations" font: this font doesnt exist (passes the sanitizer but doesn't achieve anything)
Z-Index Any integer containing 1 to 7 digits. Only used for the z-index property itself z-index: 1234567
CSS Standard Properties
CSS Property Allowed Values
azimuth Quantity
Negative Quantity
Literals: behind, center-left, center-right, far-left, far-right, left-side, leftwards, right-side, rightwards, left, right, center, inherit
background Colors
Quantity
Negative Quantity
URL
Literals: border-box, contain, content-box, cover, padding-box, no-repeat, repeat-x, repeat-y, round, space, bottom, top, left, right, ",", "/", auto, center, fixed, inherit, local, none, repeat, scroll, transparent
background-size Colors
Quantity
Negative Quantity
URL
Literals: border-box, contain, content-box, cover, padding-box, no-repeat, repeat-x, repeat-y, round, space, bottom, top, left, right, ",", "/", auto, center, fixed, inherit, local, none, repeat, scroll, transparent
background-attachment Literals: ",", fixed, local, scroll
background-color Colors
Literals: inherit, transparent
background-image URL
Literals: ",", none
background-position Quantity
Negative Quantity
Literals: bottom, top, left, right, ",", center
background-repeat Literals: no-repeat, repeat-x, repeat-y, round, space, ",", repeat
border Colors
Quantity
Negative Quantity
Literals: dashed, dotted, double, groove, outset, ridge, solid, thick, thin, hidden, inherit, inset, medium, none, transparent
border-bottom Colors
Quantity
Negative Quantity
Literals: dashed, dotted, double, groove, outset, ridge, solid, thick, thin, hidden, inherit, inset, medium, none, transparent
border-bottom-color Colors
Literals: inherit, transparent
border-bottom-left-radius Quantity
Negative Quantity
border-bottom-right-radius Quantity
Negative Quantity
border-bottom-style Literals: dashed, dotted, double, groove, outset, ridge, solid, hidden, inherit, inset, none
border-bottom-width Quantity
Negative Quantity
Literals: thick, thin, inherit, medium
border-collapse Literals: collapse, inherit, separate
border-color Colors
Literals: inherit, transparent
border-left Colors
Quantity
Negative Quantity
Literals: dashed, dotted, double, groove, outset, ridge, solid, thick, thin, hidden, inherit, inset, medium, none, transparent
border-left-color Colors
Literals: inherit, transparent
border-left-style Literals: dashed, dotted, double, groove, outset, ridge, solid, hidden, inherit, inset, none
border-left-width Quantity
Negative Quantity
Literals: thick, thin, inherit, medium
border-radius Quantity
Negative Quantity
Literals: "/"
border-right Colors
Quantity
Negative Quantity
Literals: dashed, dotted, double, groove, outset, ridge, solid, thick, thin, hidden, inherit, inset, medium, none, transparent
border-right-color Colors
Literals: inherit, transparent
border-right-style Literals: dashed, dotted, double, groove, outset, ridge, solid, hidden, inherit, inset, none
border-right-width Quantity
Negative Quantity
Literals: thick, thin, inherit, medium
border-spacing Quantity
Negative Quantity
Literals: inherit
border-style Literals: dashed, dotted, double, groove, outset, ridge, solid, hidden, inherit, inset, none
border-top Colors
Quantity
Negative Quantity
Literals: dashed, dotted, double, groove, outset, ridge, solid, thick, thin, hidden, inherit, inset, medium, none, transparent
border-top-color Colors
Literals: inherit, transparent
border-top-left-radius Quantity
Negative Quantity
border-top-right-radius Quantity
Negative Quantity
border-top-style Literals: dashed, dotted, double, groove, outset, ridge, solid, hidden, inherit, inset, none
border-top-width Quantity
Negative Quantity
Literals: thick, thin, inherit, medium
border-width Quantity
Negative Quantity
Literals: thick, thin, inherit, medium
bottom Quantity
Negative Quantity
Literals: auto, inherit
box-shadow Colors
Quantity
Negative Quantity
Literals: ",", inset, none
caption-side Literals: bottom, top, inherit
clear Literals: left, right, both, inherit, none
clip Literals: auto, inherit
color Colors
Literals: inherit
content String Content
Literals: none, normal
counter-increment Quantity
Negative Quantity
Literals: inherit, none
counter-reset Quantity
Negative Quantity
Literals: inherit, none
cue URL
Literals: inherit, none
cue-after URL
Literals: inherit, none
cue-before URL
Literals: inherit, none
cursor URL
Literals: all-scroll, col-resize, crosshair, default, e-resize, hand, help, move, n-resize, ne-resize, no-drop, not-allowed, nw-resize, pointer, progress, row-resize, s-resize, se-resize, sw-resize, text, vertical-text, w-resize, wait, ",", auto, inherit
direction Literals: ltr, rtl, inherit
display Literals: -moz-inline-box, -moz-inline-stack, block, inline, inline-block, inline-table, list-item, run-in, table, table-caption, table-cell, table-column, table-column-group, table-footer-group, table-header-group, table-row, table-row-group, inherit, none
elevation Quantity
Negative Quantity
Literals: above, below, higher, level, lower, inherit
empty-cells Literals: hide, show, inherit
filter -
float Literals: left, right, inherit, none
font Quantity
String Content
Literals: 100, 200, 300, 400, 500, 600, 700, 800, 900, bold, bolder, lighter, large, larger, small, smaller, x-large, x-small, xx-large, xx-small, caption, icon, menu, message-box, small-caption, status-bar, cursive, fantasy, monospace, sans-serif, serif, italic, oblique, ",", "/", inherit, medium, normal, small-caps
font-family String Content
Literals: cursive, fantasy, monospace, sans-serif, serif, ",", inherit
font-size Quantity
Literals: large, larger, small, smaller, x-large, x-small, xx-large, xx-small, inherit, medium
font-stretch Literals: condensed, expanded, extra-condensed, extra-expanded, narrower, semi-condensed, semi-expanded, ultra-condensed, ultra-expanded, wider, normal
font-style Literals: italic, oblique, inherit, normal
font-variant Literals: inherit, normal, small-caps
font-weight Literals: 100, 200, 300, 400, 500, 600, 700, 800, 900, bold, bolder, lighter, inherit, normal
height Quantity
Negative Quantity
Literals: auto, inherit
left Quantity
Negative Quantity
Literals: auto, inherit
letter-spacing Quantity
Negative Quantity
Literals: inherit, normal
line-height Quantity
Literals: inherit, normal
list-style URL
Literals: armenian, circle, decimal, decimal-leading-zero, disc, georgian, lower-alpha, lower-greek, lower-latin, lower-roman, square, upper-alpha, upper-latin, upper-roman, inside, outside, inherit, none
list-style-image URL
Literals: inherit, none
list-style-position Literals: inside, outside, inherit
list-style-type Literals: armenian, circle, decimal, decimal-leading-zero, disc, georgian, lower-alpha, lower-greek, lower-latin, lower-roman, square, upper-alpha, upper-latin, upper-roman, inherit, none
margin Quantity
Negative Quantity
Literals: auto, inherit
margin-bottom Quantity
Negative Quantity
Literals: auto, inherit
margin-left Quantity
Negative Quantity
Literals: auto, inherit
margin-right Quantity
Negative Quantity
Literals: auto, inherit
margin-top Quantity
Negative Quantity
Literals: auto, inherit
max-height Quantity
Literals: auto, inherit, none
max-width Quantity
Literals: auto, inherit, none
min-height Quantity
Literals: auto, inherit
min-width Quantity
Literals: auto, inherit
opacity Quantity
Literals: inherit
outline Colors
Quantity
Negative Quantity
Literals: dashed, dotted, double, groove, outset, ridge, solid, thick, thin, hidden, inherit, inset, invert, medium, none
outline-color Colors
Literals: inherit, invert
outline-style Literals: dashed, dotted, double, groove, outset, ridge, solid, hidden, inherit, inset, none
outline-width Quantity
Negative Quantity
Literals: thick, thin, inherit, medium
overflow Literals: auto, hidden, inherit, scroll, visible
overflow-x Literals: no-content, no-display, auto, hidden, scroll, visible
overflow-y Literals: no-content, no-display, auto, hidden, scroll, visible
padding Quantity
Literals: inherit
padding-bottom Quantity
Literals: inherit
padding-left Quantity
Literals: inherit
padding-right Quantity
Literals: inherit
padding-top Quantity
Literals: inherit
page-break-after Literals: left, right, always, auto, avoid, inherit
page-break-before Literals: left, right, always, auto, avoid, inherit
page-break-inside Literals: auto, avoid, inherit
pause Quantity
Negative Quantity
Literals: inherit
pause-after Quantity
Negative Quantity
Literals: inherit
pause-before Quantity
Negative Quantity
Literals: inherit
pitch Quantity
Negative Quantity
Literals: high, low, x-high, x-low, inherit, medium
pitch-range Quantity
Negative Quantity
Literals: inherit
play-during URL
Literals: auto, inherit, mix, none, repeat
position Literals: absolute, relative, static, inherit
quotes String Content
Literals: inherit, none
richness Quantity
Negative Quantity
Literals: inherit
right Quantity
Negative Quantity
Literals: auto, inherit
speak Literals: inherit, none, normal, spell-out
speak-header Literals: always, inherit, once
speak-numeral Literals: continuous, digits, inherit
speak-punctuation Literals: code, inherit, none
speech-rate Quantity
Negative Quantity
Literals: fast, faster, slow, slower, x-fast, x-slow, inherit, medium
stress Quantity
Negative Quantity
Literals: inherit
table-layout Literals: auto, fixed, inherit
text-align Literals: left, right, center, inherit, justify
text-decoration Literals: blink, line-through, overline, underline, inherit, none
text-indent Quantity
Negative Quantity
Literals: inherit
text-overflow Literals: clip, ellipsis
text-shadow Colors
Quantity
Negative Quantity
Literals: ",", inset, none
text-transform Literals: capitalize, lowercase, uppercase, inherit, none
text-wrap Literals: suppress, unrestricted, none, normal
top Quantity
Negative Quantity
Literals: auto, inherit
unicode-bidi Literals: bidi-override, embed, inherit, normal
vertical-align Quantity
Negative Quantity
Literals: baseline, middle, sub, super, text-bottom, text-top, bottom, top, inherit
visibility Literals: collapse, hidden, inherit, visible
voice-family String Content
Literals: child, female, male, ",", inherit
volume Quantity
Literals: loud, silent, soft, x-loud, x-soft, inherit, medium
white-space Literals: -moz-pre-wrap, -o-pre-wrap, -pre-wrap, nowrap, pre, pre-line, pre-wrap, inherit, normal
width Quantity
Literals: auto, inherit
word-spacing Quantity
Negative Quantity
Literals: inherit, normal
word-wrap Literals: break-word, normal
z-index Quantity
Negative Quantity
Z-Index
Literals: auto, inherit
zoom Quantity
Literals: normal
CSS Vendor-Specific Properties
CSS Property Allowed Values
-moz-border-radius Quantity
Negative Quantity
Literals: "/"
-moz-border-radius-bottomleft Quantity
Negative Quantity
-moz-border-radius-bottomright Quantity
Negative Quantity
-moz-border-radius-topleft Quantity
Negative Quantity
-moz-border-radius-topright Quantity
Negative Quantity
-moz-box-shadow Colors
Quantity
Negative Quantity
Literals: ",", inset, none
-moz-opacity Quantity
Literals: inherit
-moz-outline Colors
Quantity
Negative Quantity
Literals: dashed, dotted, double, groove, outset, ridge, solid, thick, thin, hidden, inherit, inset, invert, medium, none
-moz-outline-color Colors
Literals: inherit, invert
-moz-outline-style Literals: dashed, dotted, double, groove, outset, ridge, solid, hidden, inherit, inset, none
-moz-outline-width Quantity
Negative Quantity
Literals: thick, thin, inherit, medium
-o-text-overflow Literals: clip, ellipsis
-webkit-border-bottom-left-radius Quantity
Negative Quantity
-webkit-border-bottom-right-radius Quantity
Negative Quantity
-webkit-border-radius Quantity
Negative Quantity
Literals: "/"
-webkit-border-radius-bottom-left Quantity
Negative Quantity
-webkit-border-radius-bottom-right Quantity
Negative Quantity
-webkit-border-radius-top-left Quantity
Negative Quantity
-webkit-border-radius-top-right Quantity
Negative Quantity
-webkit-border-top-left-radius Quantity
Negative Quantity
-webkit-border-top-right-radius Quantity
Negative Quantity
-webkit-box-shadow Colors
Quantity
Negative Quantity
Literals: ",", inset, none



callback is an optional third parameter consisting of a callback function which will be passed the results of the sendChat() call instead of sending the commands to the game. Using sendChat() in this way is asynchronous. The results of the sendChat() command will be an ARRAY of operations, and each individual object will be just like an object you receive during a chat:message event (see above).

You can use this, for example, to perform a roll using the Roll20 roll engine, then get the results of the roll immediately. You could then perform additional modifications to the roll before sending it to the players in the game.

sendChat("Riley", "/roll 1d20+4", function(ops) {
    // ops will be an ARRAY of command results.
    var rollresult = ops[0];
    //Now do something with rollresult, just like you would during a chat:message event...
});

optionsis an optional fourth parameter to set options for how the message is handled. Options are specified as a javascript object with who's properties are the names of the options to set and whose values are the settings for them, generally true as they default to false.

Available options:

  • noarchive -- set this to true to prevent the message from being stored in the chat log. This is particularly useful for output that is not part of the story, such as API Button menus and state information.
  • use3d -- You can now generate 3D Dice rolls using the sendChat() function. The syntax is simply: sendChat("Name", "Rolling [[3d6]]", null, {use3d: true}); If you pass a player ID to the name parameter, such as sendChat("player|-ABC123",...) the player's color will be used for the dice. Otherwise a default white color will be used.
    Note: Clients can only show the result of one 3D roll at a time, so making a bunch of separate 3D rolls in a row is not useful. Also note that using 3D rolls does place a bit more strain on the QuantumRoll server, so use your judgement and don't perform 100 3D rolls in the space of a second. Use 3D rolls when the roll will "matter" to the player and make an impact on the game. Warning: The use3d parameter does not seem to be working as of July 2021, c.f.: https://app.roll20.net/forum/post/9017606/slug%7D.

If you want to adjust these options but do not want to use a callback parameter (third parameter--see above), you can simply pass null in it's place:

sendChat("Status", "All players are logged in.", null, {noarchive:true} );

[edit] API Command Buttons

Main Page: Complete Guide to Macros & Rolls

You can take advantage of the q Text Chat-formatting (in both your API-generated messages and those generated by macros and abilities) to create "API command buttons" in the chat.

API Button.png

To do so using Markdown formatting:

[Attack Roll](!attackroll)

The text in between the brackets will show up in the button, and part in the parentheses is the command to be executed. You can include anything in a normal roll (macros, abilities, queries, etc.), but keep in mind that the command itself will be executed by the player who clicks on it. For example, don't include @{Character|AC} if everyone who can see the message can't access that character. Instead, include the actual value as it existed when you sent the command by filling it in yourself before you send the chat message. These buttons will work in all message types, general messages, whispers, gmwhispers, etc.

Note that if you use /direct to send a message, we won't do any Markdown parsing on it, so you need to include your own <a> tags. Here's an example of that:

<a href="!attackroll">Attack Roll</a>

[edit] Entering API Buttons In Chat

You can also type Markdown syntax API buttons into chat for others to use. Because they will be interpreted by the chat parser, if you want attributes, queries and rolls to be expanded when the button is clicked, you must enter parts of the command with a special syntax (HTML Entities):

Character Replacement
 % &#37;
) &#41;
 ? &#63;
@ &#64;
[ &#91; or &lbrack;
] &#93; or &rbrack;

This sample button uses some of them:

[Attack Roll](!attackroll &#64;{target|token_id} &#91;[1d6+&#63;{Bonus|0}]&#93;)

You can actually use the API Buttons to call Macros or Abilities.

Character Replacement
<carriage return> &#13;

To do so, you simply begin the command portion with the special code !&#13; then add the macro call with # or the ability call with &#37; (%):

[Macro](!&#13;#MacroName)

[Ability](!&#13;&#37;{CharName|AbilityName})

Note: At this time, reopening a Macro saved under the l Collections-tab of the Sidebar causes HTML entities within to be reverted; if the Macro is then saved, so are those reversions. This behavior is not present within Abilities or Ability Command Buttons.

For Ability Command Buttons, if the Ability that creates the button and the Ability it references are both on the same sheet, the syntax is very simple:

[Ability](~AbilityName)

[edit] More

[edit] See Also