--- title: Group Names | Sendblue Docs description: Rename or clear the Apple-visible name of an iMessage group chat via API --- Rename or clear the Apple-visible name of an existing iMessage group chat. The change is applied on the Sendblue line that serves the group and is verified on the device before the API responds: a success response means the new name (or cleared state) was observed on the actual Apple chat, not merely requested. When more than one of your Sendblue numbers is in the group, an eligible number is selected automatically unless you choose one explicitly with `from_number`. The verified name is also persisted as the group’s `group_name`, so the name returned here is the same value your dashboard and group lookups show. Incoming renames and clears made by other group members update `group_name` the same way. > **Note:** Changing or clearing a name requires the group to already have an iMessage chat (at least one iMessage has been sent or received in it), and the Sendblue line serving the group must be online and support group name changes. SMS/RCS group chats do not support Apple group names. ## Availability The API checks compatibility automatically. Requests for a group served by an ineligible Sendblue line return `unsupported_line`. ## Rename or clear a group name ``` POST /api/v2/groups/{group_id}/name ``` Authenticate with either the standard [API credentials](/getting-started/credentials/index.md) headers (`sb-api-key-id` and `sb-api-secret-key`) or an account-scoped temporary API token returned by `POST /v3/auth/tokens`, sent as `Authorization: Bearer `. Line-scoped temporary API tokens cannot perform this account-wide mutation and receive the `403` response described below. #### Request Body | Parameter | Type | Required | Description | | ------------- | ---------------- | -------- | -------------------------------------------------------------------------------------------------------------------- | | `group_name` | string \| `null` | Yes | The new Apple-visible group name (1–255 Unicode characters), or `null` to clear the name | | `from_number` | string \| `null` | No | Which of your Sendblue numbers performs the change. Omit (or pass `null`) to select an eligible number automatically | Passing an empty string is equivalent to `null` and clears the name; whitespace-only strings are rejected. Retrying a request whose state is already applied (for example, renaming to the name the group already has) succeeds without changing anything. When `from_number` is provided, it must be one of your Sendblue numbers serving this group’s iMessage chat, and the change is performed only through that number: if it cannot act — for example it is offline or does not support group name changes — the request fails without falling back to another number. #### Example Request (rename) Terminal window ``` curl -X POST "https://api.sendblue.com/api/v2/groups/sb_group_xxxxxxxx/name" \ -H "sb-api-key-id: YOUR_API_KEY" \ -H "sb-api-secret-key: YOUR_API_SECRET" \ -H "Content-Type: application/json" \ -d '{ "group_name": "Project Falcon" }' ``` #### Example Request (clear) Terminal window ``` curl -X POST "https://api.sendblue.com/api/v2/groups/sb_group_xxxxxxxx/name" \ -H "sb-api-key-id: YOUR_API_KEY" \ -H "sb-api-secret-key: YOUR_API_SECRET" \ -H "Content-Type: application/json" \ -d '{ "group_name": null }' ``` #### Example Request (explicit sender number) Terminal window ``` curl -X POST "https://api.sendblue.com/api/v2/groups/sb_group_xxxxxxxx/name" \ -H "sb-api-key-id: YOUR_API_KEY" \ -H "sb-api-secret-key: YOUR_API_SECRET" \ -H "Content-Type: application/json" \ -d '{ "group_name": "Project Falcon", "from_number": "+15550001111" }' ``` #### Success Response (200) ``` { "status": "OK", "data": { "group_id": "sb_group_xxxxxxxx", "group_name": "Project Falcon", "from_number": "+15550001111" } } ``` | Field | Type | Description | | ------------- | ---------------- | -------------------------------------------------------------------- | | `group_id` | string | The group whose requested name state was verified | | `group_name` | string | The device-verified Apple group name; `""` when the name was cleared | | `from_number` | string \| `null` | The Sendblue number that performed the change | ## Error Responses Errors generated by this endpoint use a machine-readable `error_code` alongside a human-readable `message`: ``` { "status": "ERROR", "error_code": "no_apple_chat", "message": "This group has no Apple iMessage chat yet. Send the first intended message to the group, then retry." } ``` Invalid credentials and rate-limit failures use the standard error envelope and do not include `error_code`: ``` { "status": "ERROR", "message": "Invalid Credentials" } ``` Requests with no credentials return: ``` { "message": "Did not get inputs for authorization" } ``` A line-scoped temporary-token rejection uses `code` instead of `error_code`: ``` { "status": "ERROR", "code": "temporary_token_account_scope_not_allowed", "message": "This line-scoped temporary token cannot access account-wide configuration." } ``` | HTTP Status | Code | Description | | ----------- | --------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | | 400 | `invalid_group_name` | `group_name` is missing, not a string/null, whitespace-only, or longer than 255 characters | | 400 | `invalid_group_id` | `group_id` is not a valid Sendblue group identifier | | 400 | `invalid_from_number` | `from_number` is not a valid phone number string | | 401 | — | Authentication credentials are invalid | | 403 | — | Authentication credentials are missing | | 403 | `code`: `temporary_token_account_scope_not_allowed` | A line-scoped temporary token cannot perform this account-wide mutation | | 404 | `group_not_found` | No group with this `group_id` exists for your account | | 422 | `no_apple_chat` | The group has no Apple iMessage chat yet — send the first intended message to the group, then retry | | 422 | `sms_rcs_only_group` | The group is served over SMS/RCS, which does not support Apple group names | | 422 | `unsupported_line` | The Sendblue line serving this group does not support group name changes | | 422 | `from_number_not_participant` | `from_number` is not one of your Sendblue numbers serving this group’s iMessage chat | | 429 | — | The request rate limit was exceeded — retry with backoff | | 500 | `internal_error` | The change was verified on the device but could not be recorded, or another internal failure occurred; retrying is safe | | 502 | `group_name_update_failed` | The requested group name state could not be verified and recorded | | 503 | — | Authentication is temporarily unavailable — retry shortly | | 503 | `line_offline` | The Sendblue line serving this group is offline — retry when it reconnects | | 503 | `group_name_update_in_progress` | Another name change is still settling for this group — retry shortly | | 504 | `verification_timeout` | The resulting state could not be verified in time and may or may not have applied. Wait five minutes before retrying the same request. | Failed requests are never replayed automatically. ## Propagation Apple propagates group name changes to the other members’ devices; when their devices render the new name is up to Apple and is not guaranteed by this API.