Skip to content

Instruction MacOS

Jump to bottom
panliss91 edited this page Jul 20, 2020 · 5 revisions

Download

Download the latest MacOS zip file and unzip it to a folder location of your choice.

The config file

To configure the survey bot, please edit the config.json which is located in the config folder. To do so, you can use a text editor of your choice (e.g., MacOS's built-in editor TextEdit).

The config file is written in the JavaScript Object Notation (JSON). All used datatypes are listed here:

Name Allowed values
String "your value in quotes"
Integer Numerical values like 1 or 42
Boolean true or false
List Elements inside [] like [1,2,3,4]

NOTE: You can easily extend list by adding a new , and the new value.

General fields

{
    "api_token": "<your bot api token>",
    "surveyCommandEnabled": true,
    "participantsEnterCondition": false,
    // rest of the file...
}

The are three general fields. At the api_token field you must insert the bot api token as String, which you will get from the BotFather. The script use this token to communicate to your bots account.

With the surveyCommandenabled field you can enable the survey command. If enabled, participants can request a daily survey link themselves by entering the /survey command to the bot chat.

The last field participantsEnterCondition defines whether participants can enter their condition themselves or whether the bot chooses the condition randomly for them. If set to true the bot will ask participants for their condition during the subscribe progress.

Both last fields are Boolean values.

Set survey dates and times

{
    // rest of the file...
    "subscription_start_date": "2020-01-19 00:00",
    "subscription_deadline": "2020-01-22 00:00",
    // rest of the file...
}

With the two fields subscription_start_date and subscription_deadline the registration period can be specified. During this period participants can subscribe to the bot with the /subscribe command. After subscription, participants receive the link to the start survey.

NOTE: These timestamps must be entered in the format: YYYY-mm-dd HH:MM

{
    // rest of the file...
    "daily_dates": ["2020-01-23", "2020-01-24"],
    "daily_times": [
        ["10:00", "12:00", "13:15"],
        ["10:00"]
    ],
    "end_dates": ["2020-01-26", "2020-01-27"],
    "end_times": [
        ["08:00", "18:45"],
        ["10:00", "11:20"]
    ],
    // rest of the file...
}

With daily_dates, daily_times, end_dates and end_times fix dates and times for the daily- and end surveys can be set for all participants. For every date in the date list, one list of times must be specified. In the code example above, daily surveys will be sent to the participants at the date 2020-01-23 at the following times:

  • 10:00
  • 12:00
  • 13:15

and at the date 2020-01-24 at the time:

  • 10:00

NOTE: Dates must be entered in the format: YYYY-mm-dd.
NOTE: Times must be entered in the format: HH:MM.
NOTE: If you add a new date to a date list you also have to add a new time list to the associated times field!

{
    // rest of the file...
    "useDayCalculation": true,
    "dayCalculationSettings": {
        "daily_SurveyDays": [1, 2, 5],
        "end_SurveyDays": [6, 9]
    },
    // rest of the file...
}

The day calculation feature can be used to calculate the survey days for each participant individually depending on the subscription date. If useDayCalculation is set to true the fields daily_dates and end_dates will be ignored. When a participant subscribes to the survey, the script will calculate her/his individual dates for a daily survey based on the two fields daily_SurveyDays and end_SurveyDays, i.e., the integer values in the list are day delays after the subscription date. If, for example, a participant subscribes at the 2020-01-01 to the survey with the code example above, she/he will get daily surveys at the following dates:

  • 2020-01-02
  • 2020-01-03
  • 2020-01-06

and end surveys at the following dates:

  • 2020-01-07
  • 2020-01-10
{
    // rest of the file...
    "useTimeCalculation": true,
    "timeCalculationSettings": {
        "daily_DelayMinutesAfterWakeup": 30,
        "daily_SurveysPerDay": 3,
        "daily_DelayMinutesBetweenSurveys": 120,
        "end_DelayMinutesAfterWakeup": 60,
        "end_SurveysPerDay": 2,
        "end_DelayMinutesBetweenSurveys": 120
    },
    // rest of the file...
}

The time calculation feature can be used to calculate the survey times, depending on the wake up time of the participant. If set to true the fields daily_times and end_times will be ignored and the bot will ask each participant for her/his wake up time during the subscribe progress. Given the entires above and a participant indicates her/his wake up time is 08:00, she/he receive daily sureys at 08:30, 10:30 and 12:30. She/he receives an end survey at 09:00 and at 11:00.

NOTE: If end_SurveysPerDay is set to 1 the entry in end_DelayMinutesBetweenSurveys will be ignored.

NOTE: You are free to combine day and time calculation. That is, you can calculate the survey times depending on the wake up time AND the survey days depending on the subscription date.

Link deletion

{
    // rest of the file...
    "linkDeletionSettings": {
        "start_DeleteLinkAtSubscriptionDeadline": true,
        "start_DeleteLinkTimer": false,
        "start_DeleteDelayMinutes": 240,
        "daily_DeleteLinkAtNewLink": true,
        "daily_DeleteLinkTimer": false,
        "daily_DeleteDelayMinutes": 10,
        "end_DeleteLinkAtNewLink": false,
        "end_DeleteLinkTimer": true,
        "end_DeleteDelayMinutes": 30
    },
    // rest of the file...
}

The link deletion settings allows you to configure how long the survey links are visible in the chat.

The start links that were sent upon subscription can be deleted either at the subscription deadline (defined by the subscription_deadline field in Dates and times) or after a certain number of minutes by setting start_DeleteLinkTimer to true and setting the delay minutes at start_DeleteDelayMinutes.

The daily and end links can be deleted either when the next daily resp. end link is sent to the participant by setting ..._DeleteLinkAtNewLink to true or after a certain number of minutes by setting ..._DeleteLinkTimer to true and setting the delay minutes at ..._DeleteDelayMinutes.

NOTE: If both ..._DeleteLinkTimer and ..._DeleteLinkAtNewLink are set to true, the first event occurring will be executed. For example, if the daily_DeleteDelayMinutes is set to 240 but the next daily link will be sent 120 minutes, the link will be deleted when the new link is sent after 120 minutes.

Randomize survey times

{
    // rest of the file...
    "randomTimeShiftSettings": {
        "daily_RandomTimeShiftMinutes": 0,
        "end_RandomTimeShiftMinutes": 0
    },
    // rest of the file...
}

You can randomize the survey times with the two fields daily_RandomTimeShiftMinutes and end_RandomTimeShiftMinutes. Only positive integer values are allowed here. If, for example, the daily_RandomTimeShiftMinutes is set to 10 and the daily survey time is 10:00, the daily survey will send randomly in the time interval between 9:50 and 10:10.

NOTE: The time randomization will work with and without time calculation.

End survey reminder

{
    // rest of the file...
    "endSurveyReminderEnabled": true,
    "endSurveyReminderDelayHours": 1,
    // rest of the file...
}

With the end survey reminder you can remind your participants to fill in the end survey. You can specify the delay of this reminder under endSurveyReminderDelayHours. The delay of the end survey reminder refers to the specified or calculated time for the end survey(s). When this time interval has expired, the bot will ask participants if they have already participated (see image below). If a participant is pressing "no" she/he will get a new link.

Survey urls

{
    // rest of the file...
    "urls": {
        "start_url": [
            "https://www.surveysite.com/start_cond1/",
            "https://www.surveysite.com/start_cond2/"
        ],
        "daily_url": [
            "https://www.surveysite.com/daily_cond1/",
            "https://www.surveysite.com/daily_cond2/"
        ],
        "end_url": [
            ["https://www.surveysite.com/end_cond1_link1/", "https://www.surveysite.com/end_cond1_link2/"],
            ["https://www.surveysite.com/end_cond2_link1/", "https://www.surveysite.com/end_cond2_link2/"]
        ],
        "end_url_distribution": "RANDOM"
    },
    // rest of the file...
}

In the urls section you can specify the survey urls. You can use multiple urls for multiple conditions for each type of url (start, daily and end). The conditions will be either distributed randomly to your participant or the participants enter their condition itself (see General fields). Please note, you can enter multiple end links per condition. These can be distributed with the five following strategies:

  • NONE: Only the first link in each list will be picked. In the code example above only the links with the ending _link1 will be used.
  • DAY: For each day, for which an end survey is sent, a separate link will be used. Accordingly, every end url list must contain as many links as there are end survey days (as defined in end_dates or end_SurveyDays).
  • TIME: For each time, for which an end survey will be sent, a separate link will be used. Accordingly, every end url list must contain as many links as there are end survey times (as defined in end_times or end_SurveysPerDay).
  • MIXED: For each day and time, for which an end survey will be sent, a separate link will be used. So if you have set up two dates and two times for the end surveys you will need four links, one for every combination.
  • RANDOM: The links will be picked randomly.

The distribution strategy must be set at the end_url_distribution field.

NOTE: Each url field (start, daily and end) must contain the same count of conditions.

Texts

{
    // rest of the file...
    "texts": {
        "welcome": "Welcome to the survey bot.",
        "subscribe": "You will get now reminders for the actual survey. Please fill out the start survey.",
        "subscribe_early": "Sorry, the survey has not started yet.",
        "subscribe_late": "Sorry, the survey has already started.",
        "subscribe_already": "Sorry, you are already subscribed.",
        "subscribe_wakeup_time": "Please tell me your wakeup time.",
        "subscribe_condition": "Please enter your condition number.",
        "unsubscribe": "You will get no longer reminder for actual surveys.",
        "daily_reminder": "Hi there, it is time for a daily survey.",
        "end_reminder": "Hi, it is time for the end survey.",
        "survey_reply": "Here is your survey link.",
        "endSurveyReminder": "Hi, have you already participated the end survey?",
        "endSurveyReminderYes": "Yes",
        "endSurveyReminderNo": "No"
    },
    "help": {
        "helpEnabled": true,
        "help_text": "Here are all available commands:\n/subscribe - activates the reminder service\n/unsubscribe - deactivates the reminder service",
        "surveyCommandHelp": "\n/survey - send you an daily survey link"
    }
}

You can edit all text, which were sent from to survey bot to the participant. Furthermore you can enable or disable the help command for the participants.

Run the survey bot

After the configuration you can simply run the Survey Bot file with a double click.

The bot can be terminated with the key combination ctrl+c.

Home

Create a Telegram bot

Install instructions

Clone this wiki locally