Tutorial Setup

This step-by-step tutorial helps you to design and integrate your Messaging Service Provider (MSP) platform with the Messages for Business REST API.

NOTE You should configure and implement all Messages for Business features in this tutorial on your test server.

The code examples provided are in the Python programming language, and HTTP protocol is the fundamental architecture, but you can adapt the code for use in any language. This tutorial relies on a test server platform in a testing environment you provide and configure as an MSP. Do not use a production server in a production environment. Your MSP test server platform needs access to the web so it can talk to the Messages for Business service.

You'll learn the following in this tutorial:

  • Experiment with different message types, from basic text messaging to sending Apple Pay payments.
  • Use Messages for Business with different message types, such as text and interactive, and the handling of small to large attachments.

By the end of this tutorial, you should be familiar with the concepts and features Messages for Business offers to businesses, including familiarity with implementing these features on your MSP platform.

All tutorials follow the sending and receiving data diagram below. A user’s, device sends a message to the Messages for Business service that posts the user’s message to the MSP endpoint. The MSP platform digests the message and forwards it to the appropriate business agent for a response. The business agent responds and sends the message back to the MSP platform that posts it to the Messages for Business service, and from there it is forwarded back to the user’s Device.

Setting Up Your Accounts on Apple Business Register

You must enter all MSP, Messages for Business accounts, brands, team members, and organization details into Apple Business Register to create the accounts needed for this tutorial.

Apple Business Register is a self-service portal, and is mostly self-explanatory with a few key items of note:

  • You have to apply and be approved for your company to offer MSP services. If you don't see Messaging Service Provider as an item in Apple Business Register, contact your Messages for Business account manager to determine the application process status.
  • Apple Business Register generates several key values that you'll need for your servers, such as MSP ID, Business ID, and a secret passphrase. Other parameters you have to enter into Apple Business Register are organizational details, team member details, brand colors, brand logos, and your server URLs.
  • Each Business ID is associated with an unique MSP ID. Internal test Business IDs have no brand. Commercial Business IDs must be associated with a brand in Apple Business Register, which requires an approval step by the brand review team that may take several business days.

Configuring Your MSP Test Server

When prompted, you can refer to the following information throughout the exercises in this tutorial:

  • MSP ID: a unique UUID you receive upon approval of your MSP account
  • Business ID: a unique UUID you receive upon approval of your Messages for Business account
  • Secret passphrase for API: a Base64-encoded string
  • MSP message endpoint: https://<your.endpoint.host>/message
  • Information obtained from your Apple Business Register MSP account

NOTE For legacy reasons, code samples and some parts of the Messages for Business documentation may refer to "CSP ID" instead of "MSP ID". CSP stands for Customer Service Provider and is equivalent to the new term Messaging Service Provider (MSP).

MSP endpoint SSL certificate requirements

Your SSL certificate must meet the HTTPS requirements needed to connect to the Messages for Business endpoints. Your SSL certificate should contain the following:

  • Valid SSL certificate
  • Issued name on the SSL certificate must match the hostname
  • Certificate must include the entire trust chain, including CAs and root
  • Certificate must be in Oracle Java 8+ framework’s default trust store, meaning signed by trusted CAs, supported encryption, and format

NOTE Messages for Business does not allow the use of Ngrok hosts and other similar firewall-defeating technologies. The use of these technologies may result in declined requests for messaging, client landing page, or authentication endpoints.

Messages for Business Server Endpoints

The endpoints allow messages to be routed between the Messages for Business service and your platform. See How to Set Up Your Endpoint.

  • Production: https://mspgw.push.apple.com/v1/message
  • Staging: https://mspgw-int.push.apple.com/v1/message

Use the staging endpoint to develop and test your server changes. Even though you can message users through the staging endpoint, it has a load limit and is not intended for production messages.

TIP Messaging requests arrive at your registered MSP base URL plus /message.

Tools

This section includes the tools used throughout this tutorial.

Apple Devices

To test and verify the exercises from both your console and user-side, you’ll need

  • an Apple supported device that can run iOS 11.3 or later.
  • an Apple ID setup under the Messsage App settings / iMessage.

TIP If your device continues to display Waiting for activation, use the following link to check your device settings If you get an error when trying to activate iMessage or FaceTime.

You can use also Messages for Business from macOS device by running macOS monterey version 12.0 or later. For more information about compatibility, see capability-list under HTTP Headers under Common Specifications.

Older version of macOS, may not support certain message types and will display the following message when clicked:

Development Tools

The following development tools are needed to complete the exercises in this tutorial:

  • Python 3.7
  • Python modules:
    • Flask
    • pyjwt
    • pycryptodome (replaces pycrypto)
    • requests
    • cryptography

How to Set Up Your Endpoint

If your endpoint isn’t set up, you’ll need to set up a messaging server platform endpoint to send and receive messages from the Messages for Business service.

  1. Select a server that has sufficient storage available for the application, as Apple doesn't save messages after delivery.
  2. Set up your server to receive HTTPS messages.
  3. Configure a URL endpoint on your messaging server. Your server must be capable of receiving traffic on /message.
  4. Confirm that you can receive traffic to your URL on /message.
  5. You must have a logging tool installed and activated so that you can triage issues from your server side.

Set Up an HTTPS proxy

The Messages for Business server expects the MSP endpoint to listen for the registered platform’s API base-URL supporting HTTPS. You can simplify local development by setting up a proxy on the platform’s API base-URL server to point to a local HTTP port, such as 8002:

https://your.endpoint.base.url points to http://localhost:8002/

Research online methods to redirect HTTPS traffic to a local development server, or to set up Flask to handle SSL using correctly generated keys and certificates.

NOTE Exercises in this tutorial expect that you are redirecting messages to the Messages for Messages for Business Server at http://localhost:8002.