Check whether a participant set would be an iMessage or text group | Message Blue

curl -X POST https://api.messageblue.ai/checkGroupIMessage \
     -H "X-App-Id: <apiKey>" \
     -H "Content-Type: application/json" \
     -d '{
  "participants": [
    "+14155551234",
    "+14155556789"
  ]
}'

{
  "ok": true,
  "data": {
    "agent": "+14155550123",
    "isIMessageGroup": true,
    "service": "iMessage",
    "participants": [
      {
        "handle": "+14155551234",
        "isIMessage": true,
        "service": "iMessage",
        "source": "buddy_check"
      },
      {
        "handle": "+14155556789",
        "isIMessage": true,
        "service": "iMessage",
        "source": "buddy_check"
      }
    ]
  },
  "meta": {
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "timestamp": "2026-07-10T06:00:00.000Z"
  }
}

Opens Messages on a Mac agent, adds the participants to a new compose window (without sending), and reads whether the draft is iMessage or SMS/Text Message — same UI signal as checkIMessage. Does not create a group or send a message. A group is iMessage only when the compose UI shows iMessage for that participant set.

Authentication

X-App-Idstring

Your MessageBlue App ID, sent in clear on every request. It is paired with request signing: each request is also signed with your App Secret (see the Authentication tag). The App Secret itself is NEVER transmitted — it is only the HMAC signing key.

Request

This endpoint expects an object.

participantslist of stringsRequired

At least two distinct phone numbers (E.164) or email handles to evaluate as a group.

agentstringOptional

Optional agent iMessage number to run the check. Must be owned by the caller's account. If omitted, uses any online agent owned by the account.

agentNumberstringOptional

Alias of agent (createGroupChat-style field name).

forcebooleanOptionalDefaults to false

If true, skip chat.db and use Messages buddy-check for every participant.

Response

Check completed

okboolean

dataobject

Endpoint-specific payload wrapped in a standard success envelope.

metaobject

Errors

400

Bad Request Error

401

Unauthorized Error

500

Internal Server Error

503

Service Unavailable Error

504

Gateway Timeout Error