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_idis the new owner who must be active member of a group specified bygroup_id.-
object
- group_id (string) required
- owner_id (string) required
-
object
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
—
nicknameis required. You must use one of the following identifiers:user_id,phone_number, oremail.-
object
- nickname (string) required
- user_id (string)
- phone_number (string)
- email (string)
- guid (string)
-
object
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
memberskey in the group JSON, this is theidvalue, not theuser_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_guidwithin one minute of each other, the second message will fail with a409 Conflictresponse. 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
attachmentis 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
-
object
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
attachmentis 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
-
object
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
- 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