Article

Integrating with Business Chat

Let businesses send and receive text messages with their customers by integrating your Customer Service Platform with Business Chat.

Overview

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

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

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

HTTP Request Requirements

Business Chat 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

Credentials used to authenticate the request. See Authorize a Message.

id

A UUID string that identifies the message.

source-id

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.

destination-id

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.

msp-agent

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 them. Business Chat logs up to the first 64 characters of the string.

device-agent

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.

auto-reply

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

capabilities

A string list that identifies Business Chat features supported by the customer’s device. The list is 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 message for that device. Possible value is auth for authenticate message support.

Authorize a Message

When exchanging messages between Business Chat and the CSP, the server sending the message must authorize the HTTP request by setting the Authorization header field. Business Chat requires this field, and the receiving server should reject the request when the field is not present. Format the field value with the string “Bearer” followed by a space, followed by a signed JSON Web Token (JWT). Business Chat uses a subset of JWT fields, shown here:

alg

A string identifying the algorithm used to encode the payload.

aud

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.

iss

A string identifying the principal that issued the JWT. The value is always the CSP ID when exchanging messages with Business Chat.

iat

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.

CSP ID and Secret Key

After registering for Business Chat as a CSP, the registering agent receives:

  • A CSP ID, which identifies the platform. This ID is not the same as the business ID, which a business receives after registering for Business Chat.

  • A secret key, which is a Base64-encoded string. Decode the string before using the key to sign the JSON web token. When receiving an HTTP request from Business Chat, verify that Business Chat signed the request with the secret key. The token has the following header and claims:

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

HTTP requests sent by the CSP to Business Chat should have a valid Authorization header field. If the field is missing or invalid, Business Chat rejects the request. The token has the following header and claims:

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.

Secret Key Management

The registering agent should record and securely store the 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 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.

HTTP Response Codes

Business Chat returns one of the following response codes to HTTP requests. The CSP should follow the same behavior.

200 - OK

The request was successful.

400 - 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

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.

When the CSP returns the 401 response code, it should include WWW-Authenticate: Bearer typ=JWT in its response header.

403 - 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.

The CSP should always include the WWW-Authenticate: Bearer typ=JWT header with no response body when sending a respond back to Business Chat. If the CSP sends or receives a large number of 403 response codes, the CSP should verify that the Authorization header field matches the authorization token found on the Business Chat web portal.

404 - Not Found

The request failed to recognize the destination-id value.

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

500 - Internal Server Error

A server error occurred.

50x - various

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, notify the user that message delivery failed and provide them with an opportunity to resend their message.

See Also

Customer Service Platform Integration

Receiving Messages

Receive, route, and prioritize incoming messages sent by customers.

Sending Messages

Send responses from businesses to their customers.

Handling Message Attachments

Receive and send file attachments.

Enhancing the Customer's User Experience

Provide a rich user experience with interactive messages.

Supporting Apple Pay

Provide an easy and secure way for customers to buy goods and services through Business Chat using Apple Pay.