Article

Authorizing Messages

Authorize messages between your CSP and the Business Chat service.

Overview

When exchanging messages between Business Chat and the Customer Service Platform (CSP), 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. Business Chat requires this field, and the receiving server should reject the request when the field is not present.

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

alg

A string used in the header, identifying the algorithm used to encode the payload. The alg value is always HS256 when exchanging messages with Business Chat.

aud

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 CSP ID when exchanging messages with Business Chat. This value is used when sending messages from the business to the CSP.

iss

A claim that is a string identifying the principal that issued the JWT. The value is always the CSP ID when exchanging messages with Business Chat. This value is used with traffic coming from the CSP to the business.

iat

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 Business Chat by creating a signed JWT. After registering for Business Chat as a CSP, you receive the following:

  • A CSP ID that identifies the platform. This is not the same as the business ID you receive after registering for Business Chat.

  • 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 Business Chat, verify that Business Chat 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 Business Chat service to the CSP:

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

The decoded JWT authorization header from the CSP to the Business Chat service has the following header and claims for each message:

header
{
  "alg": HS256,
}
claims
{
  "iss": <CSP-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 Business Chat 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 CSP environment—the registering agent should revoke the old key using the Business Chat 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 Business Chat service to a CSP:

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>"
}

See Also

First Steps

Integrating with Business Chat

Implement the /message endpoint to send and receive messages.

object TypingIndicatorMessage

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