Creating a bot

Launching a bot with MeBots is even easier than using the official GroupMe API. Just follow these steps, and remember that help with any part of this process is available here!

  1. Go to Create Bot.
  2. Fill out the form! Most fields are not mandatory, but will help people locate and use your bot more effectively. Take particular note of the Callback URL. This is the URL where your bot is hosted on the internet, and where messages will be forwarded to for processing. Many developers like to host their bot on Heroku, AWS Lambda, or a personal server. Omit the callback URL if your bot does not need to receive or react to messages.
  3. Hit save to create your bot.

Congratulations! Users can now add your bot to GroupMe through the MeBots website. In your bot code, you will need to accept HTTP POST requests to the callback URL you specified. The request will contain a JSON body just like in a conventional GroupMe bot, but with a few fields added:

    "attachments": [],
    "avatar_url": "",
    "created_at": 1302623328,
    "group_id": "1234567890",
    "id": "1234567890",
    "name": "John",
    "sender_id": "12345",
    "sender_type": "user",
    "source_guid": "GUID",
    "system": false,
    "text": "Hello world, this is an example message! 😊",
    "user_id": "1234567890",
    "bot_id": "a1b2c3d4e5f61728394",
    "token": "a02h1d0/9fn032h9en0=293n40wqm0s9wjd"

The bot_id can be used to send messages through your bot as described here under the headline "Next: make your bot do something." The token property will be added if you request it and can be used to query GroupMe's API, although most bots do not need this. With the bot ID provided from MeBots, you can easily send messages from the bot across multiple groups rather than hardcoding the ID for a single chat.

Using the MeBots API

Most bots do not need to actively query the MeBots API, as the bot_id and token for the group of each received message is now included directly in the payload sent by MeBots to your callback URL. You may still wish to query the API, for example if your bot runs on a timer rather than replying to messages. This is quite easy—read on to find out how.

NOTE: There are official premade libraries for some languages that handle connection logic for you, so you can more easily integrate the MeBots API with your bot code. Choose your language: Python, JavaScript, Ruby. Please see the READMEs of those projects for detailed information on API interaction in these languages. Each library has a corresponding example bot demonstrating one possible way to implement it into a bot program: Python, JavaScript, Ruby.

If there's no library for your language, or if you want to handle things yourself, you will need to communicate directly to the MeBots API. Don't worry—this process is quite simple!

There are two major API endpoints, which allow you to provide the ID of a group and get back the bot ID for your bot in that group (and token, if your bot requires it). This way, your bot doesn't need to worry about keeping track of which servers you're in. MeBots does that for you.

From your bot's edit page, you will notice a "Token" box at the bottom of the page, with an automatically generated hexadecimal string. Take note of this token and your bot's shortname, as you will need them for authentication with the API from your bot's code. Do not share the token with anyone.

GET{shortname}/instances?token={your bot token}: will provide a list of all groups your bot is active in, and bot IDs and tokens that can be used to send messages in those groups. This endpoint may be useful if you are trying to send a scheduled message in all groups.

GET{shortname}/instances/{group_id}?token={your bot token}, substituting {shortname} for the shortname of your bot, and {group_id} for the ID of the group. You will receive a JSON response such as the following:

{"id": "0123456789abcdef", "token": "abcd_efghi/jklmnopqrstu=vwxyz123456/7890"}

The response can be parsed as JSON, and you can pass the id field as the bot_id parameter to the message post endpoint described in GroupMe's documentation here.