About Apple Authenticate Structured Messages
This structured message provides a way to send an OAuth2 authentication request to the customer. See Channel capabilities to know on which channel you can use this structured message.
There are two different workflows with Apple Authenticate messages depending on the iOS version of the customer's device. For iOS 16, iPadOS 16 or macOS 13 beta, we're sending the new Authentication message which only requests the authorization code when the customer logs in (see New Authentication Message Specification). For prior versions, we're sending the legacy Authentication message which also requests the access token, but might not be supported by Apple.
Prerequisites
- Set up OAuth URL, Token URL and Client Identifier in "End User Authentication” on your Messages for Business Account.
- In your Engage Digital channel settings, set up the Scopes and Client Secret fields in "OAuth Settings". Client Secret is only required to support the legacy Authentication message in order to request the access token.
Request Example
curl -X POST "https://[YOUR DOMAIN].api.digital.ringcentral.com/1.0/contents"
{
"source_id": "<source_id>",
"in_reply_to_id": "<in_reply_to_id>",
"body": "Please Log In",
"structured_content": {
"type": "authenticate",
"attachment_id": "<attachment_id>",
"response_body": "Response"
}
}
Primary Parameters
| API Property | Type | Description |
|---|---|---|
source_id |
String | ID of the source. |
in_reply_to_id |
String | ID of the message being replied to. |
body |
String | Content of the authentication message that the customer will receive. Optional if you provided the "Default title" field with a value in your channel settings. |
structured_content |
Object | Payload of the structured message. |
| Structured Content Settings | ||
structured_content.type |
String | Type of the structured message. Must be "authenticate". |
structured_content.response_body |
String | Optional. Field to be the body of the user’s response. If absent, the default is the structured message body. |
structured_content.attachment_id |
Object | Optional. Existing attachment id used to decorate the authenticate structured message with an image. Supports private attachments. Should be jpg, jpeg or png. Should be less than 5MB. |
Webhook
The customer will receive a message including the body and a button that will open the OAuth login page. Once authenticated, the token will be sent back by Apple and will be accessible through the Engage Digital webhook of the imported message in the "authenticate” part. The token is sent back. See following page for an example of the webhook payload format.
Webhook Payload Format for legacy Authentication message
The authenticate entry includes the decrypted access_token, the encrypted version is stored in structured_reply. Unlike the new Authentication message response, the decrypted token is only accessible through the content.imported webhook.
{
"id":"0b44eb19f120e3230942572f",
"domain_id":"48cc6703bdae1462ce06a555",
"events": [
{
"type":"content.imported",
"id":"5c3f6bbdd02c8e3a585fb9a3",
"issued_at":"2019-01-16T17:37:01.192Z",
"resource": {
"type":"apple_business_chat/authenticate_response",
"id":"5c3f6bbcd02c8e3a585fb9a1",
"metadata": {
"approval_required":false,
"author_id":"5c3721a4d02c8e735192254a",
"body":"This is an authentication test",
"body_input_format":"text",
"category_ids":[],
"creator_id":null,
"date":"2019-01-16",
"first_in_thread":"false",
"foreign_categories":[],
"foreign_id":"e70e270e-cdcb-4c3c-8e77-97e17b72a62f",
"has_attachment":false,
"intervention_id":"5c372253d02c8e6eabc2a365",
"in_reply_to_author_id":"5c371f92d02c8e6eabc2a23b",
"in_reply_to_id":"5c3f6ba5d02c8e3a585fb99c",
"language":"en",
"source_id":"5c371f92d02c8e6eabc2a237",
"status":"assigned",
"thread_id":"5c3721a4d02c8e7351922551",
"thread_title":"Thread Title",
"created_from":"synchronizer",
"private":true,
"context_data":{},
"structured_reply": {
"encrypted_access_token": "BL1Fe328olmVrsAnvESLnDtipwLR5p4IIEYqmBVXmdhe/Lhmb2+9STpd847Ox3QZ1tZx68wS9WKBsVfXl8Xt6ZkRW53dJB3gc2LbWGZirML6iVna6wNdlih3TliB+gFZmv+RaPtHVG8r2QYMAaDwL5DK8NTe/6hc5gxfEuhE9ONOBr5Ft20evhXH8zWyZn5/WDERo1c/WWfP6pVvRFQpt0wdHhs4aUDVgRey3E3wsZIR",
"version": 1,
"status": "success"
},
"authenticate": {
"access_token":"ba371cc8c511e0d9114b8e17777ebc4ad5e23811144341f0ca4726d67ff4b19e",
"status":"success",
"version": 1
}
}
}
}
]
}
Webhook Payload Format for new Authentication message
The authenticate field is juste the replication of structured_reply, result may vary depending on the OAuth provider. It generally contains the code needed to request an access_token to the OAuth provider.
{
"id":"0b44eb19f120e3230942572f",
"domain_id":"48cc6703bdae1462ce06a555",
"events": [
{
"type":"content.imported",
"id":"5c3f6bbdd02c8e3a585fb9a3",
"issued_at":"2019-01-16T17:37:01.192Z",
"resource": {
"type":"apple_business_chat/authenticate_response",
"id":"5c3f6bbcd02c8e3a585fb9a1",
"metadata": {
"approval_required":false,
"author_id":"5c3721a4d02c8e735192254a",
"body":"This is an authentication test",
"body_input_format":"text",
"category_ids":[],
"creator_id":null,
"date":"2019-01-16",
"first_in_thread":"false",
"foreign_categories":[],
"foreign_id":"e70e270e-cdcb-4c3c-8e77-97e17b72a62f",
"has_attachment":false,
"intervention_id":"5c372253d02c8e6eabc2a365",
"in_reply_to_author_id":"5c371f92d02c8e6eabc2a23b",
"in_reply_to_id":"5c3f6ba5d02c8e3a585fb99c",
"language":"en",
"source_id":"5c371f92d02c8e6eabc2a237",
"status":"assigned",
"thread_id":"5c3721a4d02c8e7351922551",
"thread_title":"Thread Title",
"created_from":"synchronizer",
"private":true,
"context_data":{},
"structured_reply": {
"code":"e993c351c5c031262b1c",
"status":"success",
"version": 2
},
"authenticate": {
"code":"e993c351c5c031262b1c",
"status":"success",
"version": 2
}
}
}
}
]
}
Example: Apple Messages for Business (Apple Authenticate)
Nothing specifically unique as this is an Apple Messages for Business specific structured message type.
