Overview

The Apple Business Chat messaging channel now allows you to send an authentication request to consumers (only from iOS 12 onwards) using an OAuth 2.0 provider. The consumers then respond to the authentication request with their user/password credentials which can be validated against the OAuth 2.0 provider.

See the message flow below:

apple business chat authentication flow

  1. Agent or bot is notified via an engagement attribute if consumer device supports the Apple Auth feature.

  2. Send the Apple Auth template via an agent or bot with the Structured Content framework and configuration (similar to Apple list and time picker templates).

  3. Authentication is done by your OAuth 2.0 provider.

  4. Upon successful or failed authentication, LiveEngage passes the authentication details back to the LiveEngage Conversational Metadata (via the Messaging Agent SDK) in order to allow you to perform validation.

Setup

  1. Supply your private OAuth2 service details in your Apple management area (register.apple.com).

The required details include:

  • Authentication endpoint URL

  • Token URL

  • Client Identifier

Instructions on how to create a free OAuth2 service using auth0

If you do not yet have an OAuth2 service or if you need a test service, follow the instructions below:

  1. Create a auth0 account

  2. Create a new Application Machine to Machine

  3. Put https://auth.businesschat.apple.com in Allowed Callback Urls

  4. Put https://auth.businesschat.apple.com in Allowed Origins & Allowed Web Origins

  5. On the same screen, go to the bottom and select advanced settings -> Endpoints

  6. Copy Auth URL, Token Url, Client Secret (it is at the top) and place them in your register.apple.com portal

Checking for Apple Auth device compatibility

Before the agent or bot sends an authentication request to a consumer, they will need to know if the consumer device is compatible (that is, using iOS 12 or newer) with Apple Auth.

In an Apple Business Chat Conversation, the messaging channel will automatically send an authenticated "role" engagement attribute to LiveEngage:

  • If consumer Apple device supports authentication, this attribute's value will be: "Apple Authentication supported".

  • If consumer Apple device does not support authentication, this attribute's value will be: "Apple Authentication not supported".

The agent or bot should read the consumer engagement attributes to check for this engagement attribute before sending the Apple Authentication request to the consumer.

Note: If the consumer updates the iOS version from 11 to 12 when still in an active conversation in LiveEngage, the conversation will not be updated with the consumer’s new capability - to solve this, the conversation should be closed and opened again in LiveEngage.

role engagement attributes

Sending an Apple Authentication Request to a Consumer

Similar to Apple structured content templates, you will send two template payloads (Metadata and Body) for the Apple Auth request to the consumer.

See how to send Structured Content for a background on how to send these.

Different from Apple structured content templates, the body template will only define how the Apple Auth bubble is displayed in the LiveEngage agent workspace. The metadata template will define how the bubble is displayed in the consumer's Messages thread.

Agent sends auth request to consumer via Agent Workspace SDK widget

Consumer sees auth request bubble. Style here defined by metadata receivedMessage.

Consumer fills out form from OAuth2 provider

Consumer sees request confirmation bubble. Style here defined by metadata replyMessage.

Request Metadata

BusinessChatMessage - receivedMessage and replyMessage bubbles

The BusinessChatMessage object contains the receivedMessage and replyMessage objects, which define how the Authentication Interactive Message bubbles layout will be displayed when the message is received on the consumer’s device (receivedMessage) and once an authentication is submitted by the consumer (replyMessage).

ConnectorAuthenticationRequest

The ConnectorAuthenticationRequest object holds the requestIdentifier object, which allows the brand to identify the authentication request and map the OAuth token in the response to the request originator.

Please use the metadata template with the relevant fields, as presented in the example below:

Metadata Template Example:
[  
  {  
    "type":"BusinessChatMessage",
    "receivedMessage":{  
      "title":"Sign In to LivePerson",
      "subtitle":"Thank you",
 "imageURL":"https://www.liveperson.com/sites/default/files/pictures/nav/Logo-LP-White.png",
      "style":"small"
    },
    "replyMessage":{  
      "title":"You Signed in",
      "subtitle":"Thank you",
"imageURL":"https://www.liveperson.com/sites/default/files/pictures/nav/Logo-LP-White.png",
      "style":"small"
    }
  },
  {  
    "type":"ConnectorAuthenticationRequest",
    "requestIdentifier":"insert the request UUID here"
  }
]
Metadata Object Properties
Property Name Description Type Required
BusinessChatMessage Represents the Business Chat bubbles view objects Object Y
ConnectorAuthenticationRequest Represents a Business Chat authentication request Object N
ConnectorAuthenticationRequest Object Properties
Property Name Description Type Required
requestIdentifier identify the authentication request and map the to the request originator. string N
receivedMessage Object Properties
Property Name Description Type Required
Style The Style of the authentication interactive message reply bubble. Can be set to icon, small or large. Defaults to icon Enum - icon, small, large N
title The title of the bubble String Y
subtitle Subtitle to be displayed under title String N
imageURL Image to be placed in the authentication interactive message received bubble layout String N
replyMessage Object Properties
Property Name Description Type Required
style The Style of the authentication interactive message reply bubble. Can be set to icon, small or large. Defaults to icon Enum - icon, small, large N
title The title of the bubble String Y
subtitle Subtitle to be displayed under title String N
imageURL Image to be placed in the authentication interactive message reply message bubble layout String N

Request Body

The request body defines how the Apple Auth bubble looks in the LiveEngage Agent Workspace and not how the bubble looks on the consumer device. This Apple Auth structured content template in the Agent Workspace is for conversational context, transcript and historic records, as well as ease of use for agents.

See the introduction to templates for information on a basic template that you can send.

Body Template Example

A very simple, basic structured content template for Apple Auth would be just an image and text in a horizontal arrangement.

{
  "type": "horizontal",
  "elements": [
    {
      "type": "image",
      "url": "apple_auth_image_url"
    },
    {
      "type": "text",
      "text": "authentication details"
    }
  ]
}

Receiving an Apple Authentication Response from a Consumer

After the consumer submits their Apple Auth details in the form, the Apple Auth response is delivered to LiveEngage using Conversational Metadata.

Conversational Metadata provides a way for developers to pass metadata or context information to a bot built with the Messaging Agent SDK.

Please see the Conversational Metadata guide for how to listen for Conversational Metadata with the correct Apple Auth response structure.

Only a bot can listen for Conversational Metadata at this time.

Response Metadata

The authentication response metadata is contextual information about the consumer authentication response status. This information should be used to allow the bot to validate the authentication status of the consumer, as well as to enable the bot to report the auth response token back to the OAuth service in order to validate user identity.

Example Conversational Metadata response:

Success example response:

{  
  "type":"ConnectorAuthenticationResponse",
  "status":true,
  "token":"Token String"
}

Failure example response:

{  
  "type":"ConnectorAuthenticationResponse",
  "status":false,
  "errors":[  
    {  
      "message":"applicable apple error codes"
    }
  ]
}

ConnectorAuthenticationResponse Object Properties

Property Name Description Type
Status Status of the consumer authentication - can be only true (successful) or false (failed) Boolean
token Token string - will be available only when authentication was successful String
errors Type of authentication error as received from Apple - will be available only when authentication failed Array

Guidelines

General Guidelines

  • Image URLs must be whitelisted in LiveEngage. Images added in the ReceivedMessage and ReplyMessage must be whitelisted in the structured content image whitelisting area. Please contact your LP representative to whitelist images.

Consumer received and reply bubble behavior

If using received bubble with style "icon", “small”, “large”:

  • Received bubble experience: if an image was added, the image in the received bubble will not be presented in the push preview message. Once you tap to view a bubble in the conversation thread, the image will be presented. The size of the received bubble will be defaulted to "icon".

  • Reply bubble experience: image will always be defaulted to the "received" bubble image (if configured). If no image was added to the received bubble, no image will be presented in the reply bubble. The size of the reply bubble will be defaulted to “icon”.

  • If authentication fails, the Reply bubble text and subtitle configured will be overridden by apple to the following text "Authentication failed".

Limitations

  • In the current version of Apple Auth support, only a bot in LiveEngage (using the Messaging Agent SDK) will be able to receive the authentication response (using the Conversation Metadata). A human Agent is currently not exposed to these events. There will be an option to receive authentication response data without the Messaging Agent SDK in Q1 2019 (and thus as a human agent).

  • Updating the Apple Business Chat authentication status visually in the LiveEngage UI is planned for 2019.

  • Touch/Face ID is not currently supported in Apple's authentication solution