Developers

Public API

API Responses

How our API responses are structured

Hitting our REST API

Always include your token as a parameter when making requests.

Base Url: 

https://api.groupme.com/v3

Example posting JSON data: 

$ curl -X POST -H "Content-Type: application/json" -d '{"name": "Family"}' https://api.groupme.com/v3/groups?token=YOUR_ACCESS_TOKEN

Example JSON response envelope ("response" key omitted in Responses for brevity): 

HTTP/1.1 201

{
  "response": {
      "id": "12345",
      "name": "Family"
      //...
    }
  }
}

Example JSON errors envelope: 

HTTP/1.1 400

{
  meta: {
    "code": 400,
    "errors": ["Name is required"]
  },
  response: null
}

Groups

Index

List the authenticated user's active groups.

The response is paginated, with a default of 10 groups per page.

Please consider using of omit=memberships parameter. Not including member lists might significantly improve user experience of your app for users who are participating in huge groups.

Request

GET /groups

Parameters

page
integer — Fetch a particular page of results. Defaults to 1.
per_page
integer — Define page size. Defaults to 10.
omit
string — Comma separated list of data to omit from output. Currently supported value is only "memberships". If used then response will contain empty (null) members field.

Responses

Status: 200 OK
[
  {
    "id": "1234567890",
    "name": "Family",
    "type": "private",
    "description": "Coolest Family Ever",
    "image_url": "https://i.groupme.com/123456789",
    "creator_user_id": "1234567890",
    "created_at": 1302623328,
    "updated_at": 1302623328,
    "members": [
      {
        "user_id": "1234567890",
        "nickname": "Jane",
        "muted": false,
        "image_url": "https://i.groupme.com/123456789"
      }
    ],
    "share_url": "https://groupme.com/join_group/1234567890/SHARE_TOKEN",
    "messages": {
      "count": 100,
      "last_message_id": "1234567890",
      "last_message_created_at": 1302623328,
      "preview": {
        "nickname": "Jane",
        "text": "Hello world",
        "image_url": "https://i.groupme.com/123456789",
        "attachments": [
          {
            "type": "image",
            "url": "https://i.groupme.com/123456789"
          },
          {
            "type": "image",
            "url": "https://i.groupme.com/123456789"
          },
          {
            "type": "location",
            "lat": "40.738206",
            "lng": "-73.993285",
            "name": "GroupMe HQ"
          },
          {
            "type": "split",
            "token": "SPLIT_TOKEN"
          },
          {
            "type": "emoji",
            "placeholder": "☃",
            "charmap": [
              [
                1,
                42
              ],
              [
                2,
                34
              ]
            ]
          }
        ]
      }
    }
  }
]

Former

List they groups you have left but can rejoin.

Request

GET /groups/former

Responses

Status: 200 OK
[
  {
    "id": "1234567890",
    "name": "Family",
    "type": "private",
    "description": "Coolest Family Ever",
    "image_url": "https://i.groupme.com/123456789",
    "creator_user_id": "1234567890",
    "created_at": 1302623328,
    "updated_at": 1302623328,
    "members": [
      {
        "user_id": "1234567890",
        "nickname": "Jane",
        "muted": false,
        "image_url": "https://i.groupme.com/123456789"
      }
    ],
    "share_url": "https://groupme.com/join_group/1234567890/SHARE_TOKEN",
    "messages": {
      "count": 100,
      "last_message_id": "1234567890",
      "last_message_created_at": 1302623328,
      "preview": {
        "nickname": "Jane",
        "text": "Hello world",
        "image_url": "https://i.groupme.com/123456789",
        "attachments": [
          {
            "type": "image",
            "url": "https://i.groupme.com/123456789"
          },
          {
            "type": "image",
            "url": "https://i.groupme.com/123456789"
          },
          {
            "type": "location",
            "lat": "40.738206",
            "lng": "-73.993285",
            "name": "GroupMe HQ"
          },
          {
            "type": "split",
            "token": "SPLIT_TOKEN"
          },
          {
            "type": "emoji",
            "placeholder": "☃",
            "charmap": [
              [
                1,
                42
              ],
              [
                2,
                34
              ]
            ]
          }
        ]
      }
    }
  }
]

Show

Load a specific group.

Request

GET /groups/:id

Parameters

id required
string

Responses

Status: 200 OK
{
  "id": "1234567890",
  "name": "Family",
  "type": "private",
  "description": "Coolest Family Ever",
  "image_url": "https://i.groupme.com/123456789",
  "creator_user_id": "1234567890",
  "created_at": 1302623328,
  "updated_at": 1302623328,
  "members": [
    {
      "user_id": "1234567890",
      "nickname": "Jane",
      "muted": false,
      "image_url": "https://i.groupme.com/123456789"
    }
  ],
  "share_url": "https://groupme.com/join_group/1234567890/SHARE_TOKEN",
  "messages": {
    "count": 100,
    "last_message_id": "1234567890",
    "last_message_created_at": 1302623328,
    "preview": {
      "nickname": "Jane",
      "text": "Hello world",
      "image_url": "https://i.groupme.com/123456789",
      "attachments": [
        {
          "type": "image",
          "url": "https://i.groupme.com/123456789"
        },
        {
          "type": "image",
          "url": "https://i.groupme.com/123456789"
        },
        {
          "type": "location",
          "lat": "40.738206",
          "lng": "-73.993285",
          "name": "GroupMe HQ"
        },
        {
          "type": "split",
          "token": "SPLIT_TOKEN"
        },
        {
          "type": "emoji",
          "placeholder": "☃",
          "charmap": [
            [
              1,
              42
            ],
            [
              2,
              34
            ]
          ]
        }
      ]
    }
  }
}

Create

Create a new group

Request

POST /groups
{
  "name": "Family",
  "share": true,
  "image_url": "https://i.groupme.com/123456789"
}

Parameters

name required
string — Primary name of the group. Maximum 140 characters
description
string — A subheading for the group. Maximum 255 characters
image_url
string — GroupMe Image Service URL
share
boolean — If you pass a true value for share, we'll generate a share URL. Anybody with this URL can join the group.

Responses

Status: 201 Created
{
  "id": "1234567890",
  "name": "Family",
  "type": "private",
  "description": "Coolest Family Ever",
  "image_url": "https://i.groupme.com/123456789",
  "creator_user_id": "1234567890",
  "created_at": 1302623328,
  "updated_at": 1302623328,
  "members": [
    {
      "user_id": "1234567890",
      "nickname": "Jane",
      "muted": false,
      "image_url": "https://i.groupme.com/123456789"
    }
  ],
  "share_url": "https://groupme.com/join_group/1234567890/SHARE_TOKEN",
  "messages": {
    "count": 100,
    "last_message_id": "1234567890",
    "last_message_created_at": 1302623328,
    "preview": {
      "nickname": "Jane",
      "text": "Hello world",
      "image_url": "https://i.groupme.com/123456789",
      "attachments": [
        {
          "type": "image",
          "url": "https://i.groupme.com/123456789"
        },
        {
          "type": "image",
          "url": "https://i.groupme.com/123456789"
        },
        {
          "type": "location",
          "lat": "40.738206",
          "lng": "-73.993285",
          "name": "GroupMe HQ"
        },
        {
          "type": "split",
          "token": "SPLIT_TOKEN"
        },
        {
          "type": "emoji",
          "placeholder": "☃",
          "charmap": [
            [
              1,
              42
            ],
            [
              2,
              34
            ]
          ]
        }
      ]
    }
  }
}

Update

Update a group after creation

Request

POST /groups/:id/update
{
  "name": "Family",
  "share": true,
  "image_url": "https://i.groupme.com/123456789",
  "office_mode": true
}

Parameters

name
string
description
string
image_url
string
office_mode
boolean
share
boolean — If you pass a true value for share, we'll generate a share URL. Anybody with this URL can join the group.

Responses

Status: 200 OK
{
  "id": "1234567890",
  "name": "Family",
  "type": "private",
  "description": "Coolest Family Ever",
  "image_url": "https://i.groupme.com/123456789",
  "creator_user_id": "1234567890",
  "created_at": 1302623328,
  "updated_at": 1302623328,
  "members": [
    {
      "user_id": "1234567890",
      "nickname": "Jane",
      "muted": false,
      "image_url": "https://i.groupme.com/123456789"
    }
  ],
  "share_url": "https://groupme.com/join_group/1234567890/SHARE_TOKEN",
  "messages": {
    "count": 100,
    "last_message_id": "1234567890",
    "last_message_created_at": 1302623328,
    "preview": {
      "nickname": "Jane",
      "text": "Hello world",
      "image_url": "https://i.groupme.com/123456789",
      "attachments": [
        {
          "type": "image",
          "url": "https://i.groupme.com/123456789"
        },
        {
          "type": "image",
          "url": "https://i.groupme.com/123456789"
        },
        {
          "type": "location",
          "lat": "40.738206",
          "lng": "-73.993285",
          "name": "GroupMe HQ"
        },
        {
          "type": "split",
          "token": "SPLIT_TOKEN"
        },
        {
          "type": "emoji",
          "placeholder": "☃",
          "charmap": [
            [
              1,
              42
            ],
            [
              2,
              34
            ]
          ]
        }
      ]
    }
  }
}

Destroy

Disband a group

This action is only available to the group creator

Request

POST /groups/:id/destroy

Responses

Status: 200 OK

Join

Join a shared group

Request

POST /groups/:id/join/:share_token

Responses

Status: 200 OK
{
  "group": {
    "id": "1234567890",
    "name": "Family",
    "type": "private",
    "description": "Coolest Family Ever",
    "image_url": "https://i.groupme.com/123456789",
    "creator_user_id": "1234567890",
    "created_at": 1302623328,
    "updated_at": 1302623328,
    "members": [
      {
        "user_id": "1234567890",
        "nickname": "Jane",
        "muted": false,
        "image_url": "https://i.groupme.com/123456789"
      }
    ],
    "share_url": "https://groupme.com/join_group/1234567890/SHARE_TOKEN",
    "messages": {
      "count": 100,
      "last_message_id": "1234567890",
      "last_message_created_at": 1302623328,
      "preview": {
        "nickname": "Jane",
        "text": "Hello world",
        "image_url": "https://i.groupme.com/123456789",
        "attachments": [
          {
            "type": "image",
            "url": "https://i.groupme.com/123456789"
          },
          {
            "type": "image",
            "url": "https://i.groupme.com/123456789"
          },
          {
            "type": "location",
            "lat": "40.738206",
            "lng": "-73.993285",
            "name": "GroupMe HQ"
          },
          {
            "type": "split",
            "token": "SPLIT_TOKEN"
          },
          {
            "type": "emoji",
            "placeholder": "☃",
            "charmap": [
              [
                1,
                42
              ],
              [
                2,
                34
              ]
            ]
          }
        ]
      }
    }
  }
}

Rejoin

Rejoin a group. Only works if you previously removed yourself.

Request

POST /groups/join

Parameters

group_id required
string

Responses

Status: 200 OK
{
  "id": "1234567890",
  "name": "Family",
  "type": "private",
  "description": "Coolest Family Ever",
  "image_url": "https://i.groupme.com/123456789",
  "creator_user_id": "1234567890",
  "created_at": 1302623328,
  "updated_at": 1302623328,
  "members": [
    {
      "user_id": "1234567890",
      "nickname": "Jane",
      "muted": false,
      "image_url": "https://i.groupme.com/123456789"
    }
  ],
  "share_url": "https://groupme.com/join_group/1234567890/SHARE_TOKEN",
  "messages": {
    "count": 100,
    "last_message_id": "1234567890",
    "last_message_created_at": 1302623328,
    "preview": {
      "nickname": "Jane",
      "text": "Hello world",
      "image_url": "https://i.groupme.com/123456789",
      "attachments": [
        {
          "type": "image",
          "url": "https://i.groupme.com/123456789"
        },
        {
          "type": "image",
          "url": "https://i.groupme.com/123456789"
        },
        {
          "type": "location",
          "lat": "40.738206",
          "lng": "-73.993285",
          "name": "GroupMe HQ"
        },
        {
          "type": "split",
          "token": "SPLIT_TOKEN"
        },
        {
          "type": "emoji",
          "placeholder": "☃",
          "charmap": [
            [
              1,
              42
            ],
            [
              2,
              34
            ]
          ]
        }
      ]
    }
  }
}

Change owner(s)

Change owner of requested groups.

This action is only available to the group creator.

Response is array of result objects which contain status field - the result of change owner action for every request:

  • '200' - OK
  • '400' - when requestor is also a new owner
  • '403' - requestor is not owner of the group
  • '404' - group or new owner not found or new owner is not member of the group
  • '405' - request object is missing required field or any of the required fields is not an ID

Request

POST /groups/change_owners

Parameters

requests required
array — One request is object where user_id is the new owner who must be active member of a group specified by group_id.
  • object
    • group_id (string) required
    • owner_id (string) required

Responses

Status: 200 OK
{
  "results": [
    {
      "group_id": "1234567890",
      "owner_id": "1234567890",
      "status": "200"
    },
    {
      "group_id": "1234567890",
      "owner_id": "1234567890",
      "status": "400"
    }
  ]
}
Status: 400 Bad Request
'requests' field missing in request body

Members

Add

Add members to a group.

Multiple members can be added in a single request, and results are fetched with a separate call (since memberships are processed asynchronously). The response includes a results_id that's used in the results request.

In order to correlate request params with resulting memberships, GUIDs can be added to the members parameters. These GUIDs will be reflected in the membership JSON objects.

Request

POST /groups/:group_id/members/add
{
  "members": [
    {
      "nickname": "Mom",
      "user_id": "1234567890",
      "guid": "GUID-1"
    },
    {
      "nickname": "Dad",
      "phone_number": "+1 2123001234",
      "guid": "GUID-2"
    },
    {
      "nickname": "Jane",
      "email": "jane@example.com",
      "guid": "GUID-3"
    }
  ]
}

Parameters

members
array — nickname is required. You must use one of the following identifiers: user_id, phone_number, or email.
  • object
    • nickname (string) required
    • user_id (string)
    • phone_number (string)
    • email (string)
    • guid (string)

Responses

Status: 202 Accepted
{
  "results_id": "GUID"
}

Results

Get the membership results from an add call.

Successfully created memberships will be returned, including any GUIDs that were sent up in the add request. If GUIDs were absent, they are filled in automatically. Failed memberships and invites are omitted.

Keep in mind that results are temporary -- they will only be available for 1 hour after the add request.

Request

GET /groups/:group_id/members/results/:results_id

Parameters

results_id required
string — This is the guid that's returned from an add request.

Responses

Status: 200 OK
{
  "members": [
    {
      "id": "1000",
      "user_id": "10000",
      "nickname": "John",
      "muted": false,
      "image_url": "https://i.groupme.com/AVATAR",
      "autokicked": false,
      "app_installed": true,
      "guid": "GUID-1"
    },
    {
      "id": "2000",
      "user_id": "20000",
      "nickname": "Anne",
      "muted": false,
      "image_url": "https://i.groupme.com/AVATAR",
      "autokicked": false,
      "app_installed": true,
      "guid": "GUID-2"
    }
  ]
}
Status: 503 Service Unavailable
Results aren't ready. Try again in a little bit.
Status: 404 Not Found
Results are no longer available. Don't try again.

Remove

Remove a member (or yourself) from a group.

Note: The creator of the group cannot be removed or exit.

Request

POST /groups/:group_id/members/:membership_id/remove

Parameters

membership_id required
string — Please note that this isn't the same as the user ID. In the members key in the group JSON, this is the id value, not the user_id.

Responses

Status: 200 OK

Update

Update your nickname in a group. The nickname must be between 1 and 50 characters.

Request

POST /groups/:group_id/memberships/update
{
  "membership": {
    "nickname": "NEW NICKNAME"
  }
}

Responses

Status: 200 OK
{
  "id": "MEMBERSHIP ID",
  "user_id": "USER ID",
  "nickname": "NEW NICKNAME",
  "muted": false,
  "image_url": "AVATAR URL",
  "autokicked": false,
  "app_installed": true
}

Messages

Index

Retrieve messages for a group.

By default, messages are returned in groups of 20, ordered by created_at descending. This can be raised or lowered by passing a limit parameter, up to a maximum of 100 messages.

Messages can be scanned by providing a message ID as either the before_id, since_id, or after_id parameter. If before_id is provided, then messages immediately preceding the given message will be returned, in descending order. This can be used to continually page back through a group's messages.

The after_id parameter will return messages that immediately follow a given message, this time in ascending order (which makes it easy to pick off the last result for continued pagination).

Finally, the since_id parameter also returns messages created after the given message, but it retrieves the most recent messages. For example, if more than twenty messages are created after the since_id message, using this parameter will omit the messages that immediately follow the given message. This is a bit counterintuitive, so take care.

If no messages are found (e.g. when filtering with before_id) we return code 304.

Note that for historical reasons, likes are returned as an array of user ids in the favorited_by key.

Request

GET /groups/:group_id/messages

Parameters

before_id
string — Returns messages created before the given message ID
since_id
string — Returns most recent messages created after the given message ID
after_id
string — Returns messages created immediately after the given message ID
limit
integer — Number of messages returned. Default is 20. Max is 100.

Responses

Status: 200 OK
{
  "count": 123,
  "messages": [
    {
      "id": "1234567890",
      "source_guid": "GUID",
      "created_at": 1302623328,
      "user_id": "1234567890",
      "group_id": "1234567890",
      "name": "John",
      "avatar_url": "https://i.groupme.com/123456789",
      "text": "Hello world ☃☃",
      "system": true,
      "favorited_by": [
        "101",
        "66",
        "1234567890"
      ],
      "attachments": [
        {
          "type": "image",
          "url": "https://i.groupme.com/123456789"
        },
        {
          "type": "image",
          "url": "https://i.groupme.com/123456789"
        },
        {
          "type": "location",
          "lat": "40.738206",
          "lng": "-73.993285",
          "name": "GroupMe HQ"
        },
        {
          "type": "split",
          "token": "SPLIT_TOKEN"
        },
        {
          "type": "emoji",
          "placeholder": "☃",
          "charmap": [
            [
              1,
              42
            ],
            [
              2,
              34
            ]
          ]
        }
      ]
    }
  ]
}

Create

Send a message to a group

If you want to attach an image, you must first process it through our image service.

Attachments of type emoji rely on data from emoji PowerUps.

Clients use a placeholder character in the message text and specify a replacement charmap to substitute emoji characters

The character map is an array of arrays containing rune data ([[{pack_id,offset}],...]).

The placeholder should be a high-point/invisible UTF-8 character.

Request

POST /groups/:group_id/messages
{
  "message": {
    "source_guid": "GUID",
    "text": "Hello world ☃☃",
    "attachments": [
      {
        "type": "image",
        "url": "https://i.groupme.com/123456789"
      },
      {
        "type": "image",
        "url": "https://i.groupme.com/123456789"
      },
      {
        "type": "location",
        "lat": "40.738206",
        "lng": "-73.993285",
        "name": "GroupMe HQ"
      },
      {
        "type": "split",
        "token": "SPLIT_TOKEN"
      },
      {
        "type": "emoji",
        "placeholder": "☃",
        "charmap": [
          [
            1,
            42
          ],
          [
            2,
            34
          ]
        ]
      }
    ]
  }
}

Parameters

source_guid required
string — Client-side IDs for messages. This can be used by clients to set their own identifiers on messages, but the server also scans these for de-duplication. That is, if two messages are sent with the same source_guid within one minute of each other, the second message will fail with a 409 Conflict response. So it's important to set this to a unique value for each message.
text required
string — This can be omitted if at least one attachment is present. The maximum length is 1,000 characters.
attachments
array — A polymorphic list of attachments (locations, images, etc). You may have You may have more than one of any type of attachment, provided clients can display it.
  • object
    • type (string) — “image” required
    • url (string) required — Must be an image service (i.groupme.com) URL
  • object
    • type (string) — “location” required
    • name (string) required
    • lat (string) required
    • lng (string) required
  • object
    • type (string) — “split” required
    • token (string) required
  • object
    • type (string) — “emoji” required
    • placeholder (string) — “☃” required
    • charmap (array) — “[{pack_id},{offset}]” required

Responses

Status: 201 Created
{
  "message": {
    "id": "1234567890",
    "source_guid": "GUID",
    "created_at": 1302623328,
    "user_id": "1234567890",
    "group_id": "1234567890",
    "name": "John",
    "avatar_url": "https://i.groupme.com/123456789",
    "text": "Hello world ☃☃",
    "system": true,
    "favorited_by": [
      "101",
      "66",
      "1234567890"
    ],
    "attachments": [
      {
        "type": "image",
        "url": "https://i.groupme.com/123456789"
      },
      {
        "type": "image",
        "url": "https://i.groupme.com/123456789"
      },
      {
        "type": "location",
        "lat": "40.738206",
        "lng": "-73.993285",
        "name": "GroupMe HQ"
      },
      {
        "type": "split",
        "token": "SPLIT_TOKEN"
      },
      {
        "type": "emoji",
        "placeholder": "☃",
        "charmap": [
          [
            1,
            42
          ],
          [
            2,
            34
          ]
        ]
      }
    ]
  }
}

Chats

Index

Returns a paginated list of direct message chats, or conversations, sorted by updated_at descending.

Request

GET /chats

Parameters

page
integer — Page number
per_page
integer — Number of chats per page

Responses

Status: 200 OK
[
  {
    "created_at": 1352299338,
    "updated_at": 1352299338,
    "last_message": {
      "attachments": [

      ],
      "avatar_url": "https://i.groupme.com/200x200.jpeg.abcdef",
      "conversation_id": "12345+67890",
      "created_at": 1352299338,
      "favorited_by": [

      ],
      "id": "1234567890",
      "name": "John Doe",
      "recipient_id": "67890",
      "sender_id": "12345",
      "sender_type": "user",
      "source_guid": "GUID",
      "text": "Hello world",
      "user_id": "12345"
    },
    "messages_count": 10,
    "other_user": {
      "avatar_url": "https://i.groupme.com/200x200.jpeg.abcdef",
      "id": 12345,
      "name": "John Doe"
    }
  }
]

Direct Messages

Index

Fetch direct messages between two users.

DMs are returned in groups of 20, ordered by created_at descending.

If no messages are found (e.g. when filtering with since_id) we return code 304.

Note that for historical reasons, likes are returned as an array of user ids in the favorited_by key.

Request

GET /direct_messages

Parameters

other_user_id required
string — The other participant in the conversation.
before_id
string — Returns 20 messages created before the given message ID
since_id
string — Returns 20 messages created after the given message ID

Responses

Status: 200 OK
{
  "count": 123,
  "direct_messages": [
    {
      "id": "1234567890",
      "source_guid": "GUID",
      "recipient_id": "20",
      "user_id": "1234567890",
      "created_at": 1302623328,
      "name": "John",
      "avatar_url": "https://i.groupme.com/123456789",
      "text": "Hello world ☃☃",
      "favorited_by": [
        "101"
      ],
      "attachments": [
        {
          "type": "image",
          "url": "https://i.groupme.com/123456789"
        },
        {
          "type": "image",
          "url": "https://i.groupme.com/123456789"
        },
        {
          "type": "location",
          "lat": "40.738206",
          "lng": "-73.993285",
          "name": "GroupMe HQ"
        },
        {
          "type": "emoji",
          "placeholder": "☃",
          "charmap": [
            [
              1,
              42
            ],
            [
              2,
              34
            ]
          ]
        }
      ]
    }
  ]
}

Create

Send a DM to another user

If you want to attach an image, you must first process it through our image service.

Attachments of type emoji rely on data from emoji PowerUps.

Clients use a placeholder character in the message text and specify a replacement charmap to substitute emoji characters

The character map is an array of arrays containing rune data ([[{pack_id,offset}],...]).

Request

POST /direct_messages
{
  "direct_message": {
    "source_guid": "GUID",
    "recipient_id": "20",
    "text": "Hello world ☃☃",
    "attachments": [
      {
        "type": "image",
        "url": "https://i.groupme.com/123456789"
      },
      {
        "type": "image",
        "url": "https://i.groupme.com/123456789"
      },
      {
        "type": "location",
        "lat": "40.738206",
        "lng": "-73.993285",
        "name": "GroupMe HQ"
      },
      {
        "type": "emoji",
        "placeholder": "☃",
        "charmap": [
          [
            1,
            42
          ],
          [
            2,
            34
          ]
        ]
      }
    ]
  }
}

Parameters

source_guid required
string — This is used for client-side deduplication.
recipient_id required
string — The GroupMe user ID of the recipient of this message.
text required
string — This can be omitted if at least one attachment is present.
attachments
array — A polymorphic list of attachments (locations, images, etc). You may have You may have more than one of any type of attachment, provided clients can display it.
  • object
    • type (string) — “image” required
    • url (string) required — Must be an image service (i.groupme.com) URL
  • object
    • type (string) — “location” required
    • name (string) required
    • lat (string) required
    • lng (string) required
  • object
    • type (string) — “emoji” required
    • placeholder (string) — “☃” required
    • charmap (array) — “[{pack_id},{offset}]” required

Responses

Status: 201 Created
{
  "message": {
    "id": "1234567890",
    "source_guid": "GUID",
    "recipient_id": "20",
    "user_id": "1234567890",
    "created_at": 1302623328,
    "name": "John",
    "avatar_url": "https://i.groupme.com/123456789",
    "text": "Hello world ☃☃",
    "favorited_by": [
      "101"
    ],
    "attachments": [
      {
        "type": "image",
        "url": "https://i.groupme.com/123456789"
      },
      {
        "type": "image",
        "url": "https://i.groupme.com/123456789"
      },
      {
        "type": "location",
        "lat": "40.738206",
        "lng": "-73.993285",
        "name": "GroupMe HQ"
      },
      {
        "type": "emoji",
        "placeholder": "☃",
        "charmap": [
          [
            1,
            42
          ],
          [
            2,
            34
          ]
        ]
      }
    ]
  }
}
Status: 403 Forbidden
User has been auto-banned for sending too many messages.
Status: 400 Bad Request
There's a problem with the parameters. Check errors.

Likes

Create

Like a message.

Request

POST /messages/:conversation_id/:message_id/like

Responses

Status: 200 OK

Destroy

Unlike a message.

Request

POST /messages/:conversation_id/:message_id/unlike

Responses

Status: 200 OK

Leaderboard

Index

A list of the liked messages in the group for a given period of time. Messages are ranked in order of number of likes.

Request

GET /groups/:group_id/likes?period=<day|week|month>

Parameters

period required
string — one of: 'day', 'week', or 'month'

Responses

Status: 200 OK
{
  "messages": [
    {
      "id": "1234567890",
      "source_guid": "GUID",
      "created_at": 1302623328,
      "user_id": "1234567890",
      "group_id": "1234567890",
      "name": "John",
      "avatar_url": "https://i.groupme.com/123456789",
      "text": "Hello world ☃☃",
      "system": true,
      "favorited_by": [
        "101",
        "66",
        "1234567890"
      ],
      "attachments": [
        {
          "type": "image",
          "url": "https://i.groupme.com/123456789"
        },
        {
          "type": "image",
          "url": "https://i.groupme.com/123456789"
        },
        {
          "type": "location",
          "lat": "40.738206",
          "lng": "-73.993285",
          "name": "GroupMe HQ"
        },
        {
          "type": "split",
          "token": "SPLIT_TOKEN"
        },
        {
          "type": "emoji",
          "placeholder": "☃",
          "charmap": [
            [
              1,
              42
            ],
            [
              2,
              34
            ]
          ]
        }
      ]
    },
    {
      "id": "1234567890",
      "source_guid": "GUID",
      "created_at": 1302623328,
      "user_id": "1234567890",
      "group_id": "1234567890",
      "name": "John",
      "avatar_url": "https://i.groupme.com/123456789",
      "text": "Hello world ☃☃",
      "system": true,
      "favorited_by": [
        "1",
        "2"
      ],
      "attachments": [
        {
          "type": "image",
          "url": "https://i.groupme.com/123456789"
        },
        {
          "type": "image",
          "url": "https://i.groupme.com/123456789"
        },
        {
          "type": "location",
          "lat": "40.738206",
          "lng": "-73.993285",
          "name": "GroupMe HQ"
        },
        {
          "type": "split",
          "token": "SPLIT_TOKEN"
        },
        {
          "type": "emoji",
          "placeholder": "☃",
          "charmap": [
            [
              1,
              42
            ],
            [
              2,
              34
            ]
          ]
        }
      ]
    }
  ]
}

My Likes

A list of messages you have liked. Messages are returned in reverse chrono-order. Note that the payload includes a liked_at timestamp in ISO-8601 format.

Request

GET /groups/:group_id/likes/mine

Responses

Status: 200 OK
{
  "messages": [
    {
      "id": "1234567890",
      "source_guid": "GUID",
      "created_at": 1302623328,
      "user_id": "1234567890",
      "group_id": "1234567890",
      "name": "John",
      "avatar_url": "https://i.groupme.com/123456789",
      "text": "Hello world ☃☃",
      "system": true,
      "favorited_by": [
        "101",
        "66",
        "1234567890"
      ],
      "attachments": [
        {
          "type": "image",
          "url": "https://i.groupme.com/123456789"
        },
        {
          "type": "image",
          "url": "https://i.groupme.com/123456789"
        },
        {
          "type": "location",
          "lat": "40.738206",
          "lng": "-73.993285",
          "name": "GroupMe HQ"
        },
        {
          "type": "split",
          "token": "SPLIT_TOKEN"
        },
        {
          "type": "emoji",
          "placeholder": "☃",
          "charmap": [
            [
              1,
              42
            ],
            [
              2,
              34
            ]
          ]
        }
      ],
      "liked_at": "2014-05-08T18:30:31.6617Z"
    }
  ]
}

My Hits

A list of messages others have liked.

Request

GET /groups/:group_id/likes/for_me

Responses

Status: 200 OK
{
  "messages": [
    {
      "id": "1234567890",
      "source_guid": "GUID",
      "created_at": 1302623328,
      "user_id": "1234567890",
      "group_id": "1234567890",
      "name": "John",
      "avatar_url": "https://i.groupme.com/123456789",
      "text": "Hello world ☃☃",
      "system": true,
      "favorited_by": [
        "101",
        "66",
        "1234567890"
      ],
      "attachments": [
        {
          "type": "image",
          "url": "https://i.groupme.com/123456789"
        },
        {
          "type": "image",
          "url": "https://i.groupme.com/123456789"
        },
        {
          "type": "location",
          "lat": "40.738206",
          "lng": "-73.993285",
          "name": "GroupMe HQ"
        },
        {
          "type": "split",
          "token": "SPLIT_TOKEN"
        },
        {
          "type": "emoji",
          "placeholder": "☃",
          "charmap": [
            [
              1,
              42
            ],
            [
              2,
              34
            ]
          ]
        }
      ]
    }
  ]
}

Bots

Create

Create a bot. See our Bots Tutorial for a full walkthrough.

Request

POST /bots

Parameters

bot[name] required
string
bot[group_id] required
string
bot[avatar_url]
string
bot[callback_url]
string
bot[dm_notification]
boolean
bot[active] required
boolean

Responses

Status: 201 Created
{
  "bot_id": "1234567890",
  "group_id": "1234567890",
  "name": "hal9000",
  "avatar_url": "https://i.groupme.com/123456789",
  "callback_url": "https://example.com/bots/callback",
  "dm_notification": false,
  "active": true
}

Post a Message

Post a message from a bot

Request

POST /bots/post

Parameters

bot_id required
string
text required
string
picture_url
string — Image must be processed through image service.

Responses

Status: 201 Created

Index

List bots that you have created

Request

GET /bots

Responses

Status: 200 OK
[
  {
    "bot_id": "1234567890",
    "group_id": "1234567890",
    "name": "hal9000",
    "avatar_url": "https://i.groupme.com/123456789",
    "callback_url": "https://example.com/bots/callback",
    "dm_notification": false,
    "active": true
  }
]

Destroy

Remove a bot that you have created

Request

POST /bots/destroy

Parameters

bot_id required

Responses

Status: 200 OK

Users

Me

Get details about the authenticated user

Request

GET /users/me

Responses

Status: 200 OK
{
  "id": "1234567890",
  "phone_number": "+1 2123001234",
  "image_url": "https://i.groupme.com/123456789",
  "name": "Ronald Swanson",
  "created_at": 1302623328,
  "updated_at": 1302623328,
  "email": "me@example.com",
  "sms": false
}

Update

Update attributes about your own account

Request

POST /users/update
{
  "avatar_url": "https://4.bp.blogspot.com/-GAeMYT8SZoI/TtBTK209xMI/AAAAAAAAWts/5nmvpmmvoWo/s1600/TopGun_059Pyxurz.jpg",
  "name": "Tom Skerritt",
  "email": "viper@topgun.usaf.mil",
  "zip_code": "92145"
}

Parameters

avatar_url
string — URL to valid JPG/PNG/GIF image. URL will be converted into an image service link (https://i.groupme.com/....)
name
string — Name must be of the form FirstName LastName
email
string — Email address. Must be in name@domain.com form.
zip_code
string — Zip code.

Responses

Status: 200 OK
{
  "id": "1234567890",
  "phone_number": "+1 2123001234",
  "image_url": "https://i.groupme.com/123456789",
  "name": "Ronald Swanson",
  "created_at": 1302623328,
  "updated_at": 1302623328,
  "email": "me@example.com",
  "sms": false
}

Sms Mode

Create

Enables SMS mode for N hours, where N is at most 48. After N hours have elapsed, user will receive push notfications.

Request

POST /users/sms_mode
{
  "duration": 4,
  "registration_id": "TOKEN"
}

Parameters

duration required
integer
registration_id
string — The push notification ID/token that should be suppressed during SMS mode. If this is omitted, both SMS and push notifications will be delivered to the device.

Responses

Status: 201 Created

Delete

Disables SMS mode

Request

POST /users/sms_mode/delete

Responses

Status: 200 OK

Blocks

Index

A list of contacts you have blocked. These people cannot DM you.

Request

GET /blocks?user=<your user id>

Responses

Status: 200 OK
{
  "blocks": [
    {
      "user_id": "1234567890",
      "blocked_user_id": "1234567890",
      "created_at": 1302623328
    }
  ]
}

Block Between

Asks if a block exists between you and another user id

Request

GET /blocks/between?user=<you>&otherUser=<other user>

Responses

Status: 200 OK
{
  "between": true
}

Create Block

Creates a block between you and the contact

Request

POST /blocks?user=<you>&otherUser=<other user>

Parameters

user required
string — your user id.
otherUser required
string — user id of person you want to block.

Responses

Status: 201 Created
{
  "block": {
    "user_id": "1234567890",
    "blocked_user_id": "1234567890",
    "created_at": 1302623328
  }
}

Unblock

Removes block between you and other user

Request

DELETE /blocks?user=<you>&otherUser=<other user>

Responses

Status: 200 OK

Unblock

Removes block between you and other user

Request

POST /blocks/delete?user=<you>&otherUser=<other user>

Responses

Status: 200 OK
Back to Top