Group Names

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 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 <token>. 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)

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)

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)

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.