Web Service Endpoint

Integrating with Business Chat

Implement the /message endpoint to send and receive messages.

URL

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

HTTP Headers

The Business Chat service and the CSP communicate with each other by sending HTTP requests. Each request must use HTTPS/TLS 1.2, and it may include the following header keys:

Authorization
string
(Required)

Credentials used to authenticate the request. See Authorizing Messages.

auto-reply
string

A Boolean that determines whether the reply is sent by a person or an automated agent (bot). Set the value to true when a bot sends the reply.

capabilities
string

A string list that identifies Business Chat features supported by the customer’s device. The list items are case insensitive and separated by commas. When a customer sends a message, the Customer Service Platform (CSP) can obtain the customer device capabilities to compose an appropriate response for that device. Possible value is auth for authenticate message support.

destination-id
string
(Required)

A string that identifies the message recipient. When a customer sends a message, the destination-id is the business ID. When a business sends a reply to the customer, the value is the customer’s opaque ID.

device-agent
string

A string that identifies the operating system type of the customer’s device. Possible values include "iPhone OS", "Mac OS X", "Watch OS", and "Apple TVOS". Business Chat includes this header key in each request it sends to the CSP.

id
uuid
(Required)

A UUID string that identifies the message.

msp-agent
string

A string that identifies the agent or system sending the request. The CSP should set the field to a string value that is meaningful to the business. Business Chat logs up to the first 64 characters of the string.

source-id
string
(Required)

A string that identifies the message sender. When a customer sends a message, the source-id is the customer’s opaque ID. When a business sends a reply to the customer, the source-id is the business ID.

HTTP Body

For TextMessage, see Sending Text Messages.

For RichLinkMessage, see Sending Rich Link Messages.

For ListPickerMessage, see Sending a List Picker.

For TimePickerMessage, see Sending a Time Picker.

For CustomedInteractiveMessage, see Sending Custom iMessage Extensions.

For ApplyPayMessage, see Sending an Apple Pay Payment Request.

Response Codes

OK

The request was successful.

400 Bad Request
Bad Request

The request lacks the required header fields, the request body isn't JSON or the JSON lacks the required fields, or the destination-id header field does not match the destinationId JSON field.

401 Unauthorized
Unauthorized

The request lacks the Authorization header field.

Requests from Business Chat always contain the Authorization header field. If the CSP returns a 401 response code, the problem is either a configuration issue with Business Chat or a signal of spoofed incoming activity.

403 Forbidden
Forbidden

The request failed to validate the Authorization header field.

If the CSP sends a request to Business Chat and it responds with 403 - Forbidden, it’s likely in response to an invalid CSP ID in the Authorization header field.

404 Not Found
Not Found

The request failed to recognize the destination-id or was sent to a customer no longer available.

When sending this response code, include brief text explaining the error in the response body.

500 Internal Server Error
Internal Server Error

A server error occurred.

An additional response could be 50x - various. This means that the request encountered various server-side failures. Find and return the appropriate code based on the specific condition. A request that returns 50x status codes in the response causes the server to retry the request up to three times within 30 seconds. If the request fails three times, or times out after 30 seconds, you need to notify the customer that message delivery failed and provide an opportunity to resend the message.

Discussion

To exchange text messages between customers and businesses, a CSP provider integrates their platform with Business Chat. To integrate, the CSP provider:

  1. Implements the /message endpoint that Business Chat uses to forward messages sent by customers (see Messages Received).

  2. Authorizes the exchange of messages by creating a JSON web token (JWT) and using it in the authorization header field (see Authorizing Messages).

  3. Uses the Business Chat REST API to send replies from the business to their customers (see Messages Sent).

Topics

Common Dictionaries

object BaseMessage

Dictionary keys used in all message types.

object Attachment

Dictionary keys for sending and receiving messages with attachments.

See Also

First Steps

Authorizing Messages

Authorize messages between your CSP and the Business Chat service.

object TypingIndicatorMessage

Forward indicators from Business Chat when someone is entering text in Messages.