Reference
Group conversations
Native iMessage groups use the same number ownership boundary as one-to-one sends. Every mutation returns a refreshed group, so an integration can store exactly what Messages accepted instead of guessing.
POST/v1/groups
Create a native iMessage group and send its first message.
| number_id* | uuid | A number held by this project. |
| participants* | string[] | 2–32 different phone numbers or Apple ID emails. |
| initial_message* | string | 1–20,000 characters. Group creation and the first message are one operation. |
curl -X POST https://api.missblue.dev/v1/groups \
-H "Authorization: Bearer $MISS_BLUE_KEY" \
-H "Content-Type: application/json" \
-d '{
"number_id": "8f14e45f-ceea-467a-9a1b-1b1e5f9e2c3d",
"participants": [
"+15555550100",
"+15555550101"
],
"initial_message": "Welcome to the project group."
}'Response
{
"chat_id": "iMessage;+;chat123456789",
"participants": [
{ "id": "p1", "handle": "+15555550100", "name": "Ari" },
{ "id": "p2", "handle": "+15555550101", "name": "Sam" },
{ "id": "self", "handle": "+16465550142", "is_self": true }
]
}- 400Fewer than two different participants, too many participants, or an empty first message.
- 404The number is outside this project.
Pull the group's current name, photo URL, and participants.
curl -X GET https://api.missblue.dev/v1/groups/iMessage%3B%2B%3Bchat123456789 \
-H "Authorization: Bearer $MISS_BLUE_KEY"Response
{
"chat_id": "iMessage;+;chat123456789",
"title": "Install team",
"photo_url": "https://api.missblue.dev/v1/attachments/…/view",
"participants": [
{ "id": "p1", "handle": "+15555550100", "name": "Ari" },
{ "id": "self", "handle": "+16465550142", "is_self": true }
]
}- 404No such group on a number held by this project.
PATCH/v1/groups/{chat_id}
Rename a group and/or replace its photo.
Upload the JPEG or PNG first. To remove the current photo, omit photo_attachment_id and send remove_photo: true. The complete refreshed group is returned.
| title | string | At most 256 characters. |
| photo_attachment_id | uuid | Uploaded JPEG or PNG. |
| remove_photo | boolean | Cannot be true while replacing the photo. |
curl -X PATCH https://api.missblue.dev/v1/groups/iMessage%3B%2B%3Bchat123456789 \
-H "Authorization: Bearer $MISS_BLUE_KEY"Response
{
"chat_id": "iMessage;+;chat123456789",
"title": "Install team",
"photo_url": "https://api.missblue.dev/v1/attachments/…/view",
"participants": [
{ "id": "p1", "handle": "+15555550100", "name": "Ari" },
{ "id": "self", "handle": "+16465550142", "is_self": true }
]
}Add or remove one group participant.
Set add to false to remove. The response is the complete refreshed group.
curl -X POST https://api.missblue.dev/v1/groups/iMessage%3B%2B%3Bchat123456789/participants \
-H "Authorization: Bearer $MISS_BLUE_KEY" \
-H "Content-Type: application/json" \
-d '{
"participant": "+15555550102",
"add": true
}'Response
{
"chat_id": "iMessage;+;chat123456789",
"title": "Install team",
"participants": [
{ "id": "p1", "handle": "+15555550100", "name": "Ari" },
{ "id": "p3", "handle": "+15555550102", "name": "Jo" },
{ "id": "self", "handle": "+16465550142", "is_self": true }
]
}