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

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.**
+
+The two way messaging feature lets the message recipient to receive a question and then reply choosing from a list of pre-defined responses.
+
+e.g.
+Question: Can you still attend your appointment tomorrow?
+Answer options: [Yes, No]
+
+In order to present the recipient with answers include the `answerOptions` field.
+
+This 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/Message.yaml

@@ -15,6 +15,28 @@ 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:
+    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:
+        type:
+          $ref: ../enums/EnumAnswerOptionsType.yaml
+        options:
+          type: array
+          items:
+            type: object
+            properties:
+              code:
+                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.
+                type: string
+                example: Yes
 required:
   - messageReference
   - recipient

specification/schemas/enums/EnumAnswerOptionsType.yaml

@@ -0,0 +1,6 @@
+title: Enum_AnswerOptionsType
+description: The type of answer options available for this message.
+type: string
+enum:
+  - NHSAPP
+example: NHSAPP

specification/schemas/requests/CreateMessage.yaml

@@ -38,7 +38,29 @@ 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:
+            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:
+                type:
+                  $ref: ../enums/EnumAnswerOptionsType.yaml
+                options:
+                  type: array
+                  items:
+                    type: object
+                    properties:
+                      code:
+                        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.
+                        type: string
+                        example: Yes
     required:
       - type
       - attributes