Integration

  • Version: 3.7
  • Last update: November 9, 2022

Messages for Business is a service that allows your clients to communicate directly with their users through your Messaging Service Provider (MSP) platform using the Messages app. An MSP implements the server-to-server REST API solutions on their messaging platform which makes it possible to send and receive texts and photos, request payment through Apple Pay, and much more.

This drawing illustrates the relationship between a business, an MSP, the Messages for Business service, and users. The MSP platform handles user message routing between Messages for Business service and the business. For more information on these accounts and how to qualify for them, see MSP Onboarding.

“MSP
Communicate with users using Messages for Business

Apple devices running iOS 11.3 and later or macOS 10.13.4 and later support Messages for Business.

For more information about the visual design of Messages for Business, see Apple Human Interface Guidelines.

Required Features

Apple requires that you build and demonstrate support for the following features for approval to connect brands to Messages for Business:

Feature Bot/API Agent Triggered* Description
Receiving and Sending Messages Send and receive text, international characters, and emojis.
Receiving and Sending attachments Send and receive commonly known type files up to 100MB between your platform and the user.
Tapback Reactions N/A Detect user tapbacks.
Receiving Closed Conversation Messages Notify live agents and automated agents of customer opt-out.
Rich Link Messages Every URL sent by an automated or human agent should be recognised and sent as a rich link.
Quick Reply Messages Optional Send quick reply choices to end user.
List Picker Message Optional Single selection, multi selection and multi section with icons for send/received list pickers as well as images.
Time Picker Message Optional Send time pickers including icons.
Apple Pay Message Optional Send an Apple Pay payment request.
Authentication Message Optional Support OAuth2 inline authentication.
New Authentication Message Optional New OAuth2 inline authentication.
iMessage Apps Optional Support iMessage apps for advanced interactions.
Form Message Support forms interactions.
Typing Indicator Message Required Show bidirectional typing indicators.
Routing based on entrypoint parameters Required Route new conversations using intentID and groupID attributes.
Channel settings and Landing Page Required Centrally host channel settings and provide a landing page with account linking
Device capabilities Required Support alternate handling for devices with different capabilities.

The MSP must provide the business with easy-to-use tools necessary to build rich object payloads, such as List Pickers, Message Forms, etc. This allows a business to have a library of ready to use rich objects that can be used by agents and bot builders.

*Agent Triggered: the agent or operator can trigger this message type via an automated flow, or a canned response/object available in the agent console.

Authorizing Messages

When exchanging messages between Messages for Business service and the MSP platform, the server sending the message must authorize the HTTP request by setting the Authorization header field with a signed JSON Web Token (JWT), which the receiving server decodes. Messages for Business requires this field, and the receiving server should reject the request when the field is not present.

Messages for Business uses a subset of the JWT fields, described here:

Name Type Description
alg string A string used in the header, identifying the algorithm used to encode the payload. The alg value is always HS256 when exchanging messages with Messages for Business.
aud string A claim that is a string, or array of strings, identifying the recipients of the JWT. The value should be a string when the JWT has one recipient; otherwise, it should be an array of strings where each string represents a recipient. The aud value is always the MSP ID when exchanging messages with Messages for Business. This value is used when sending messages from the business to the MSP platform
iss string A claim that is a string identifying the principal that issued the JWT. The value is always the MSP ID when exchanging messages with Messages for Business. This value is used with traffic coming from the MSP platform to the business.
iat dateTime A claim that is a numeric date—that is, an integer—identifying the time at which the JWT was issued. The value is the number of seconds from 1970-01-01T00:00:00Z UTC until the specified UTC date and time, ignoring leap seconds. For more information, see the Terminology section in RFC 7519.

Create a JSON Web Token

Sign and verify all messages in Messages for Business by creating a signed JWT. After registering for Messages for Business as an MSP, you receive the following:

  • An MSP ID that identifies the platform. This is not the same as the business ID you receive after registering for Messages for Business.
  • A Messaging API secret key that is a Base64-encoded string. Decode the string before using the key to sign the JWT. When receiving an HTTP request from Messages for Business, verify that Messages for Business signed the request with the secret key.

The JWT has three parts, each separated with a period ( . ): the Javascript Object Signing and Encryption (JOSE) header, the claims, and the Base64-encoded Messaging API secret. The JWT looks similar to the following:

hhhhhhh.ccccccc.ssssssss

For more information about the JWT specifications, see RFC 7519.

A decoded JWT authorization header has the following header and claims for each message coming from the Messaging service to the MSP platform:

header
{
  "alg": HS256,
}
claims
{
  "aud": <CSP-ID>,
  "iat": <issued at unix-timestamp (in seconds)>
}

The decoded JWT authorization header from the MSP platform to the Messaging service has the following header and claims for each message:

header
{
  "alg": HS256,
}
claims
{
  "iss": <MSP-ID>,
  "iat": <issued at unix-timestamp (in seconds)>
}

Generate authorization tokens at least once every hour, and reject tokens with an iat timestamp older than an hour.

Manage the Messaging API Secret Key

The registering agent should record and securely store the Messaging API secret key for safekeeping. If the secret key becomes compromised, the registering agent should provision a new key using the Messages for Business web portal.

When using a new secret key, honor the authorization tokens signed with both the old and new keys for a short period of time. After deploying the token signed with the new secret key—and ensuring its use throughout the MSP platform environment—the registering agent should revoke the old key using the Apple Business Register web portal.

Add the JWT to Your Messages

Once you have your signed JWT, format the Authorization field value with the string Bearer followed by a space, followed by your signed JWT.

POST https://mspgw.push.apple.com/v1/message

{
  "Destination-Id": "urn:mbid:AQAAYy <truncated>",
  "Source-Id": "DEF123GH-b0ad-<truncated>",
  "Content-Type": "application/json",
  "id": "4102c4b3-316 <truncated>",
  "Authorization": "Bearer eyJhbGciOiJIUzI1NiIs.<truncated>"
}

The following code shows an example of a JWT authorization header from the Messaging service to an MSP platform:

POST /message

{
    "Destination-Id": "DEF123GH-b0ad <truncated>",
    "Source-Id": "urn:mbid:AQ/quv4JIAJyVALyKtW <truncated>",
    "Content-Type": "application/json",
    "id": "3608321f-<truncated>",
    "Authorization": "Bearer eyJhbGciOiJIUzI1NiIs.<truncated>"
}

First Message Exchange

To exchange text messages between customers and businesses, an MSP integrates their platform with Messages for Business. To integrate, the MSP provider:

  1. Implement the /message endpoint that Messages for Business uses to forward messages sent by customers. For more information, see Messages Received.
  2. Authorizes the exchange of messages by creating a JSON web token (JWT) and using it in the authorization header field. For more information, see Authorizing Messages.
  3. Uses the Messages for Business REST API to send replies from the business to their users. For more information, see Messages Sent.