Apple Messages for Business is a channel built to reach customers through Messages on any Apple device. The channel prides itself on its rich set of messaging features including bot and AI capabilities, security, and ability to connect to the wide world of iOS apps and add-ons.
Apple Messages for Business is used for customer service interactions, scheduling tasks, and even payments. This means that customers interact with brands as easily as they message their friends and family. It’s discoverable from Apple Maps, Safari, and Search— or directly embedded into a brand’s website.
Apple Messages for Business requires all businesses to register with Apple before rolling out Messages for Business. A business will need to submit brand information, including addresses and logos, for Apple’s approval. As part of this process, you’ll be prompted to select a Messaging Service Provider. Here is where Zendesk’s Sunshine Conversations comes into play— as a Messaging Service Provider, we are certified by Apple to provide services and solutions for your Messages for Business needs. At the end of the registration process, you’ll receive a unique Messages for Business ID that will be used to connect to Sunshine Conversations.
See Register Your Account for more information.
To set up your Messages for Business Account in the Apple Business Register:
Sign into the Business Register and add a Messages for Business Account.
Go to register.apple.com.
Review the Messages for Business policies and click Next.
You’ll need to provide:
Finally, click Send for review to submit your application to Apple. You’ll be able to see the status of your application at the top of your Messages for Business Account page.
After you’ve been approved by Apple for Messages for Business, you’ll be issued an ID.
You can find the ID by going to your Messages for Business Account page and scrolling down to the Messaging Service Provider section.
From there, click on Test your Messaging Service Provider connection.
After that, you’ll be directed to a page where you can copy your Messages for Business ID.
Apple supports a wide variety of capabilities as seen in the channel capabilities grid. Below is a detailed view of each capability.
Delivery events allow you to track deliveries of Sunshine Conversations messages to Apple Messages for Business by subscribing to the conversation:message:delivery:channel
webhook. Failures to deliver a message to Apple Messages for Business can be detected by subscribing to the conversation:message:delivery:failure
webhook.
Apple’s documentation can be found here.
You will need to do the following:
<div>
container to house the button.The Messages for Business button must contain the following, at minimum:
data-apple-business-id
attribute with the business ID you received when you registered your company with Messages for Business.If you don’t have a Sunshine Conversations account yet, contact us from the Test your Messaging Service Provider connection in the Business Register to continue the integration process. From that page, you can click on the Connect button to send you to the Sunshine Conversations site.
Log into the Apple Business Register.
In a separate tab, log into your Sunshine Conversations Dashboard.
Copy your Messages for Business ID from the Test your Messaging Service Provider connection page in Apple Business Register.
In the Sunshine Conversations Dashboard, select Apple Messages for Business from the list of channel integrations.
Next, complete the following steps to connect your Apple Messages for Business integration.
Since Messages for Business IDs are public, Sunshine Conversations has implemented a security measure to ensure your brand’s Messages for Business ID stays linked to your Sunshine Conversations app. This means that a Messages for Business ID cannot be migrated from one app to another through the dashboard or API. If you need to remove your Apple Messages for Business integration and migrate it to another app, please contact our team for assistance using the help widget in your dashboard. Our team will release the Messages for Business ID on your behalf.
There are 3 different IDs required in the payload:
Apple makes it possible to craft a URL that will bring users into a conversation with the business. For more information on how you can track which link a user has clicked, see the documentation for client intents.
Apple Messages for Business supports several message types that can only be sent using message overrides such as:
For more details and examples on how to send these message types, consult the documentation for message overrides. We recommend using templates where possible, to avoid crafting complex messages each time they’re sent and also to avoid network delays when sending large messages.
Apple Messages for Business supports several message types that have no equivalent within Sunshine Conversations. For more information on how to receive Apple-specific message types, see the documentation for passthrough webhooks.
If the user chooses to close their conversation with the business, the user’s apple
client will be marked as blocked
. See client status for more information.
The existing Sunshine Conversations /messages
and /templates
APIs will not accept payloads larger than 100kb.
In order to remain compatible with Apple’s large payloads, Sunshine Conversations offers separate APIs designed specifically for handling large Apple Messages for Business override payloads. The existing Sunshine Conversations /messages
and /templates
API accept the override parameter inside JSON payloads smaller than 100kb while a separate set of APIs will be offered that are designed to accept much larger payloads, up to 10mb.
Standard Sunshine Conversations API (v1) | Large Apple paylaods equivalent |
---|---|
POST
/v1/apps/:appId/appusers/:userId/messages | POST
/v1/apps/:appId/appusers/:userId/messages/large |
POST
/v1/apps/:appId/templates | POST
/v1/apps/:appId/templates/large |
PUT
/v1/apps/:appId/templates/:templateId | PUT
/v1/apps/:appId/templates/:templateId/large |
The large payload APIs may only be used for apps that have a valid Apple Messages for Business integration configured.
We strongly recommend using templates for sending large Messages for Business messages whenever possible as constantly transferring the same large payload when sending the same content to multiple users generates unnecessary network traffic, which may cause message delivery latency.
If your quick reply requires the use of interactive data because the reply is too large, please use the passthrough API to send that message.
The large payload APIs behave the same as their conventional equivalents, except for two key differences:
override.apple.payload
(or message.override.apple.override
for templates) is required in the request bodyLarge message and template processing is deferred to a processing queue and therefore large payload APIs return 202 Accepted along with a requestId. For example:
{"requestId":"dkgSujU2R62HF3W9PnRIGy8K"}
This requestId
can be used to track the success or failure of the request (message delivery or template creation/update) via two new webhook triggers: request:success
and request:failure
. The request body of request:success
webhooks have a response key, whose value matches the structure returned from the associated standard API. request:failure
webhooks have an “error” key mapping to an object containing error details. Possible error codes can be found here.
Example for POST /v1/apps/:appId/appusers/:userId/messages/large
:
request:success
example:
{
"trigger": "request:success",
"app": { "_id": "564f56151d195e2100c49f13" },
"appUser": { "_id": "4f75e8d7c26953e0df65bb40" },
"requestId": "dkgSujU2R62HF3W9PnRIGy8K",
"timestamp": 1534173863.84,
"response": {
"message": {
"_id": "5b71beb728ef8677a427c769",
...
},
"conversation": {
"_id": "1f706345a613e803962dfe54",
...
}
}
}
request:failure
example:
{
"trigger": "request:failure",
"app": { "_id": "564f56151d195e2100c49f13" },
"appUser": { "_id": "4f75e8d7c26953e0df65bb40" },
"requestId": "dkgSujU2R62HF3W9PnRIGy8K",
"error": {
"code": "bad_request",
"message": "Invalid JSON"
},
"timestamp": 1534173863.84
}
SUNSHINE_CONV_ROOT='https://api.smooch.io'
APP_ID='your_app_id'
APP_USER_ID='app_user_id'
MESSAGE=$(cat <<-END
{
"type": "text",
"text": "Hello non-apple channel",
"role": "appMaker",
"override": {
"apple": {
"payload": {
"type": "interactive",
"interactiveData": {
"bid": "com.apple.messages.MSMessageExtensionBalloonPlugin:0000000000:com.apple.icloud.apps.messages.business.extension",
"data": {
"version": "1.0",
"requestIdentifier": "",
"images": [
{
"data": "base64encoded-image-file",
"identifier": "1"
},
{
"data": "base64encoded-image-file",
"identifier": "2"
},
{
"data": "base64encoded-image-file",
"identifier": "3"
}
],
"listPicker": {
"sections": [
{
"title": "Appetizers",
"order": 0,
"items": [
{
"title": "Tacos",
"order": 0,
"identifier": "taco-appetizer",
"imageIdentifier": "2"
},
{
"title": "Burritos",
"order": 1,
"identifier": "burrito-appetizer",
"imageIdentifier": "3"
}
]
},
{
"title": "Meals",
"order": 1,
"items": [
{
"title": "Tacos",
"order": 0,
"identifier": "taco-meal",
"imageIdentifier": "2"
},
{
"title": "Burritos",
"order": 1,
"identifier": "burrito-meal",
"imageIdentifier": "3"
}
]
}
]
}
},
"receivedMessage": {
"style": "small",
"title": "Food Picker",
"subtitle": "Let\"s eat!",
"imageIdentifier": "1"
},
"replyMessage": {
"style": "small",
"title": "Selected food",
"subtitle": "Nutrition"
}
}
}
}
}
}
END
)
curl $SUNSHINE_CONV_ROOT/v1/apps/$APP_ID/appusers/$APP_USER_ID/messages/large \
-X POST \
-H 'content-type: application/json' \
-H 'authorization: Bearer your-account-jwt' \
-d "$MESSAGE"
curl $SUNSHINE_CONV_ROOT/v1/apps/$APP_ID/templates/large \
-X POST \
-H 'content-type: application/json' \
-H 'authorization: Bearer your-account-jwt' \
-d '{
"name": "test-template-1234",
"message":'"$MESSAGE"'
}'
TEMPLATE_ID='your_template_id'
curl $SUNSHINE_CONV_ROOT/v1/apps/$APP_ID/templates/$TEMPLATE_ID/large \
-X PUT \
-H 'content-type: application/json' \
-H 'authorization: Bearer your-account-jwt' \
-d '{
"name": "new-template-name",
"message":'"$MESSAGE"'
}'
Just like the traditional /messages
API, /messages/large
can be used to send messages to users on channels other than Apple Messages for Business. If you wish to target a user’s Apple client specifically you can do so via channel targeting.
Sending a large template is done using the standard /messages
API, as described here.
It’s possible to convert a standard template to a large one by calling the PUT /templates/:templateId/large
endpoint. Converting a large template to a standard one is also possible by calling the PUT /templates/:templateId
endpoint and providing the message in the request body.
Large templates are deleted the same way as standard templates, by calling the DELETE /templates/:templateId
endpoint.
Fetching large templates can be achieved by using the same APIs as for standard templates (GET /templates
and GET /templates/:templateId
). An isLarge
property set to true
will be included only for large templates (it won’t be present for standard templates.) Note that when retrieving a large template, the response will not include the Apple override section.