Contributing Checklist -- What we still need for full coverage.

# Contribution Checklist

The following endpoints have been found used within the GroupMe Web Client. These are essentially the only endpoints left to document in order to have *nearly* full coverage of the API as it stands *right now*.

I'll be working on trying to get these documented as I have time, but anyone who's curious or wants to take a look is free to do so.

On a side note, this is a super awesome place to start if you're looking to start documenting with us! If you're interested, open up your web browser's developer console, go to the network tab, dig in, and submit a pull request. It's not scary and we're happy to propose edits and review along the way.

As it stands, priority should probably be given to maintaining already documented endpoints and ensuring they're still consistent, as GroupMe will often update the API with new features without telling anyone. However, ANY documentation helps.

***

# I. New Endpoints/Functionality Not Currently Documented (or only partially):

**This is not an exhaustive list, as there are definitely more. However, these are the endpoints we know exist but haven't gotten around to documenting yet.**

**User Purchases (PowerUps/Emoji related):**

- [ ] List user's acquired PowerUps: `GET https://powerup.groupme.com/purchases?scope=user-:user_id`

**Pinned Conversations (Global List & Setting):**

- [x] Get list of pinned conversation IDs: `GET https://api.groupme.com/v4/pinned_conversations`
- [x] Set/update the list of pinned conversation IDs: `POST https://api.groupme.com/v4/pinned_conversations`

**Access Token Management:**

- [x] List active tokens: `GET https://v2.groupme.com/access_tokens`
- [x] Destroy specific token: `POST https://v2.groupme.com/access_tokens/:token_id/destroy`
- [x] Destroy current session token: `POST https://v2.groupme.com/access_tokens/current/destroy`
- [x] Login with username/password: `POST https://v2.groupme.com/access_tokens`

**Multi-Factor Authentication (MFA) Management (entire flow):**

- [x] Initiate phone channel setup/confirm after verification: `POST https://api.groupme.com/v3/user/mfa/channel`
- [x] Send SMS/call PIN: `POST https://api.groupme.com/v3/verifications/:verification_code/initiate`
- [x] Confirm PIN: `POST https://api.groupme.com/v3/verifications/:verification_code/confirm`
- [x] Enable/Disable MFA, returns backup code on enable: `POST https://api.groupme.com/v3/user/mfa`

**Web Pings (Presence/Activity/notif suppression):**

- This is used to disable notifications to your phone while you have the web client open

- [ ] Register web client activity: `POST https://api.groupme.com/v3/web_pings`
- [ ] Get current web ping status: `GET https://api.groupme.com/v3/web_pings`
- [ ] End web client activity session: `POST https://api.groupme.com/v3/web_pings/destroy`

**Client Installation Registration:**

- This is used by official clients, more work is needed to know exactly what it's used for

- [ ] Register client platform/version: `POST https://api.groupme.com/v3/installations`

**Membership States (Global):**

- This is a super cut down list of all of the groups you're in or left/were removed

- [x] Lists user's membership state across various groups: `GET https://api.groupme.com/v3/memberships/states`

**Topic management:**

- [x] Create, requires `topic`, `group_type`: `POST https://api.groupme.com/v3/groups/:parent_group_id/subgroups`
- [x] Update `topic`, `description`, `like_icon`, `group_type`: `PUT https://api.groupme.com/v3/groups/:parent_group_id/subgroups/:subgroup_id`
- [x] Delete a topic: `DELETE https://api.groupme.com/v3/groups/:group_id/subgroups/:subgroup_id`
- [x] Mute notifications: `POST https://api.groupme.com/v3/groups/:group_id/subgroups/:subgroup_id/mute`
- [x] Unmute notifications: `POST https://api.groupme.com/v3/groups/:group_id/subgroups/:subgroup_id/unmute`

**Group Management:**

- [x] Mute notifications for a group: `POST https://v2.groupme.com/groups/:group_id/memberships/mute`
- [x] Unmute notifications for a group: `POST https://v2.groupme.com/groups/:group_id/memberships/unmute`
- [x] Mute all channels, including topics: `POST https://api.groupme.com/v3/groups/:group_id/memberships/mute_all`
- [x] Unmute all channels, including topics: `POST https://api.groupme.com/v3/groups/:group_id/memberships/unmute_all`
- [ ] List group locations: `GET https://api.groupme.com/v3/groups/:group_id/locations`
- [ ] Add a group location, requires signature from location search: `POST https://api.groupme.com/v3/groups/:group_id/locations`
- [ ] Remove a group location: `DELETE https://api.groupme.com/v3/groups/:group_id/locations/:location_id`
- [ ] Search geographical locations: `GET https://api.groupme.com/v1/location/locations?query=`
- [ ] Clear group message history: `POST https://v2.groupme.com/groups/:group_id/clear_history`

**Call Management (v1 & v2, for ACS/Teams Live calls):**

- Calling is *super* undocumented right now. We're not sure if automating them is possible, but here are some calls we have found.

- [ ] Start/Join Call: `GET https://api.groupme.com/v2/conversations/:group_id/call`
- [ ] Keep call active: `PUT https://api.groupme.com/v1/conversations/:group_id/call/heartbeat`
- [ ] Leave/End Call: `POST https://api.groupme.com/v1/conversations/:group_id/call/disconnect`
- [ ] Lookup ACS user ID: `GET https://api.groupme.com/v1/identity/lookup?user_id=`

**URL Preview (v1, for rich content in chat):**

- [ ] `GET https://api.groupme.com/v1/urls/preview?url=`

**Image Service QR Code Preview:**

- [ ] Get raw data for QR code image: `GET https://image.groupme.com/qr/join_group/:group_id/:share_token/preview?format=json`

***

# II. Updates/Inaccuracies in Existing Documentation

The current docs are pretty accurate, but as new features come out, many of the responses have gone out of date. Here's the ones we know for sure.

## `self.md`

**"About" (`GET /users/me`)**

- [x] **Inaccurate/Incomplete Response:** The current API shows a much richer response including MFA status, profile sharing URLs, campus profile details (majors, graduation year, visibility), photo gallery URLs, theme song, and interests. *The documentation example needs to be significantly expanded.*

***

## `groups.md`

**"Index" (`GET /groups`)**
- [ ] **Incomplete Response Fields:** Currently, group objects include many more fields: `muted_until`, `like_icon` (object), approval/join question details, deletion/edit modes, `children_count`, `visibility`, `bot_settings`, etc. Member objects within this also include `roles`.

**"Create" (`POST /groups`)**
- [ ] **Missing Request Parameters:** API includes parameters like `isClosed` and `type` which are currently undocumented.
- [ ] **Incomplete Response Fields:** Created group object is more detailed than the documentation currently suggests.

**"Update" (`POST /groups/:id/update`)**
- [ ] **Missing Request Parameters:** Current API demonstrates updating many more fields: `theme_name`, `like_icon`, `requires_approval`, `show_join_question`, `join_question`, `visibility` (`searchable`, `hidden`, `community`), `group_type` (`closed`, `private`, `announcement`), and `message_deletion_mode`.

**"Show" (`GET /groups/:id`)**
- [ ] **Incomplete Response Fields:** `bot_settings` along with other interesting parameters related to Copilot and group management are present in the API.

**"Rejoin"**
- [ ] The documented `POST /groups/join` with `group_id` in the body differs from the web client's `POST https://v2.groupme.com/groups/:id/memberships/activate` for rejoining/activating. Both might be valid for different scenarios or be old/new versions.

## `dms.md`

**"List Existing DM Channels" (`GET /chats`)**
- [ ] **Incomplete Response Fields:** API chat objects currently include: `message_deletion_period`, `message_deletion_mode`, `requires_approval`, `unread_count`, `last_read_message_id`, `last_read_at`, `message_edit_period`. `last_message` object also has `pinned_at` and `pinned_by`.

**"Index Messages" (`GET /direct_messages`)**
- [ ] **Missing Parameter:** `acceptFiles=1` is used in official clients but untouched in the docs.

***

## Miscellaneous

**`messages.md` - "Index" (`GET /groups/:group_id/messages`)**
- [ ] **Missing Parameter:** `acceptFiles=1` is used in official clients but untouched in the docs.

**`users.md` - "Index Blocks" vs "Block Between?"**
- [ ] Official clients show a `GET /v3/blocks?user=...&otherUser=...` that directly returns the block object if it exists, which is a different behavior/endpoint variant than the two currently documented.

***