About Apple Form Structured Messages

Last updated: 2022-09-29 Contributors
Edit this page

This structured message provides a form made of a list of questions the customer can answer to. See Channel capabilities to know on which channel you can use this structured message.

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>",
  "structured_content": {
    "type": "form",
    "title": "Report a product issue",
    "subtitle": "Please fill this form to report any issue you had with our product",
    "attachment_id": "<attachment_id>",
    "attachment_fallback_id": "<attachment_id>",
    "first_page_id": "page_1",
    "private": false,
    "show_summary": true,
    "splash": {
      "header": "Lorem ipsum",
      "text": "Lorem ipson dolor sit amet",
      "button_title": "Splash button",
      "attachment_id": "<attachment_id>",
    },
    "pages": [
      {
        "page_id": "page_1",
        "type": "datePicker",
        "header": "Retrieval Date",
        "title": "What date did you receive, or expect to receive the product?",
        "next_page_id": "page_2"
      },
      {
        "page_id": "page_2",
        "type": "select",
        "multiple_selection": true,
        "header": "Report an issue",
        "title": "What was the issue with your product?",
        "next_page_id": "page_3",
        "items": [
          {
            "id": "item_id_1",
            "value": "doesnt_work",
            "title": "The product does not work"
          },
          {
            "id": "item_id_2",
            "value": "damaged",
            "title": "The product is damaged"
          },
          {
            "id": "item_id_3",
            "value": "not_received",
            "title": "I haven't received the product"
          }
        ]
      },
      {
        "page_id": "page_3",
        "type": "picker",
        "header": "Compensation",
        "title": "What would you like to obtain as compensation?",
        "next_page_id": "page_4",
        "items": [
          {
            "id": "item_id_1",
            "value": "refund",
            "title": "A refund"
          },
          {
            "id": "item_id_2",
            "value": "new_product",
            "title": "A new product"
          },
          {
            "id": "item_id_3",
            "value": "replacement",
            "title": "A replacement"
          }
        ]
      },
      {
        "page_id": "page_4",
        "type": "input",
        "header": "More informations",
        "title": "If you have anything you'd like to tell us please do",
        "submit_form": true
      }
    ]
  }
}

Primary Parameters

API Property Type Description
source_id String Optional. ID of the source. Most interactions are in reply to a message being sent to the agent. In these cases, the source ID is not required.
in_reply_to_id String ID of the message being replied to.
structured_content Object Payload of the structured message.
Structured Content Settings
structured_content.type String Type of the structured message. Must be "form".
structured_content.title String The title of the structured message.
structured_content.subtitle String The subtitle of the structured message.
structured_content.first_page_id String page_id of the first page you want to display.
structured_content.private Boolean Indicates wether to mark the response as private in the structured_reply field of the form response.
structured_content.show_summary Boolean Displays a summary of the responses before submitting the form. Is false by default.
structured_content.attachment_id String Optional. Existing attachment id used to decorate the form message with an image.
Supports private attachments.
Should be jpg, jpeg or png.
Should be less than 5MB.
structured_content.attachment_fallback_id String Optional. Fallback in case the attachment related to the attachment_id doesn’t meet the source requirements. Must be public. Only be jpg, jpeg or png. Maximum size of 5MB. Upload attachments for you own custom images.
structured_content.splash Object Optional. Displays an introductive screen before the form questions.
structured_content.pages Array Optional. An array of objects representing each form question.
Splash Settings
structured_content.splash.header String Optional. Header of the splash screen.
structured_content.splash.text String Optional. Text in the splash screen.
structured_content.splash.button_title String Optional. Label of the button that allows to open the form.
structured_content.splash.attachment_id String Optional. Existing attachment id used to decorate the splash with an image.
Supports private attachments.
Should be jpg, jpeg or png.
Should be less than 5MB.
structured_content.splash.attachment_fallback_id String Optional. Fallback in case the attachment related to the attachment_id doesn’t meet the source requirements. Must be public. Only be jpg, jpeg or png. Maximum size of 5MB. Upload attachments for you own custom images.
Page Settings
structured_content.pages.page_id String Page identifier.
structured_content.pages.type String Page type, can be select, picker, datePicker, or input.
structured_content.pages.header String Optional. Header label for the page.
structured_content.pages.title String Title for the page.
structured_content.pages.attachment_id String Optional. Existing attachment id used to decorate the page with an image.
Supports private attachments.
Should be jpg, jpeg or png.
Should be less than 5MB.
structured_content.pages.attachment_fallback_id String Optional. Fallback in case the attachment related to the attachment_id doesn’t meet the source requirements. Must be public. Only be jpg, jpeg or png. Maximum size of 5MB. Upload attachments for you own custom images.
structured_content.pages.next_page_id String page_id of the page you want to be displayed after this one. In select pages without multiple_selection to true, it should be at item level.
structured_content.pages.submit_form Boolean Should be true on the page that ends the form.
structured_content.pages.multiple_selection Boolean Optional. On select pages, should be true to allow selecting multiple items.
structured_content.pages.picker_title String Optional. On picker pages, adds a label on the picker element.
structured_content.pages.selected_item_index Integer Optional. On picker pages, is the default selected item.
structured_content.pages.hint_text String Optional. On datePicker and input pages, adds a text below the field.
structured_content.pages.items Array Optional. An array of objects representing each selectable items, is mandatory on select and picker pages.
structured_content.pages.options Object Optional. An object containing diverse options for the different page types.
Item Settings
structured_content.pages.items.title String Text that will actually be displayed for the item.
structured_content.pages.items.value String Item hidden value.
structured_content.pages.items.id String Item identifier.
structured_content.pages.items.next_page_id String Optional. Mandatory in select pages with multiple_selection missing or false.
structured_content.pages.attachment_id String Optional. Existing attachment id used to decorate the item with an image.
Supports private attachments.
Should be jpg, jpeg or png.
Should be less than 5MB.
structured_content.pages.attachment_fallback_id String Optional. Fallback in case the attachment related to the attachment_id doesn’t meet the source requirements. Must be public. Only be jpg, jpeg or png. Maximum size of 5MB. Upload attachments for you own custom images.
Options Settings
structured_content.pages.options.date_format String Optional. Available for datePicker only. Uses Unicode Date Format Patterns Standard
structured_content.pages.options.start_date String Optional. Available for datePicker only. Default value for the date picker. Must be ISO 8601 (YYYY-MM-DD)
structured_content.pages.options.maximum_date String Optional. Available for datePicker only. Maximum value for the date picker. Must be ISO 8601 (YYYY-MM-DD)
structured_content.pages.options.minimum_date String Optional. Available for datePicker only. Minimum value for the date picker. Must be ISO 8601 (YYYY-MM-DD)
structured_content.pages.options.label_text String Optional. Available for datePicker only. A string representing the text string to be shown next to date field. Defaults to text Date.
structured_content.pages.options.regex String Optional. Available for input only. A string representing a JSON encoded regular expression (regex) string to limit the type of input for input field to use.
structured_content.pages.options.placeholder String Optional. Available for input only. A text string used when there is no other text in the input text field. Default value are Required or Optional.
structured_content.pages.options.required Boolean Optional. Available for input only. A Boolean value that defaults to false. When set to true, the next button on page is disabled until the user provides input.
structured_content.pages.options.input_type String Optional. Available for input only. A string value that defaults to singleline. Other values are multiline or singleline.
structured_content.pages.options.prefix_text String Optional. Available for input only. A string value representing optional text shown next to the text field. This value defaults to an empty string. Only applies to inputType : singleline.
structured_content.pages.options.max_character_count Integer Optional. Available for input only. An integer value representing the field size in characters for singleline and multiline. The field size defaults to 30 characters for singleline and 300 characters for multiline.
structured_content.pages.options.keyboard_type String Optional. Available for input only. Type of keyboard to be shown. Available values are: default, asciiCapable, numbersAndPunctuation, numberPad, phonePad, namePhonePad, emailAddress, decimalPad, UIKeyboardTypeTwitter, webSearch.
structured_content.pages.options.text_content_type String Optional. Available for input only. A string value representing the keyboard and system information about the expected semantic meaning for the content that users enter. Available values are: name, namePrefix, givenName, middleName, familyName, nameSuffix, nickname, jobTitle, organizationName, location, fullStreetAddress, streetAddressLine1, streetAddressLine2, addressCity, addressState, addressCityAndState, sublocality, countryName, postalCode, telephoneNumber, emailAddress, URL, creditCardNumber, username, password, newPassword, oneTimeCode.

Example: Apple Messages for Business (Form Message)

Nothing specifically unique as this is an Apple Messages for Business specific structured message type.

Splash

Date Picker

Select

Picker

Input

Get the form responses

The form responses can be directly viewed in the conversation. If you wish to get them via API you can do so by accessing the structured_reply field. It is also included in the webhook of content.imported events.

curl -X GET "https://[YOUR DOMAIN].api.digital.ringcentral.com/1.0/contents/633567aeb42e443f436ac389"
{
  "id": "633567aeb42e443f436ac389",
  "created_at": "2022-09-29T09:38:54Z",
  "updated_at": "2022-09-29T11:25:08Z",
  "approval_required": false,
  "author_id": "63344dcbb42e44256eaf28cf",
  "body": "Report a product issue",
  "body_input_format": "text",
  "category_ids": [],
  "creator_id": null,
  "foreign_id": "ac7f81aa-f881-4857-85da-5f7a2b37cb13",
  "intervention_id": "63344dd1b42e4428b86b5c0d",
  "language": "en",
  "remotely_deleted": false,
  "source_id": "6038c1c69090ee8393c2f169",
  "source_url": null,
  "synchronization_status": "success",
  "status": "ignored",
  "thread_id": "63344dcbb42e44256eaf28d0",
  "in_reply_to_id": "63356768b42e443f08f32cde",
  "in_reply_to_author_id": "6038c1c69090ee8393c2f16e",
  "attachments_count": 0,
  "attachments": [],
  "auto_submitted": false,
  "body_formatted": {
    "text": "Report a product issue",
    "html": "<p>Report a product issue</p>"
  },
  "context_data": null,
  "created_from": "synchronizer",
  "private_message": true,
  "published": true,
  "source_type": "apple_business_chat",
  "structured_content_supported": true,
  "structured_content": {},
  "structured_reply": {
    "responses": [{
        "page_id": "page_1",
        "title": "What date did you receive, or expect to receive the product?",
        "items": [{
          "id": "page_1",
          "title": "09/29/2022",
          "value": "2022-09-28T22:00:00Z"
        }]
      },
      {
        "page_id": "page_2",
        "title": "What was the issue with your product?",
        "items": [{
            "id": "item_id_1",
            "title": "The product does not work",
            "value": "doesnt_work"
          },
          {
            "id": "item_id_3",
            "title": "I haven't received the product",
            "value": "not_received"
          }
        ]
      },
      {
        "page_id": "page_3",
        "title": "What would you like to obtain as compensation?",
        "items": [{
          "id": "item_id_2",
          "title": "A new product",
          "value": "new_product"
        }]
      },
      {
        "page_id": "page_4",
        "title": "If you have anything you'd like to tell us please do",
        "items": [{
          "id": "page_4",
          "title": "Thank you",
          "value": "Thank you"
        }]
      }
    ]
  },
  "type": "form_response",
  "synchronization_error": null,
  "capabilities_supported": [
    "apple_pay",
    "rich_link",
    "authenticate",
    "list",
    "time_select",
    "select"
  ]
}