MTurk Integration

Overview

ChatbotLab can integrate directly with Amazon Mechanical Turk (MTurk) to link worker identifiers (Worker IDs, HIT IDs, Assignment IDs) with your survey and chat conversation data. This enables accurate data merging, auditing, and protection against data loss.

MTurk metadata is stored automatically in ChatbotLab’s backend when passed through survey URLs.

Workflow Summary

To use ChatbotLab through MTurk:

1. Create an MTurk HIT (Human Intelligence Task).

2. Set the External Question URL to your survey (Qualtrics or REDCap) that includes a ChatbotLab chatbot.

3. MTurk automatically appends identifying parameters to your survey URL:

   ?assignmentId=${assignmentId}&workerId=${workerId}&hitId=${hitId}

4. In your survey, save each parameter as embedded data.

5. Pass these values through your ChatbotLab integration code so they are stored in the backend database.

   Qualtrics.SurveyEngine.addOnload(function() {
      ...
      var workerID = "<WORKER-ID>";       // MTurk workerId
      var assignmentID = "<ASSIGNMENT-ID>"; // MTurk assignmentId
      var hitID = "<HIT-ID>";               // MTurk hitId
   
      ...
   
      botURL += "&participant_id=" + encodeURIComponent(workerID);
      botURL += "&mturk_assignment_id=" + encodeURIComponent(assignmentID);
      botURL += "&mturk_hit_id=" + encodeURIComponent(hitID);
   });
   

Example (Qualtrics)

To capture and link MTurk identifiers in Qualtrics:

1. Open your survey.

2. Navigate to Survey Flow → Add a New Element → Embedded Data.

3. Add the following variables and set them to pull from the URL:

   Set Embedded Data:
   
      workerId     → Value will be set from Panel or URL
      assignmentId → Value will be set from Panel or URL
      hitId        → Value will be set from Panel or URL
   

4. Save your Survey Flow.

5. In the ChatbotLab question’s JavaScript editor, reference the embedded fields:

   Qualtrics.SurveyEngine.addOnload(function() {
      ...
      var workerID = "${e://Field/workerId}";
      var assignmentID = "${e://Field/assignmentId}";
      var hitID = "${e://Field/hitId}";
   
      ...
   
      botURL += "&participant_id=" + encodeURIComponent(workerID);
      botURL += "&mturk_assignment_id=" + encodeURIComponent(assignmentID);
      botURL += "&mturk_hit_id=" + encodeURIComponent(hitID);
   });
   

Data Storage and Linking

Once participants complete the chatbot interaction, their MTurk identifiers are stored within the ChatbotLab database:

• participant_id → stored in chatbot_conversation.participant_id

• mturk_assignment_id → stored in chatbot_conversation.survey_meta_data

• mturk_hit_id → stored in chatbot_conversation.survey_meta_data

These fields can be used to merge ChatbotLab logs with MTurk exports or survey data.

Tracking and Payment Verification

• You can use the assignmentId or hitId values to verify completion and automate bonus payments through the MTurk API.

• Completion codes can be displayed on your survey’s final page or inside the ChatbotLab chat after the final message.

• These codes can also be included in survey_meta_data for verification.

Best Practices

• Test your HIT in MTurk Sandbox to ensure all parameters (workerId, assignmentId, hitId) are properly passed.

• Confirm that conversation entries appear in ChatbotLab’s Admin Panel with matching MTurk metadata.

• Always use the same parameter names (workerId, assignmentId, hitId) in both the survey and your ChatbotLab embed script.