Missing features from API about hubot-groupme

[hawkins]

So images are somewhat documented now on the GroupMe public api.

Adding and removing users, I'm not so sure about.

But mentions are another story. I'm using mentions in another [another hubot project of mine, in which I've implemented an "@ALL" feature for GroupMe that mentions every user in the room. To do this, I use the following code to form the request:

  robot.hear /(.*)@all(.*)/i, (res) ->
    message =
      'text': res.match[1],
      'bot_id': @bot_id,
      'attachments': [
        "loci": [],
        "type": "mentions",
        "user_ids": []
      ]

    i = 0
    for user, values of robot.brain.users()
      message.attachments[0].loci.push([i, i+1])
      message.attachments[0].user_ids.push(user)
      i += 1

    json = JSON.stringify(message)

    options =
      agent: false
      host: "api.groupme.com"
      path: "/v3/bots/post"
      port: 443
      method: "POST"
      headers:
        'Content-Length': json.length
        'Content-Type': 'application/json'
        'X-Access-Token': token

    req = https.request options, (response) ->
      data = ''
      response.on 'data', (chunk) -> data += chunk
      response.on 'end', ->
        console.log "[GROUPME RESPONSE] #{response.statusCode} #{data}"
    req.end(json)

You'll notice a few things here: First, mentions are added using an attachments property on the data sent. There are actually a few other types of attachments available (image, emoji, location, split) you can find on the public API. But we'll just talk about mentions] for now.

mentions has two required properties:

• loci :: Array[n] of Array[2] containing integers
• user_ids :: Array[n] containing user_ids

loci holds an array of array of indexes used to mark off where a particular mention begins and ends.
For instance, loci: [[0, 1]] will have one mention (the user id for which will be found in user_ids) and this mention will start at index 0 and stretch until index 1. You'll notice this means mentions do not have to be the same length / string as the user name of the user they mention!

user_ids holds a series of user ids to match the loci ordered pairs.

Example

message =
  text: "Some long string.",
  attachments: [
    loci: [
      [0, 5]
    ],
    type: "mentions",
    user_ids: [
      12345678
    ]
  ]

The previous example will tag the user with the ID 12345678 and their mention will be on the text "Some", so the text will appear bolded on "Some" but not "long string."

---

Note that I'm currently working to include mention capability in the hubot-groupme adapter, but I'm not sure the best format to do so. How should the user build mentions into a string? I'll keep toying with the idea, and for those interested, keep an eye on my fork for more info.