Record and enforce consent through the Chat API

api-schemas/v1.yml

@@ -51,6 +51,49 @@ paths:
               schema:
                 $ref: '#/components/schemas/ChatTaskPollError'
           description: ''
+  /api/chat/{session_id}/consent/:
+    post:
+      operationId: chat_record_consent
+      description: |-
+        Record consent for the form version the participant was shown.
+
+        A `form_version_id` that is not the session version's current form is refused with `409`
+        and the current block, so the widget re-renders rather than recording consent to text the
+        participant never saw.
+      summary: Record that the participant accepted the chatbot's consent form
+      parameters:
+      - in: path
+        name: session_id
+        schema:
+          type: string
+        description: Session ID
+        required: true
+      tags:
+      - Chat
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/ChatConsentRequest'
+        required: true
+      security:
+      - cookieAuth: []
+      - embedKeyAuth: []
+      responses:
+        '204':
+          description: No response body
+        '400':
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ChatConsentSessionEnded'
+          description: ''
+        '409':
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ChatConsentStale'
+          description: ''
   /api/chat/{session_id}/message/:
     post:
       operationId: chat_send_message
@@ -93,6 +136,12 @@ paths:
               schema:
                 $ref: '#/components/schemas/ChatSendMessageResponse'
           description: ''
+        '403':
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ChatConsentRequired'
+          description: ''
   /api/chat/{session_id}/poll/:
     get:
       operationId: chat_poll_response
@@ -158,6 +207,12 @@ paths:
               schema:
                 $ref: '#/components/schemas/ChatUploadFileResponse'
           description: ''
+        '403':
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ChatConsentRequired'
+          description: ''
   /api/chat/start/:
     post:
       operationId: chat_start_session
@@ -213,6 +268,10 @@ paths:
                     participant:
                       identifier: abc
                       remote_id: abc
+                    consent:
+                      required: false
+                      form_version_id: null
+                      text: null
                   summary: Session started with published version
                 StartSessionSpecificVersionResponse:
                   value:
@@ -226,6 +285,10 @@ paths:
                     participant:
                       identifier: abc
                       remote_id: abc
+                    consent:
+                      required: false
+                      form_version_id: null
+                      text: null
                   summary: Session started with specific version
           description: ''
         '401':
@@ -1111,6 +1174,77 @@ components:
       - assistant
       type: string
       description: '* `assistant` - assistant'
+    ChatConsent:
+      type: object
+      properties:
+        required:
+          type: boolean
+          title: Consent required
+          description: True until the participant accepts the chatbot's consent form.
+            Send and upload return `403 consent_required` while this is true; poll
+            is never gated.
+        form_version_id:
+          type: integer
+          nullable: true
+          title: Consent form version ID
+          description: Identifies the frozen consent form text. Post it back to `/consent/`.
+            A changed form gets a new id, and consent is required again until the
+            participant accepts it.
+        text:
+          type: string
+          nullable: true
+          title: Consent text
+          description: Rendered HTML of the consent form. Present only while consent
+            is required.
+      required:
+      - form_version_id
+      - required
+      - text
+    ChatConsentRequest:
+      type: object
+      properties:
+        form_version_id:
+          type: integer
+          title: Consent form version ID
+          description: The `form_version_id` from the start or poll response being
+            accepted.
+      required:
+      - form_version_id
+    ChatConsentRequired:
+      type: object
+      properties:
+        error:
+          type: string
+        code:
+          type: string
+          description: '`consent_required`.'
+        consent:
+          $ref: '#/components/schemas/ChatConsent'
+      required:
+      - code
+      - consent
+      - error
+    ChatConsentSessionEnded:
+      type: object
+      properties:
+        error:
+          type: string
+      required:
+      - error
+    ChatConsentStale:
+      type: object
+      properties:
+        error:
+          type: string
+        code:
+          type: string
+          description: Always `consent_stale`.
+        consent:
+          $ref: '#/components/schemas/ChatConsent'
+      required:
+      - code
+      - consent
+      - error
     ChatPollResponse:
       type: object
       properties:
@@ -1126,7 +1260,12 @@ components:
           allOf:
           - $ref: '#/components/schemas/SessionStatusEnum'
           title: Current session status
+        consent:
+          allOf:
+          - $ref: '#/components/schemas/ChatConsent'
+          readOnly: true
       required:
+      - consent
       - has_more
       - messages
       - session_status
@@ -1242,8 +1381,13 @@ components:
           allOf:
           - $ref: '#/components/schemas/Participant'
           readOnly: true
+        consent:
+          allOf:
+          - $ref: '#/components/schemas/ChatConsent'
+          readOnly: true
       required:
       - chatbot
+      - consent
       - participant
       - session_id
     ChatTaskPoll:

apps/api/chat_consent.py

@@ -0,0 +1,59 @@
+"""Consent as the Chat API reports and enforces it (public channel design, D7).
+
+The store is ``ParticipantData.system_metadata["consent"]``, shared with CommCare Connect and read
+by ``ConsentCheckStage``, plus the accepted ``consent_form_version_id``. The text is the frozen
+``ConsentForm`` on the version the session runs against; a republished form has a new id, so the
+participant is prompted again until they accept it.
+"""
+
+from rest_framework import status
+from rest_framework.response import Response
+
+from apps.channels.widget_versions import WIDGET_VERSION_HEADER, widget_enforces_consent
+from apps.experiments.models import Experiment, ExperimentSession, ParticipantData
+
+
+def participant_data_for(session: ExperimentSession) -> ParticipantData | None:
+    return ParticipantData.objects.for_experiment(session.experiment).filter(participant=session.participant).first()
+
+
+def consent_block(version: Experiment, participant_data: ParticipantData | None) -> dict:
+    form = version.consent_form
+    if form is None:
+        return {"required": False, "form_version_id": None, "text": None}
+    consented = participant_data is not None and participant_data.has_consented_to(form.id)
+    return {
+        "required": not consented,
+        "form_version_id": form.id,
+        "text": None if consented else form.get_rendered_content(),
+    }
+
+
+def session_consent_block(session: ExperimentSession) -> dict:
+    """The consent block for `session`, without a participant-data query when there is no form.
+
+    Always the session's own version, never a `version_number` the caller asked to preview:
+    participant data holds one accepted form id and the consent endpoint has no version to key
+    on, so a preview gated on the previewed version's form could never be satisfied.
+    """
+    version = session.experiment_version
+    if version.consent_form_id is None:
+        return consent_block(version, None)
+    return consent_block(version, participant_data_for(session))
+
+
+def consent_refusal(request, session: ExperimentSession) -> Response | None:
+    """The 403 that holds a message until consent is recorded, or None.
+
+    Only widgets from ``CONSENT_INTRODUCED`` on are refused: older widgets treat every 403 as a
+    dead session, and non-widget API callers have no consent surface.
+    """
+    if not widget_enforces_consent(request.headers.get(WIDGET_VERSION_HEADER)):
+        return None
+    block = session_consent_block(session)
+    if not block["required"]:
+        return None
+    return Response(
+        {"error": "Consent is required before chatting", "code": "consent_required", "consent": block},
+        status=status.HTTP_403_FORBIDDEN,
+    )

apps/api/serializers.py

@@ -349,6 +349,32 @@ def validate_timezone(self, value):
         return value if value and value in available_timezones() else None
 
 
+class ChatConsentSerializer(serializers.Serializer):
+    required = serializers.BooleanField(
+        label="Consent required",
+        help_text="True until the participant accepts the chatbot's consent form. Send and upload return"
+        " `403 consent_required` while this is true; poll is never gated.",
+    )
+    form_version_id = serializers.IntegerField(
+        label="Consent form version ID",
+        allow_null=True,
+        help_text="Identifies the frozen consent form text. Post it back to `/consent/`. A changed form"
+        " gets a new id, and consent is required again until the participant accepts it.",
+    )
+    text = serializers.CharField(
+        label="Consent text",
+        allow_null=True,
+        help_text="Rendered HTML of the consent form. Present only while consent is required.",
+    )
+
+
+class ChatConsentRequest(serializers.Serializer):
+    form_version_id = serializers.IntegerField(
+        label="Consent form version ID",
+        help_text="The `form_version_id` from the start or poll response being accepted.",
+    )
+
+
 class ChatStartSessionResponse(serializers.Serializer):
     session_id = serializers.UUIDField(label="Session ID")
     session_token = serializers.CharField(
@@ -360,6 +386,7 @@ class ChatStartSessionResponse(serializers.Serializer):
     )
     chatbot = ExperimentSerializer(read_only=True)
     participant = ParticipantSerializer(read_only=True)
+    consent = ChatConsentSerializer(read_only=True)
 
 
 class ChatSendMessageRequest(serializers.Serializer):
@@ -390,6 +417,7 @@ class ChatPollResponse(serializers.Serializer):
     session_status = serializers.ChoiceField(
         choices=[("active", "Active"), ("ended", "Ended")], label="Current session status"
     )
+    consent = ChatConsentSerializer(read_only=True)
 
 
 class TriggerBotMessageRequest(serializers.Serializer):

apps/api/tests/test_chat_api_anon.py

@@ -44,6 +44,11 @@ def test_start_chat_session(team_with_users, api_client, experiment):
             "versions": [],
         },
         "participant": {"identifier": mock.ANY, "remote_id": ""},
+        "consent": {
+            "required": True,
+            "form_version_id": experiment.consent_form_id,
+            "text": experiment.consent_form.get_rendered_content(),
+        },
     }
     assert response_json["session_token"]  # token must be non-null
     assert response_json["participant"]["identifier"].startswith("anon:")
@@ -147,7 +152,16 @@ def test_session_poll(api_client, session):
     url = reverse("api:chat:poll-response", kwargs={"session_id": session.external_id})
     response = api_client.get(url)
     response_json = response.json()
-    assert response_json == {"has_more": False, "messages": [], "session_status": "active"}
+    assert response_json == {
+        "has_more": False,
+        "messages": [],
+        "session_status": "active",
+        "consent": {
+            "required": True,
+            "form_version_id": session.experiment.consent_form_id,
+            "text": session.experiment.consent_form.get_rendered_content(),
+        },
+    }
 
 
 @pytest.mark.django_db()
@@ -188,17 +202,24 @@ def test_session_poll_with_messages(api_client, session):
             "tags": ["test"],
         },
     ]
+    expected_consent = {
+        "required": True,
+        "form_version_id": session.experiment.consent_form_id,
+        "text": session.experiment.consent_form.get_rendered_content(),
+    }
     assert response.json() == {
         "has_more": False,
         "messages": expected_messages,
         "session_status": "active",
+        "consent": expected_consent,
     }
 
     response = api_client.get(url, data={"limit": 1})
     assert response.json() == {
         "has_more": True,
         "messages": [expected_messages[0]],
         "session_status": "active",
+        "consent": expected_consent,
     }