Roll20 Wiki

===Chat Events===

'''chat:message'''

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 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:
{| class="wikitable"
|-
! 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 <code>type</code> 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: <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".
|-
| [[Inline Rolls|inlinerolls]]
|
| ''(content contains one or more inline rolls only)'' An array of objects containing information about all inline rolls in the message.
|-
| [[Roll Template|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, <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
|
| ''(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.

<div class="toccolours mw-collapsible mw-collapsed" style="width:45%; margin-right: 20px; float: left;">
''Roll Result Structure Example 1''

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">
<pre data-language="javascript">
{
  "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)
}
</pre>
</div>
</div>

<div class="toccolours mw-collapsible mw-collapsed" style="width:45%; float: left;">
''Roll Result Structure Example 2''

An annotated structure for the result of <code>/roll {1d6!!>5}>6</code> (showing exploding modifications and target successes):
<div class="mw-collapsible-content">
<pre data-language="javascript">
{
  "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
}
</pre>
</div>
</div>

<div style="clear: both;"></div>

''Chat Event Example (Implementing Custom Roll Type)''
<pre data-language="javascript">
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");
  }
});
</pre>