Guides

Apple Messages for Business

Suggest Edits

The main difference to other channels is the fact that Apple Messenger for Business uses id's (more technically GUIDs) as a sender and recipient. Due to technical limitations, when you receive an MO message, the id in the to: field will be formatted without the dashes (-).

🚧

Note

Unlike other channels, Apple Messages for Business had it's name changed several times.
Incoming messages for Apple Messages for Business will still state channel with the previous name Apple Business Chat.

Media message

See also receiving media messages

Suggestions

When the customer clicks on an item in a quick reply suggestion list, the label of the selected element will be sent as text in the response.

Example message

{
    "reference": "515836578",
    "messageContext": "",
    "from": {
        "number": "00000000-0000-0000-0000-000000000000",
        "name": ""
    },
    "to": {
        "number": "11111111111111111111111111111111"
    },
    "message": {
        "text": "Edit appointment",
        "media": {
            "mediaUri": "",
            "contentType": "",
            "title": ""
        },
        "custom": {
        }
    },
    "groupings": [
        "",
        "",
        ""
    ],
    "time": "2023-09-19 16:04:45",
    "timeUtc": "2023-09-19T14:04:45",
    "channel": "Apple Business Chat"
}

List picker

When the end-user clicks on an item in a list picker, the reply will have the label and media of the selected element in the response.

When the list picker has multiple selections enabled, each selected item will be a separate incoming message.

Example message

{
    "reference": "515836578",
    "messageContext": "",
    "from": {
        "number": "00000000-0000-0000-0000-000000000000",
        "name": ""
    },
    "to": {
        "number": "11111111111111111111111111111111"
    },
    "message": {
        "text": "Ace of Diamonds",
        "media": {
            "mediaUri": "https://cdn-1.messaging.cm.com/fileproxy/files/f9087c40468d427995f5ae69076e2850",
            "contentType": "image/png",
            "title": "ace_of_diamonds.png"
        },
        "custom": {
        }
    },
    "groupings": [
        "",
        "",
        ""
    ],
    "time": "2023-09-19 16:04:45",
    "timeUtc": "2023-09-19T14:04:45",
    "channel": "Apple Business Chat"
}

Time picker

When the end-user clicks on an item in a time picker, the reply will have the date and time of the selected time slot in the response.

Example message

{
    "reference": "515836578",
    "messageContext": "",
    "from": {
        "number": "00000000-0000-0000-0000-000000000000",
        "name": ""
    },
    "to": {
        "number": "11111111111111111111111111111111"
    },
    "message": {
        "text": "2023-10-13T09:00:00.0000000Z",
        "media": {
            "mediaUri": "",
            "contentType": "",
            "title": ""
        },
        "custom": {
        }
    },
    "groupings": [
        "",
        "",
        ""
    ],
    "time": "2023-09-19 16:04:45",
    "timeUtc": "2023-09-19T14:04:45",
    "channel": "Apple Business Chat"
}

Closing the conversation

When the end-user wants to opt out of receiving any further messages, a Close message will be sent.
You will be no longer allowed or able to send messages to this end-user.

🚧

Note

This type of message is considered to be converted into an incoming event in the future.

Example message

{
    "reference": "515836576",
    "messageContext": "",
    "from": {
        "number": "00000000-0000-0000-0000-000000000000",
        "name": ""
    },
    "to": {
        "number": "11111111111111111111111111111111"
    },
    "message": {
        "text": "CLOSE_CONVERSATION",
        "media": {
            "mediaUri": "",
            "contentType": "",
            "title": ""
        },
        "custom": {
        }
    },
    "groupings": [
        "",
        "",
        ""
    ],
    "time": "2023-09-19 17:04:45",
    "timeUtc": "2023-09-19T15:04:45",
    "channel": "Apple Business Chat"
}

App extension

After you've sent an app extension message, it's possible the end user can send one back based on the performed actions in the iMessage app.

The data passed by the app will be sent as text and media in the response.

Example message

{
    "reference": "515836576",
    "messageContext": "",
    "from": {
        "number": "00000000-0000-0000-0000-000000000000",
        "name": ""
    },
    "to": {
        "number": "20241c26-f863-4faf-8bb2-ad4213641caa"
    },
    "message": {
        "text": "?data=passed-to-app&data2=more-data-passed-to-app",
        "media": {
            "mediaUri": "https://cdn-2.messaging.cm.com/fileproxy/files/5c65eef9b95e4102a72d6817b6b0d98a",
            "contentType": "image/jpeg",
            "title": "Tic-Tac-Toe-move-1.jpg"
        },
        "custom": {
        }
    },
    "groupings": [
        "",
        "",
        ""
    ],
    "time": "2023-09-19 17:04:45",
    "timeUtc": "2023-09-19T15:04:45",
    "channel": "Apple Business Chat"
}

Form

After the end-user has gone through your form pages, each answer will be forwarded as a separate incoming message.

Each message will contain the label and media of the selected answer and metadata about the originating page and answer in the custom/formPage item.

FieldRemarks
identifierIdentifier of the page.
subTitleSubtitle of the page which contains the question.
typeType of page: select, picker, datePicker or input.
postbackDataPostback data of the selected predefined answer. Always empty for page type input.
"custom": {
  "formPage": {
    "identifier": "0",
    "subTitle": "Which of the following product do you like?",
    "type": "select",
    "postbackData": "AMB"
  }
}

Example message

Answer of a select page.

{
    "reference": "515836576",
    "messageContext": "",
    "from": {
        "number": "00000000-0000-0000-0000-000000000000",
        "name": ""
    },
    "to": {
        "number": "11111111111111111111111111111111"
    },
    "message": {
        "text": "Apple Messages for Business",
        "media": {
            "mediaUri": "https://cdn-2.messaging.cm.com/fileproxy/files/a81992132a6048f88f5b781e7e35a899",
            "contentType": "image/png",
            "title": "amb.png"
        },
        "custom": {
            "formPage": {
              "identifier": "0",
              "subTitle": "Which of the following product do you like?",
              "type": "select",
              "postbackData": "AMB"
            }
        }
    },
    "groupings": [
        "",
        "",
        ""
    ],
    "time": "2023-09-19 17:04:45",
    "timeUtc": "2023-09-19T15:04:45",
    "channel": "Apple Business Chat"
}

Answer of a picker page.
The main difference with select page is that picker can never contain media.

{
    "reference": "515836576",
    "messageContext": "",
    "from": {
        "number": "00000000-0000-0000-0000-000000000000",
        "name": ""
    },
    "to": {
        "number": "11111111111111111111111111111111"
    },
    "message": {
        "text": "Europe",
        "media": {
            "mediaUri": "",
            "contentType": "",
            "title": ""
        },
        "custom": {
            "formPage": {
              "identifier": "1",
              "subTitle": "Where are you from?",
              "type": "picker",
              "postbackData": "EU"
            }
        }
    },
    "groupings": [
        "",
        "",
        ""
    ],
    "time": "2023-09-19 17:04:45",
    "timeUtc": "2023-09-19T15:04:45",
    "channel": "Apple Business Chat"
}

Answer of a datePicker page

{
    "reference": "515836576",
    "messageContext": "",
    "from": {
        "number": "00000000-0000-0000-0000-000000000000",
        "name": ""
    },
    "to": {
        "number": "11111111111111111111111111111111"
    },
    "message": {
        "text": "09/26/2023",
        "media": {
            "mediaUri": "",
            "contentType": "",
            "title": ""
        },
        "custom": {
            "formPage": {
              "identifier": "2",
              "subTitle": "When did you arrive?",
              "type": "datePicker",
              "postbackData": "2023-09-25T22:00:00Z"
            }
        }
    },
    "groupings": [
        "",
        "",
        ""
    ],
    "time": "2023-09-19 17:04:45",
    "timeUtc": "2023-09-19T15:04:45",
    "channel": "Apple Business Chat"
}

Answer of a input page. Since an input page has no predefined answers, it can never contain postback data.

{
    "reference": "515836576",
    "messageContext": "",
    "from": {
        "number": "00000000-0000-0000-0000-000000000000",
        "name": ""
    },
    "to": {
        "number": "11111111111111111111111111111111"
    },
    "message": {
        "text": "More images",
        "media": {
            "mediaUri": "",
            "contentType": "",
            "title": ""
        },
        "custom": {
            "formPage": {
              "identifier": "3",
              "subTitle": "What would you like to see added?",
              "type": "input"
            }
        }
    },
    "groupings": [
        "",
        "",
        ""
    ],
    "time": "2023-09-19 17:04:45",
    "timeUtc": "2023-09-19T15:04:45",
    "channel": "Apple Business Chat"
}

Authentication

After the end-user has successfully authenticated, you will receive OAuth tokens via the configured redirect URL. Your redirect URL needs to forward an authentication status to Apple in order to close the authentication flow.

Your forwarded authentication status will be mapped to an incoming message.

🚧

Note

This type of message is considered to be converted into an incoming event in the future.

Example message

{
    "reference": "515836576",
    "messageContext": "",
    "from": {
        "number": "00000000-0000-0000-0000-000000000000",
        "name": ""
    },
    "to": {
        "number": "11111111111111111111111111111111"
    },
    "message": {
        "text": "Success",
        "media": {
            "mediaUri": "",
            "contentType": "",
            "title": ""
        },
        "custom": {
            "rawPayload": {
              "authenticated": true
            }
        }
    },
    "groupings": [
        "",
        "",
        ""
    ],
    "time": "2023-09-19 17:04:45",
    "timeUtc": "2023-09-19T15:04:45",
    "channel": "Apple Business Chat"
}

Metadata

When an end-user starts a chat session through your app or website, you can choose to include the context for the chat entry point by setting up the intent: purpose of the chat, and group: type of department or individuals best qualified to handle the conversation.

Do note that the intent and group will only be sent in the first message of the conversation.

{
    "reference": "515836577",
    "messageContext": "",
    "from": {
        "number": "00000000-0000-0000-0000-000000000000",
        "name": ""
    },
    "to": {
        "number": "11111111111111111111111111111111"
    },
    "message": {
        "text": "Hi",
        "media": {
            "mediaUri": "",
            "contentType": "",
            "title": ""
        },
        "custom": {
            "intent": "apidocs",
            "group": "techsupport"
        }
    },
    "groupings": [
        "",
        "",
        ""
    ],
    "time": "2023-09-19 15:42:28",
    "timeUtc": "2023-09-19T13:42:28",
    "channel": "Apple Business Chat"
}

Updated 9 months ago