About Apple Authenticate Structured Messages

Last updated: 2024-04-17Contributors
Edit this page

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