# Update a group and its members

Add or remove members, rename a group, change its description, image, topics, or access settings from your own systems.

One call can change several things at once, and the response says which of them changed. The account behind your access token has to be the group's owner or an admin of it; the account that created the group is its owner. See [Generate an access token](https://begenuin.com/developers/developer-resources/api/generate-access-token-using-authentication-api) for the token.

## Endpoint

`PATCH /api/thirdparty/update_conversation/{chat_id}`

| Environment | Base URL |
| --- | --- |
| Production | https://api.begenuin.com |
| QA | https://api.qa.begenuin.com |

`chat_id` is the group's UUID, from [Create a group in a community](https://begenuin.com/developers/developer-resources/api/create-a-group-programmatically-within-community-using-create-group-api). Send the token as a bearer token in the `Authorization` header, and the fields as a JSON body with the `Content-Type: application/json` header.

## Parameters

Send at least one of these. Fields you leave out are unchanged.

| Parameter | Type | Description |
| --- | --- | --- |
| members_added | array | Accounts to add, each {"user_id": "<uuid>"} or {"phone_number": "<digits>"}. At least one entry. A number without an account gets a pending account. |
| members_removed | array of strings | UUIDs of members to remove. At least one entry. |
| subscribers_removed | array of strings | UUIDs of subscribers, people who follow the group without being members, to unsubscribe. At least one entry. |
| name | string | New name. |
| description | string | New description, up to 300 characters. Send tags with it. |
| tags | string | Comma-separated discovery tags. |
| dp | string | File name of a new group image, uploaded to Genuin's media storage first. |
| topics | array of integers | Topic ids. |
| settings | object | {"discoverable": true}. The endpoint only accepts true. |
| actions | array | New visibility and posting rules, with the same ids and pairing rules as Create a group in a community. Not allowed on a welcome group. |
| language | string | Language code, such as en. |
| location | object | {"latitude": <-90 to 90>, "longitude": <-180 to 180>}. |

A member who is both added and removed in the same call is rejected.

## Returns

Returns `200 OK` with the members that were added and removed and a boolean per field that says whether it changed. Added members get an invitation notification; removed members get a removal notification.

## Request

```bash title="cURL"
curl -X PATCH https://api.begenuin.com/api/thirdparty/update_conversation/{{CHAT_ID}} \
  -H "Authorization: Bearer {{GN_ACCESS_TOKEN}}" \
  -H "Content-Type: application/json" \
  -d '{
    "members_added": [{ "user_id": "{{USER_ID}}" }],
    "members_removed": ["{{OTHER_USER_ID}}"],
    "name": "Race recaps 2026",
    "description": "Finish-line videos from this season #recap",
    "tags": "recap,races,2026"
  }'
```

## Response

```json title="Response"
{
  "code": 200,
  "message": "Conversation updated successfully.",
  "data": {
    "members_added": [
      {
        "member_id": "9a42d4ed-3720-49cb-8697-57d7e8269b9d",
        "name": "Avery Chen",
        "bio": null,
        "nickname": "averyc",
        "phone": "14155550111",
        "is_brand_system_user": false,
        "is_avatar": true,
        "status": 2,
        "role": 2,
        "profile_image": "sloth",
        "profile_image_s": "",
        "profile_image_m": "",
        "profile_image_l": ""
      }
    ],
    "members_removed": ["b12f13af-ef5a-4906-b0a0-2995e106200d"],
    "subscribers_added": [],
    "subscribers_removed": [],
    "requester_removed": [],
    "name_updated": true,
    "description_updated": true,
    "dp_updated": false,
    "topics_updated": false,
    "settings_updated": false
  }
}
```

The `_updated` flags are `false` when you didn't send the field or sent the current value. `subscribers_added` lists removed members who stay as subscribers, and `requester_removed` lists pending join requests that an added member no longer needs.

## Errors

Every error response carries an HTTP status, a string `code`, a `message`, and a `data` object. Match on `code`.

| HTTP status | code | Cause | Fix |
| --- | --- | --- | --- |
| 400 Bad Request | none | chat_id isn't a UUID, the body has no updatable field, or a field failed validation. The body is {"data": {}} with no code or message. | Check the Parameters table. |
| 401 Unauthorized | 5159 | The token's account isn't the group's owner or an admin, actions was sent for a welcome group, or subscribers_removed was sent for a direct group. Message: Invalid Use of API. | Call from the owner's or an admin's account. |
| 404 Not Found | 5044 | The group doesn't exist, or is deleted or flagged. | Check chat_id. |
| 422 Unprocessable Entity | 5158 | The update couldn't be applied. Message: Could not update the group.. | Retry once. If it persists, contact the Genuin team with the request timestamp. |

## Limitations

- **Discoverable only**: `settings.discoverable` can be set to `true` but not back to `false`.
- **Owner stays**: The owner can't be removed or replaced through this endpoint.
- **Rate limit**: There's no rate limit on this endpoint.

## See also

- [Create a group in a community](https://begenuin.com/developers/developer-resources/api/create-a-group-programmatically-within-community-using-create-group-api)
- [Post a video to a group](https://begenuin.com/developers/developer-resources/api/post-and-share-a-video-within-a-group-using-the-post-video-api)
- [Add members to a community](https://begenuin.com/developers/developer-resources/api/add-members-to-a-community-programmatically-api)
- [Generate an access token](https://begenuin.com/developers/developer-resources/api/generate-access-token-using-authentication-api)
- [Handle API errors](https://begenuin.com/developers/developer-resources/api/handle-api-errors)