Added Mentions (Schmavery#460)

* Added mentions sendMessage handler + docs.
* Mentions: Added fromIndex, checks and warnings

DOCS.md

@@ -493,7 +493,7 @@ function loadNextThreadHistory(api){
         if(err) return console.error(err);
 
         /*
-            Since the timestamp is from a previous loaded message, 
+            Since the timestamp is from a previous loaded message,
             that message will be included in this history so we can discard it unless it is the first load.
         */
         if(timestamp != undefined) history.pop();
@@ -875,6 +875,9 @@ Various types of message can be sent:
 * *File or image:* Set field `attachment` to a readable stream or an array of readable streams.
 * *URL:* set a field `url` to the desired URL.
 * *Emoji:* set field `emoji` to the desired emoji as a string and set field `emojiSize` with size of the emoji (`small`, `medium`, `large`)
+* *Mentions:* set field `mentions` to an array of objects. Objects should have the `tag` field set to the text that should be highlighted in the mention. The object should have an `id` field, where the `id` is the user id of the person being mentioned. The instance of `tag` that is highlighted is determined through indexOf, an optional `fromIndex`
+can be passed in to specify the start index to start searching for the `tag` text
+in `body` (default=0). (See below for an example.)
 
 Note that a message can only be a regular message (which can be empty) and optionally one of the following: a sticker, an attachment or a url.
 
@@ -912,6 +915,30 @@ login({appState: JSON.parse(fs.readFileSync('appstate.json', 'utf8'))}, (err, ap
 ***REMOVED***;
 ```
 
+__Example (Mention)__
+```js
+const login = require("facebook-chat-api");
+
+login({email: "EMAIL", password: "PASSWORD"}, (err, api) => {
+    if(err) return console.error(err);
+
+    api.listen((err, message) => {
+        if (message && message.body) {
+            // Getting the actual sender name from ID involves calling
+            // `api.getThreadInfo` and `api.getUserInfo`
+            api.sendMessage({
+                body: 'Hello @Sender! @Sender!',
+                mentions: [{
+                     tag: '@Sender',
+                     id: message.senderID,
+                     fromIndex: 9, // Highlight the second occurrence of @Sender
+                }],
+            }, message.threadID);
+        }
+  ***REMOVED***;
+***REMOVED***;
+```
+
 ---------------------------------------
 
 <a name="sendTypingIndicator"></a>

src/sendMessage.js

@@ -11,6 +11,7 @@ var allowedProperties = {
   emoji: true,
   emojiSize: true,
   body: true,
+  mentions: true,
 };
 
 module.exports = function(defaultFuncs, api, ctx) {
@@ -186,7 +187,7 @@ module.exports = function(defaultFuncs, api, ctx) {
     }
     cb();
   }
-  
+
   function handleEmoji(msg, form, callback, cb) {
     if (msg.emojiSize != null && msg.emoji == null) {
       return callback({error: "emoji property is empty"***REMOVED***;
@@ -236,6 +237,36 @@ module.exports = function(defaultFuncs, api, ctx) {
     }
   }
 
+  function handleMention(msg, form, callback, cb) {
+    if (msg.mentions) {
+      for (let i=0; i < msg.mentions.length; i++) {
+        const mention = msg.mentions[i];
+
+        const tag = mention.tag;
+        if (typeof tag !== "string") {
+          return callback({error: "Mention tags must be strings."***REMOVED***;
+        }
+
+        const offset = msg.body.indexOf(tag, mention.fromIndex || 0);
+
+        if (offset < 0) {
+          log.warn("handleMention", "Mention for \"" + tag +
+            "\" not found in message string.");
+        }
+
+        if (mention.id == null) {
+          log.warn("handleMention", "Mention id should be non-null.");
+        }
+
+        const id = mention.id || 0;
+        form['profile_xmd[' + i + '][offset]'] = offset;
+        form['profile_xmd[' + i + '][length]'] = tag.length;
+        form['profile_xmd[' + i + '][id]'] = id;
+      }
+    }
+    cb();
+  }
+
   return function sendMessage(msg, threadID, callback) {
     if(!callback && (utils.getType(threadID) === 'Function' || utils.getType(threadID) === 'AsyncFunction')) {
       return callback({error: "Pass a threadID as a second argument."***REMOVED***;
@@ -303,6 +334,7 @@ module.exports = function(defaultFuncs, api, ctx) {
       () => handleAttachment(msg, form, callback,
         () => handleUrl(msg, form, callback,
           () => handleEmoji(msg, form, callback,
-            () => send(form, threadID, messageAndOTID, callback)))));
+            () => handleMention(msg, form, callback,
+              () => send(form, threadID, messageAndOTID, callback))))));
   };
 };