Clients can initiate messages using the provided URL. When a customer clicks on the URL, the system redirects them to a message so they can send a text message. Decide how and where to provide the URL. Brands can embed it as a link in an email message or website, or use it as a button action in the app the customer is using.

The URL to use is https://bcrw.apple.com/urn:biz: <your-business-id>, replacing <your-business-id> with the business ID you received from Apple after registering with Messages for Business.

There are optional query string parameters you can include in the URL:

• biz-intent-id

• biz-group-id

• body

The biz-intent-id parameter lets you specify the intention, or purpose of the message. The biz-group-id parameter lets you indicate the group, department, or individuals best qualified to handle the customer’s particular question or problem. The body parameter pre-populates the message so the customer only has to hit send to initiate the conversation.

NOTE: Parameters and data attributes that form the URL, such as the intent, group, and body, must not contain a subset of URI reserved characters, such as &, #, [], (), {} and /

About Intent, Group, and Body Values

Businesses define the values for the intent, group, and body parameters, and these parameters are included in a URL that initiates a chat session in Messages when a customer clicks or taps the Messages button.

When a customer starts a chat session through your app or website, you can choose to include the following three parameters as part of the URL for defining messages:

• Intent, or purpose, of the chat.

• Group designates the department or individuals best qualified to handle the customer’s particular question or problem.

• Body is a parameter that prepopulates a message for your customers so all they need to do is tap Send in Messages.

Use the intent, group, and body values to define the customer's intent so you can quickly direct them appropriately within your support organization. The power to define these values lies underneath the author.

For example, if your company is a financial institution and a customer contacts you with a question about their credit card account. When a customer clicks or clicks the message button, the message provides an auto-generated response "What can I help you with today?" When the customer clicks the message button, the message opens and displays a welcome message with a list of options to choose from. For example, these options may include, but are not limited to, “Credit Card Account,” “Checking Account,” and “Saving Account.” The customer taps one of the options (the intent)—in this case, "Credit Card Account"—which routes the message to the Credit Card Department (the group).

​

The body parameter, added manually to a URL, allows the provisioning of more granular information such as "Order an additional credit card." Messages for Business uses the body value to prepopulate a message for your customers so all they need to do is tap Send in Messages. In this example, the customer taps a chat button which opens a prepopulated text message, "Order an additional credit card." The customer only needs to tap Send to notify the business of their intent and initiate the conversation.

​

Note: The spotlight entry point does not accept Intent and Group values.

Starting a Message from Your App

You can create a class button and add it to your application's user interface to allow clients to initiate messages within your application. Create a message button that, when a customer clicks the button, invokes a message URL for the business that is used by the target action engine to start a conversation with the business.

Create a Posts button class using SVG/PNG button images. Use an appropriate CTA message to let your customers know that their questions will be answered when they click on that entry point.

Customize Intent and Group ID for Your Business Locations:

​

The intent and group ID values can be whatever the brand decides. When you don't define the intent or group ID, by default, the group ID is empty and the intent ID is set as:

business_name: physical_address_of_the_location

If you would like to customize the group and intent ID for your locations, this can also be accomplished in Apple Business Register. For each location you wish to add a custom group or intent ID, it must be added to Apple Business Register. If your brand's business presence has more than 50 locations, speak with your Apple representative so that they can advise how to proceed in adding them.

​

After adding the locations for your business, you can customize the intent and group IDs.

Once the value is defined, Apple Maps can track customer-requested locations. You can also send messages directly to the appropriate agent group for your service location. For example, when a customer in a store requests a specific item, an agent can direct the customer to the correct aisle.

​

When sending messages from map locations, Messages for Business uses standard URL encoding similar to web buttons. When the MSP platform receives an encoded parameter, a plus sign replaces the encoded space.

After the intent ID is defined, the log will contain something similar to the following:

​

{

"intent": "My+Business:+One+Apple+Park+Way,+Cupertino,+CA++95014,+United+States",

"sourceId": "urn:mbid:AQAAY1RfNajxPMgY5JzQHCnF6bY00d+HrG2YmTlgZ2VJ/spRqzPQUER1mT4wBWg=",

"v": 1,

"group": "poi_to_abc",

"body": "hi",

"locale": "en_PL",

"id": "0c68c45c-fb66-47de-b255-df1644c",

"type": "text",

"destinationId": "70a55-11de-11e8-a180-b7c088"

}