---
title: "Apple Messages incoming messages"
description: "Get started with CM.com's Developer API Documentation for inbound Apple Messages for Business. Find everything you need to implement inbound Apple Messages for Business for your business."
canonical: "https://docs.cm.com/messaging/other-channels/apple-messages-for-business-inbound"
---

# Apple Messages incoming messages

> Get started with CM.com's Developer API Documentation for inbound Apple Messages for Business. Find everything you need to implement inbound Apple Messages for Business for your business.

Source: https://docs.cm.com/messaging/other-channels/apple-messages-for-business-inbound

This page describes the incoming (MO) messages you can receive from Apple Messages for Business users through the CM.com Messaging API.

For the generic behaviour of inbound messages across all channels, see [Incoming messages](https://docs.cm.com/messaging/business-messaging/incoming-messages).

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

:::warning[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](https://docs.cm.com/messaging/business-messaging/incoming-messages#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

```json
{
    "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

```json
{
    "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

```json
{
    "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.

:::warning[Note]
This type of message is considered to be converted into an incoming event in the future.
:::

#### Example message

```json
{
    "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

```json
{
    "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.

| Field | Remarks |
| - | - |
| identifier | Identifier of the page. |
| subTitle | Subtitle of the page which contains the question. |
| type | Type of page: `select`, `picker`, `datePicker` or `input`. |
| postbackData | Postback data of the selected predefined answer. Always empty for page type `input`. |

```json
"custom": {
  "formPage": {
    "identifier": "0",
    "subTitle": "Which of the following product do you like?",
    "type": "select",
    "postbackData": "AMB"
  }
}
```

#### Example message

Answer of a `select` page.

```json
{
    "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.

```json
{
    "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

```json
{
    "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.

```json
{
    "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.

:::warning[Note]
This type of message is considered to be converted into an incoming event in the future.
:::

#### Example message

```json
{
    "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.

```json
{
    "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"
}
```