Most Common Errors

What can I do to avoid the most common errors in implementing Messages for Business?
Encoding errors are the largest class of technical errors based on our analysis of support tickets associated with the Messages for Business API.

Developers who work entirely or primarily with web technologies may be unfamiliar with binary classes and objects. When you decode a Base64-encoded string it creates a binary object that is not a string. String methods attempted on this object fail.

Another common error is double-encoding URLs. You should only apply safe-encoding to a URL a single time. You should use a well-validated library to URL encode and decode, to ensure that it correctly implements all aspects of the specification.

Many languages safe-encode output to log files and standard output stream. These strings may error out when used as input in the exact same format as the output. For example, Java safe-encodes many characters in strings with a / character. Python safe-encodes strings with a u at the beginning to indicate unicode string.

Unfortunately, all valid hexadecimal strings are also valid Base64 strings. When you decode a hex string as Base64, the method succeeds, but creates an erroneous result. This makes it difficult to triage the issue.

User Accounts and Synchronization

I sent my first message and it shows Not Delivered on the device. How do I fix it?
There are different reasons you may see the Not Delivered error when beginning a Business Chat conversation for the first time.

If you receive Not Delivered for all test devices, try the following steps:

  • Use a cURL command, or similar language, to ensure that your server is listening on the correct endpoint. Remember, /message appends to the end and is a POST, not a GET.
  • Verify your server received the Messages for Business message and, if so, troubleshoot based on the HTTP response code.
  • Double check that all of the email addresses used in the allow list are valid Apple IDs at https://appleid.apple.com.

For each device showing Not Delivered perform the following steps:

  1. Go to Settings > Messages > Send & Receive.
  2. Ensure that the email address associated with the allow list is checked, on both “… receive messages…” and “…start new conversations…” sections.
  3. Return to Settings.
  4. Wait 12 hours from the last attempt to message this particular brand from this device as the message may have been sent since you logged the support ticket.
  5. Ensure that the Messaging Service Provider (MSP) endpoint, listener, and agent console are prepared to receive and process the message.
  6. Attempt to start the conversation again.

How are messages synced across multiple devices for a single user?
Messages sync across all devices that are on a set of related Apple IDs. You can create Apple IDs from an email address or a phone number. You can check these associations by logging into the Apple ID site.

Some users set up two or more devices from different Apple IDs. This creates two zones that act as separate users. Additional devices sync with one of the zones depending on the Apple ID, but the two zones don't sync. Also, Messages for Business conversations have different Opaque IDs across the two zones.

What can we do to prevent issues for users with multiple devices or accounts?
Our recommended practice is to structure user tables in such a way that a single known user may have more than one Opaque ID. Most users only enter the system once with one Opaque ID. They may return under an unknown ID not fully realizing that is the case. This is more common with tech-savvy users who have many devices and many accounts for services they use, than for the general user population.

What is an Opaque ID?
It is a unique identifier to each pairing between a Business ID and a user. The Opaque ID also refers to the destinationId in the code samples for sending messages from your Messaging Service Provider (MSP) to a user. Each user is defined by a set of related Apple IDs as described above.

For privacy, the business doesn’t receive the user’s phone number, email address or iCloud account information. The Opaque ID is unique to the relationship between the customer's Apple ID and the business’s business ID. A customer has a different Opaque ID for every chat they have using Messages for Business. The customer decides if and when to share personal identifying information with the business. For more information, see Apple Platform Security.

In your MSP agent console, Apple recommends that your system stores the Opaque ID. Once a user has authenticated through either an agent/bot process or our OAuth2 feature, you should change the identifier to the user’s name.

Are users limited to sending only photos and videos in Messages for Business? Is it possible to send other types of files such as PDF, Microsoft Word, Microsoft Excel?
You can send any type of file through Messages for Business. For example, you can easily send and receive an Excel file (.xlsx) to an iPhone that does not have Excel installed. Any binary file should be intact after transport in either direction, regardless of the iPhone or iPad settings.

Getting Users into a Conversation with Entry Points

How do I use the intent ID and group ID parameters?

The intent (biz-intent-id) and group (biz-group-id) fields are used to track the source of user engagement and to route messages to the appropriate groups.

Intent and group field values can be specified as URL parameters embedded in apps, QR codes, or Messages for Business buttons on websites. For example:

https://bcrw.apple.com/urn:biz:Some-Biz-Chat-ID?biz-intent-id=SomeIntent&biz-group-id=SomeGroup

In the first text message from the customer after starting the conversation through the URL, the MSP can retrieve the intent and group from the message payload. For example:

{
"body": "Hello",
"sourceId": "<opaque user ID>",
…
"intent": "SomeIntent",
"group": "SomeGroup"
}

The intent field value is specified with biz-intent-id key in the URL, but appears under intent key in the message payload. Similarly, the group field is specified with biz-group-id in the URL and group from the message.

Apple Maps puts the physical address in the biz-intent-id field for users who launch Messages for Business from Maps. Spaces are replaced by plus-sign characters and other safe encoding changes may be made for the sake of generating a valid URL.

For more information about routing using intent and group IDs, see About Intent, Group, and Body Values and Apple Maps and Your Business Locations.

How do I set up entry points in Apple Maps and my brand website?

You can set up entry points for the following:

Our users experienced latency or our engineers measured latency in the message delivery. Can you fix this latency on your side?

The device connectivity, also known as the "last mile” connection from the device into the network, generates the most latency. Apple continually optimizes message delivery on the Messages for Business server side, but we cannot affect connectivity between the device and Wi-Fi or cellular networks.

Compliance and Regulatory Questions

Does the MSP have to delete the conversation history with user in accordance with General Data Protection Regulation 2016/679 (GDPR)?

According to our security and compliance team:

The MSP is the data controller. The arrangement between the brand and the MSP guides how it is handled, with consideration of the regulatory domain they are operating in. All we offer is a block for further messages from the brand to the user. It is beyond our scope to manage the relationship any further than that.