CCM-14740: add two-way-messaging to API docs

package.json

@@ -27,7 +27,7 @@
   "devDependencies": {
     "@babel/core": "^7.25.2",
     "@babel/eslint-parser": "^7.25.1",
-    "@redocly/cli": "^2.14.4",
+    "@redocly/cli": "1.34.15",
     "eslint": "^8.57.1",
     "eslint-config-airbnb-base": "^15.0.0",
     "eslint-config-prettier": "^8.5.0",

specification/documentation/APIDescription.md

@@ -215,6 +215,20 @@ Every request includes an `idempotencyKey` field located in the meta collection
 
 If a request fails, our retry policy will continue to attempt to deliver the callback for a period of 2 hours.
 
+## Two-way messaging
+
+**This feature is currently under development and is not yet ready to use.**
+
+Two-way messaging lets a service send a simple question to a recipient through the NHS App and provide a fixed list of possible answers. The recipient can choose one answer from the list, and that response is sent back to the service.
+
+e.g.
+Question: Can you still attend your GP appointment on Tuesday 26th May at 14:00?
+Answer options: [Yes, No]
+
+In order to present the recipient with answers include the `answerOptions` field.
+
+This feature is currently only supported by the NHSAPP channel.
+
 ## Message character limits
 Different character limits apply to each of the communication channels as listed below. NHS Notify will validate that any personalisation fields submitted in the send message request do not exceed these limits but it is the client's responsibility to ensure that when personalisation is combined with any templated text, the channel character limit is not exceeded.
 

specification/documentation/CreateMessage.md

@@ -33,6 +33,6 @@ Here is an example curl request which creates a message using one of these routi
   curl -X POST \
     --header "Accept: */*" \
     --header "Content-type: application/vnd.api+json" \
-    -d '{"data": {"type": "Message","attributes": {"routingPlanId": "b838b13c-f98c-4def-93f0-515d4e4f4ee1","messageReference": "da0b1495-c7cb-468c-9d81-07dee089d728","recipient": {"nhsNumber": "9990548609"},"originator": {"odsCode":"X123"},"personalisation": {}}}}' \
+    -d '{"data": {"type": "Message","attributes": {"routingPlanId": "b838b13c-f98c-4def-93f0-515d4e4f4ee1","messageReference": "da0b1495-c7cb-468c-9d81-07dee089d728","recipient": {"nhsNumber": "9990548609"},"originator": {"odsCode":"X123"},"personalisation": {},"answerOptions": {"NHSAPP":[{"code":"Yes"},{"code":"No"}]}}}}' \
     https://sandbox.api.service.nhs.uk/comms/v1/messages
 ```

specification/documentation/CreateMessageBatch.md

@@ -38,6 +38,6 @@ Here is an example curl request which creates a message batch using one of these
   curl -X POST \
     --header "Accept: */*" \
     --header "Content-type: application/vnd.api+json" \
-    -d '{"data": {"type": "MessageBatch","attributes": {"routingPlanId": "b838b13c-f98c-4def-93f0-515d4e4f4ee1","messageBatchReference": "da0b1495-c7cb-468c-9d81-07dee089d728","messages": [{"messageReference": "703b8008-545d-4a04-bb90-1f2946ce1575","recipient": {"nhsNumber": "9990548609"},"originator": {"odsCode":"X123"},"personalisation": {}}]}}}' \
+    -d '{"data": {"type": "MessageBatch","attributes": {"routingPlanId": "b838b13c-f98c-4def-93f0-515d4e4f4ee1","messageBatchReference": "da0b1495-c7cb-468c-9d81-07dee089d728","messages": [{"messageReference": "703b8008-545d-4a04-bb90-1f2946ce1575","recipient": {"nhsNumber": "9990548609"},"originator": {"odsCode":"X123"},"personalisation": {},"answerOptions": {"NHSAPP":[{"code":"Yes"},{"code":"No"}]}}]}}}' \
     https://sandbox.api.service.nhs.uk/comms/v1/message-batches
 ```

specification/schemas/components/AnswerOption.yaml

@@ -0,0 +1,10 @@
+type: object
+title: AnswerOption
+properties:
+  code:
+    type: string
+    examples:
+      - Yes
+      - No
+    description: |-
+      This is the code that will be sent back to you in the callback when a recipient selects this option. It is for your reference to understand which option the recipient has selected. It is also the display value shown to the recipient.

specification/schemas/components/AnswerOptions.yaml

@@ -0,0 +1,18 @@
+type: object
+optional: true
+description: |-
+  The answer options for this message. These are channel specific.
+
+  If you provide answer options, then they will be presented to the receipient for reply options. These will then be sent back via the two-way messaging callback mechanism.
+
+  This feature needs to be enabled on your account and is subject to the relevant callback integration being completed.
+properties:
+  NHSAPP:
+    type: array
+    minItems: 1
+    maxItems: 6
+    examples:
+      - code: Yes
+      - code: No
+    items:
+      $ref: ./AnswerOption.yaml

specification/schemas/components/Message.yaml

@@ -15,6 +15,12 @@ properties:
   personalisation:
     type: object
     description: The personalisation keys and values for this message. These are linked to the routingPlanId provided and are agreed upon during [onboarding](#overview--onboarding).
+  answerOptions:
+    example:
+      NHSAPP:
+        - code: Yes
+        - code: No
+    $ref: ./AnswerOptions.yaml
 required:
   - messageReference
   - recipient

specification/schemas/requests/CreateMessage.yaml

@@ -38,7 +38,13 @@ properties:
             $ref: ../components/Originator.yaml
           personalisation:
             type: object
-            description: 'The personalisation keys and values for this message. These are linked to the routingPlanId provided and are agreed upon during [onboarding](#overview--onboarding).'
+            description: "The personalisation keys and values for this message. These are linked to the routingPlanId provided and are agreed upon during [onboarding](#overview--onboarding)."
+          answerOptions:
+            example:
+              NHSAPP:
+                - code: Yes
+                - code: No
+            $ref: ../components/AnswerOptions.yaml
     required:
       - type
       - attributes