Let businesses send and receive text messages with their customers by integrating your Customer Service Platform with Business Chat.
To exchange text messages between customers and businesses, a Customer Service Platform (CSP) provider integrates their platform with Business Chat. To integrate, the CSP:
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:
Credentials used to authenticate the request. See Authorize a Message.
A UUID string that identifies the message.
A string that identifies the message sender. When a customer sends a message, the
source-idis the customer’s opaque ID. When a business sends a reply to the customer, the
source-idis the business ID.
A string that identifies the message recipient. When a customer sends a message, the
destination-idis the business ID. When a business sends a reply to the customer, the value is the customer’s opaque ID.
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.
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.
A Boolean that determines whether the reply is sent by a person or an automated bot. Set the value to
truewhen an automated agent (a bot) sends the reply.
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:
A string identifying the algorithm used to encode the payload.
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
audvalue is always the CSP ID when exchanging messages with Business Chat.
A string identifying the principal that issued the JWT. The value is always the CSP ID when exchanging messages with Business Chat.
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.
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
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
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
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-idheader field does not match the
401 - Unauthorized
The request lacks the
Requests from Business Chat always contain the
Authorizationheader field. If the CSP returns a
401response code, the problem is either a configuration issue with Business Chat or a signal of spoofed incoming activity.
When the CSP returns the
401response code, it should include
WWW-Authenticate: Bearer typ=JWTin its response header.
403 - Forbidden
The request failed to validate the
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
The CSP should always include the
WWW-Authenticate: Bearer typ=JWTheader with no response body when sending a respond back to Business Chat. If the CSP sends or receives a large number of
403response codes, the CSP should verify that the
Authorizationheader field matches the authorization token found on the Business Chat web portal.
404 - Not Found
The request failed to recognize the
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
50xstatus 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.