Trees (Beta)

Note

API support for Trees is in BETA-mode and is limited to GET requests for acessing tree data and results. Trees can only be built on the VOTO platform using the block builder canvas. Report any issues to support@votomobile.org

Trees are our most versatile content building tool. They can be used to build the most complex survey, with different flows depending on a subscriber’s response, but can also be used to design a simple message sequence or a straightforward survey. Tree content is built on the VOTO platform by adding blocks and drawing connections between the blocks to dictate the subscriber’s flow through the content.

For a brief introduction to trees, see this video. For more details, see Creating and Building Trees.

Trees are built using blocks. There are three types of tree blocks:

  1. Content blocks
  2. Branching blocks
  3. Advanced blocks

Content blocks contain messages the subscribers receive or questions with which the subscribers interact;

  • Message: Use this block to add a message to your tree content. Message blocks contain one-way content. The subscribers will receive the IVR or SMS content when they pass through this block.
  • Multiple Choice Question: Use this block to ask subscribers a question that they can respond to by selecting one of many options.
  • Numeric Question: Use this block to ask subscribers a question that they can respond to using the number keys on their phones. This question block is useful for recording unique ID number codes or precise ages.
  • Open-Ended Question: Use this block to ask subscribers a question to which they can reply in their own words. Using SMS, the subscriber can type in a unique response and using IVR (voice), the subscriber will be given the opportunity to respond to the question by speaking into the phone after hearing a tone, much like recording a voicemail.

Branching Blocks contain directions for which path a particular subscriber should follow in the tree;

  • Decision Branch: Use this block to decide a subscriber’s path based on the subscriber’s responses to preceeding Multiple Choice questions. The Multiple Choice questions may directly precede the Decision Branch or they may be much farther up in the tree. Set the conditions for which the decision branch is true. All other response combinations will follow the path from False.
  • Numeric Branch: Use this block to decide a subscriber’s path based on the subscriber’s responses to preceeding Numeric questions. The Numeric questions may directly precede the Numeric Branch or they may be much farther up in the tree. Set the conditions for up to eight unique outputs, having a maximum of nine total outputs. The final output in any configuration is reserved for all response combinations that do not match any defined output criteria.
  • Random Branch: Use this block to randomly choose what block a subscriber will interact with next. A Random Branch block can be used to randomly select which one of many questions a subscriber should receive or to randomize the order in which a subscriber receives a set of questions. This block is especially helpful in controlling for bias in surveys.
  • Branch via Subscriber Data: Use this block to determine a subscriber’s path in the tree based on one of their subscriber properties. The deciding property can be a default field such as Location or Comments or may be a custom field suchs as “Maize or “Sorghum”.
  • Branch via Group Membership: Use this block to determine subscribers’ paths in the tree based on whether or not they belong to a selected group in your organisation.
  • Branch via Group Size: Use this block to branch based on the size of a designated group. This block allows you to create quotas or vary call behaviour based on how many people have been added to an indicated group. It’s particularly useful for changing the flow of a call based on demographic information, or when you want to send certain question blocks to a limited number of callers. For example, if you want a survey to reach X people with about a 50:50 gender split, you could use this block in combination with an Edit Group Membership block to design a tree that will continue through the content only for female subscribers after X/2 male subscribers have interacted with the tree.

Advanced Blocks instigate a change in the subscriber’s properties in the VOTO app or contain more complicated content options. Connecting lines are drawn between the blocks to define the path by which subscribers will travel through the tree.

  • Run Another Tree: this block will cause a subscriber to enter another tree in the organisation. The next block that the subscriber will enter after a Jump to Another Tree block will be the Starting block of the tree to which the jump block is pointing. Note that the starting block is marked by a small downward pointing arrow in its top right corner.
  • Language Selector: Use this block to send subscribers the language selector part way through a call and change their preferred language. This block is intended to create a convenient way for you to offer subscribers the option of changing the default language in which they receive content. Recall that once a subscriber sets her preferred language through the language selector, she will receive content in this language by default unless she receives the language selector again through this block (note that the only other way for a subscriber to receive the language selector after a preferred language has been selected is to reset their preferred language to Unknown manually or using the Edit Subscriber Property Block - once the language has been reset, the next time this subscriber calls in, he will receive the language selector before accessing the call content).
  • Edit subscriber Property: This block can be used to edit the property fields of a subscriber. You can view a subscriber’s properties in the Subscribers section of your organisation (accessible from the left-hand panel on the dashboard).
  • Edit Group Membership: This block can be used to add or remove subscribers from a group.
  • Random Order Multiple Choice Question: Use this block in place of the regular Multiple Choice Question Block in IVR trees when asking multiple choice questions for which the order of choice options may bias responses. This block will present the choice options in a random order for each call. Note that if the question is repeated due to an invalid response, the choice options will be repeated in the same order as they were initially presented. This block is available for IVR trees only.

List All Trees

Method: GET

URL: https://go.votomobile.org/api/v1/trees

Parameters:

  • api_key

Returns:

{
   "status":200,
   "code":1000,
   "data":{
      "trees":[
         {
            "id":"3",
            "title":"Tree One",
            "description":"",
            "has_voice":"1",
            "has_sms":"0",
            "has_ussd":"0",
            "starting_block_id":"48",
            "is_interactive":"1",
            "created_at":"2016-03-23 20:41:39",
            "updated_at":"2016-03-27 20:05:46",
            "num_blocks":"4"
         },
         {
            "id":"4",
            "title":"Tree One (Copy)",
            "description":"",
            "has_voice":"1",
            "has_sms":"0",
            "has_ussd":"0",
            "starting_block_id":"74",
            "is_interactive":"1",
            "created_at":"2016-03-31 17:32:53",
            "updated_at":"2016-03-31 17:37:59",
            "num_blocks":"10"
         }
      ]
   },
   "message":"Trees fetched successfully",
   "more_info":"",
   "pagination":{
      "nextURL":"https://192.168.3.5/api/v1/trees?api_key=125d50ceb4e4e2186cf47e3c3&page_after=4",
      "previousURL":null
   },
   "url":"https://192.168.3.5/api/v1/trees?api_key=125d50ceb4e4e2186cf47e3c3"
}

List Tree Details

Method: GET

URL: https://go.votomobile.org/api/v1/trees/[tree_id]

Parameters:

  • api_key

Returns:

{
   "status":200,
   "code":1000,
   "data":{
      "tree":[
         {
            "id":"7",
            "title":"Full Tree",
            "description":"A tree with all the blocks!",
            "has_voice":"1",
            "has_sms":"1",
            "has_ussd":"0",
            "starting_block_id":"1366",
            "is_interactive":"1",
            "created_at":"2016-04-17 00:52:55",
            "updated_at":"2016-04-17 22:05:39",
            "num_blocks":"16"
         }
      ]
   },
   "message":"Tree 7 details fetched successfully",
   "more_info":"",
   "pagination":null,
   "url":"https://192.168.3.5/api/v1/trees/7?api_key=125d50ceb4e4e2186cf47e3c3"
}

List Tree Blocks

Method: GET

URL: https://go.votomobile.org/api/v1/trees/[tree_id]/blocks

Parameters:

  • api_key

Returns:

{
   "status":200,
   "code":1000,
   "data":{
      "tree":[
         {
            "id":"7",
            "starting_block_id":"1366",
            "num_blocks":"16"
         }
      ],
      "blocks":[
         {
            "id":"1359",
            "type":"Message",
            "num_outputs":"1",
            "is_interactive":0,
            "title":"This is why we vote...",
            "repeat_enabled":1,
            "repeat_times":"3",
            "repeat_key":"2",
            "repeat_delay_seconds":"7",
            "audio_files":[
               {
                  "language_id":"6",
                  "language_name":"English",
                  "audio_file_id":"13",
                  "audio_file_description":"vote-message-en.wav"
               }
            ],
            "sms_content":[
               {
                  "language_id":"6",
                  "language_name":"English",
                  "sms_content":"We vote to exercise our franchise."
               }
            ],
            "connections_to_block":[
               "1360"
            ],
            "connections_from_block":[
               "1360"
            ]
         },
         {
            "id":"1360",
            "type":"Multiple Choice Question",
            "num_outputs":"4",
            "is_interactive":1,
            "title":"Are you a registered voter?",
            "choices":[
               "Yes",
               "No",
               "Maybe",
               "Not Interested"
            ],
            "choices_key_press_options":{
               "1":"1",
               "2":"2",
               "3":"3",
               "4":"*"
            },
            "choices_sms_response_options":{
               "1":[
                  "1",
                  "yes"
               ],
               "2":[
                  "2",
                  "no"
               ],
               "3":[
                  "3",
                  "maybe"
               ],
               "4":[
                  "*",
                  "not interested"
               ]
            },
            "repeat_times":2,
            "branching_enabled":1,
            "audio_files":[
               {
                  "language_id":"6",
                  "language_name":"English",
                  "audio_file_id":"16",
                  "audio_file_description":"voter-question-en.wav"
               },
               {
                  "language_id":"7",
                  "language_name":"French",
                  "audio_file_id":"17",
                  "audio_file_description":"voter-question-fr.wav"
               },
               {
                  "language_id":"10",
                  "language_name":"Pidgin",
                  "audio_file_id":"18",
                  "audio_file_description":"voter-question-pdg.wav"
               }
            ],
            "sms_content":[
               {
                  "language_id":"6",
                  "language_name":"English",
                  "sms_content":"Are you a registered voter? Reply 1 for Yes, 2 for No, 3 for Maybe, 4 for Not Interested."
               },
               {
                  "language_id":"7",
                  "language_name":"French",
                  "sms_content":"Êtes-vous un électeur inscrit? Répondre 1 pour Oui , 2 pour Non, 3 pour Peut-être , pour 4 Pas intéressé."
               },
               {
                  "language_id":"10",
                  "language_name":"Pidgin",
                  "sms_content":"You don put your name down as person wey fit vote? Press 1 for Yes, 2 say No, 3 say e be like so, 4 say you e no concern you."
               }
            ],
            "connections_to_block":[
               "1366",
               "1359",
               "1368"
            ],
            "connections_from_block":[
               "1359",
               "1361",
               "1362"
            ]
         },
         {
            "id":"1361",
            "type":"Numeric Question",
            "num_outputs":"1",
            "is_interactive":1,
            "title":"How many times have you voted?",
            "num_repeats":2,
            "max_numeric_digits":2,
            "audio_files":[
               {
                  "language_id":"6",
                  "language_name":"English",
                  "audio_file_id":"19",
                  "audio_file_description":"count-voted-en.wav"
               }
            ],
            "sms_content":[
               {
                  "language_id":"6",
                  "language_name":"English",
                  "sms_content":"How many times have you voted? Reply with up to 2 digits."
               }
            ],
            "connections_to_block":[
               "1360"
            ],
            "connections_from_block":[
               "1364"
            ]
         },
         {
            "id":"1362",
            "type":"Open-Ended Question",
            "num_outputs":"1",
            "is_interactive":1,
            "title":"Why are you not registered as a voter?",
            "max_open_length":60,
            "audio_files":[
               {
                  "language_id":"6",
                  "language_name":"English",
                  "audio_file_id":"20",
                  "audio_file_description":"why-not-voter-en.wav"
               }
            ],
            "sms_content":[
               {
                  "language_id":"6",
                  "language_name":"English",
                  "sms_content":"Why are you not registered as a voter?"
               }
            ],
            "connections_to_block":[
               "1360"
            ],
            "connections_from_block":[
               "1364"
            ]
         },
         {
            "id":"1363",
            "type":"Decision Branch",
            "num_outputs":"2",
            "is_interactive":0,
            "title":"If all of the following are true...",
            "logic":"all",
            "question_blocks":[
               {
                  "block_id":"1360",
                  "choice":"1"
               },
               {
                  "block_id":"1360",
                  "choice":"2"
               },
               {
                  "block_id":"1360",
                  "choice":"4"
               },
               {
                  "block_id":"1360",
                  "choice":"3"
               }
            ],
            "connections_to_block":[
               "1364",
               "1369"
            ],
            "connections_from_block":[
               "1367"
            ]
         },
         {
            "id":"1364",
            "type":"Numeric Branch",
            "num_outputs":"6",
            "is_interactive":0,
            "options":[
               {
                  "logic":"any",
                  "num_conditions":2,
                  "conditions":[
                     {
                        "block_id":"1361",
                        "logic":"morethan",
                        "value":3
                     },
                     {
                        "block_id":"1361",
                        "logic":"lessthan",
                        "value":0
                     }
                  ]
               },
               {
                  "logic":"atleast",
                  "num_conditions":2,
                  "conditions":[
                     {
                        "block_id":"1361",
                        "logic":"morethan",
                        "value":3
                     },
                     {
                        "block_id":"1361",
                        "logic":"lessthan",
                        "value":0
                     },
                     {
                        "block_id":"1361",
                        "logic":"equalto",
                        "value":1
                     }
                  ],
                  "at_least_threshold_value":1
               },
               {
                  "logic":"all",
                  "num_conditions":1,
                  "conditions":[
                     {
                        "block_id":"1361",
                        "logic":"morethan",
                        "value":3
                     },
                     {
                        "block_id":"1361",
                        "logic":"lessthan",
                        "value":0
                     },
                     {
                        "block_id":"1361",
                        "logic":"equalto",
                        "value":1
                     },
                     {
                        "block_id":"1361",
                        "logic":"morethan",
                        "value":0
                     }
                  ],
                  "at_least_threshold_value":1
               },
               {
                  "logic":"all",
                  "num_conditions":1,
                  "conditions":[
                     {
                        "block_id":"1361",
                        "logic":"morethan",
                        "value":3
                     },
                     {
                        "block_id":"1361",
                        "logic":"lessthan",
                        "value":0
                     },
                     {
                        "block_id":"1361",
                        "logic":"equalto",
                        "value":1
                     },
                     {
                        "block_id":"1361",
                        "logic":"morethan",
                        "value":0
                     },
                     {
                        "block_id":"1361",
                        "logic":"morethan",
                        "value":0
                     }
                  ],
                  "at_least_threshold_value":1
               }
            ],
            "connections_to_block":[
               "1361",
               "1362"
            ],
            "connections_from_block":[
               "1369",
               "1363"
            ]
         },
         {
            "id":"1365",
            "type":"Random Branch",
            "num_outputs":2,
            "is_interactive":0,
            "loop_back_method":"exit",
            "connections_to_block":[
               "1367"
            ],
            "connections_from_block":[
               "1370",
               "1368"
            ]
         },
         {
            "id":"1366",
            "type":"Branch via Subscriber Data",
            "num_outputs":"2",
            "is_interactive":0,
            "action_type":"viaCustomData",
            "subscriber_property_id":"40",
            "subscriber_property_name":"movie",
            "data_value":"10",
            "connections_to_block":[

            ],
            "connections_from_block":[
               "1360"
            ]
         },
         {
            "id":"1367",
            "type":"Branch via Group Membership",
            "num_outputs":"2",
            "is_interactive":0,
            "group_id":"124",
            "condition_subscriber_is_in_group":0,
            "connections_to_block":[
               "1363"
            ],
            "connections_from_block":[
               "1365",
               "1371"
            ]
         },
         {
            "id":"1368",
            "type":"Branch via Group Size",
            "num_outputs":"2",
            "is_interactive":0,
            "group_id":"124",
            "quota_threshold":100,
            "connections_to_block":[
               "1365"
            ],
            "connections_from_block":[
               "1360",
               "1373"
            ]
         },
         {
            "id":"1369",
            "type":"Edit Group Membership",
            "num_outputs":"1",
            "is_interactive":0,
            "group_id":"124",
            "action_type":"addToGroup",
            "connections_to_block":[
               "1364"
            ],
            "connections_from_block":[
               "1363"
            ]
         },
         {
            "id":"1370",
            "type":"Edit Subscriber Property",
            "num_outputs":"1",
            "is_interactive":0,
            "action_type":"setStartDate",
            "start_date_method":"relativeToNumericInput",
            "start_date_input_on_numeric_block_id":"1361",
            "connections_to_block":[
               "1365"
            ],
            "connections_from_block":[
               "1372"
            ]
         },
         {
            "id":"1371",
            "type":"Run Another Tree",
            "num_outputs":"1",
            "is_interactive":"0",
            "title":"Tree C",
            "run_tree_id":"6",
            "connections_to_block":[
               "1367"
            ],
            "connections_from_block":[

            ]
         },
         {
            "id":"1372",
            "type":"Language Selector",
            "num_outputs":"1",
            "is_interactive":0,
            "language_selector_id":null,
            "connections_to_block":[
               "1370"
            ],
            "connections_from_block":[
               "1374"
            ]
         },
         {
            "id":"1373",
            "type":"Random Order Multiple Choice Question",
            "num_outputs":"3",
            "is_interactive":1,
            "title":"Who are you voting for?",
            "choices":[
               "ABC",
               "MNO",
               "XYZ"
            ],
            "choices_key_press_options":[

            ],
            "choices_sms_response_options":[

            ],
            "choices_locked_in_position":[
               1,
               2
            ],
            "choices_voice_content":{
               "1":{
                  "choice":[
                     {
                        "language_id":"6",
                        "language_name":"English",
                        "audio_file_id":"21",
                        "audio_file_description":"voting-for-abc-en.wav"
                     },
                     {
                        "language_id":"7",
                        "language_name":"French",
                        "audio_file_id":"22",
                        "audio_file_description":"voting-for-abc-fr.wav"
                     }
                  ],
                  "option":[
                     {
                        "language_id":"6",
                        "language_name":"English",
                        "audio_file_id":"23",
                        "audio_file_description":"press-one-en.wav"
                     },
                     {
                        "language_id":"7",
                        "language_name":"French",
                        "audio_file_id":"24",
                        "audio_file_description":"press-one-fr.wav"
                     }
                  ]
               },
               "2":{
                  "choice":[
                     {
                        "language_id":"6",
                        "language_name":"English",
                        "audio_file_id":"25",
                        "audio_file_description":"voting-for-mno-en.wav"
                     }
                  ],
                  "option":[
                     {
                        "language_id":"6",
                        "language_name":"English",
                        "audio_file_id":"26",
                        "audio_file_description":"press-two-en.wav"
                     }
                  ]
               },
               "3":{
                  "choice":[
                     {
                        "language_id":"6",
                        "language_name":"English",
                        "audio_file_id":"27",
                        "audio_file_description":"voting-for-xyz-en.wav"
                     }
                  ],
                  "option":[
                     {
                        "language_id":"6",
                        "language_name":"English",
                        "audio_file_id":"28",
                        "audio_file_description":"press-three-en.wav"
                     }
                  ]
               }
            },
            "repeat_times":2,
            "branching_enabled":1,
            "audio_files":[
               {
                  "language_id":"6",
                  "language_name":"English",
                  "audio_file_id":"29",
                  "audio_file_description":"voting-for-who-question-en.wav"
               },
               {
                  "language_id":"7",
                  "language_name":"French",
                  "audio_file_id":"30",
                  "audio_file_description":"voting-for-who-question-fr.wav"
               }
            ],
            "connections_to_block":[
               "1368"
            ],
            "connections_from_block":[
               "1374"
            ]
         },
         {
            "id":"1374",
            "type":"Message",
            "num_outputs":"1",
            "is_interactive":0,
            "title":"Thank you",
            "repeat_enabled":0,
            "audio_files":[
               {
                  "language_id":"6",
                  "language_name":"English",
                  "audio_file_id":"31",
                  "audio_file_description":"thankyou-en.wav"
               }
            ],
            "sms_content":[
               {
                  "language_id":"6",
                  "language_name":"English",
                  "sms_content":"Thank you"
               }
            ],
            "connections_to_block":[
               "1372",
               "1373"
            ],
            "connections_from_block":[

            ]
         }
      ]
   },
   "message":"Tree 7 and block details fetched successfully",
   "more_info":"",
   "pagination":null,
   "url":"https://192.168.3.5/api/v1/trees/7/blocks?api_key=125d50ceb4e4e2186cf47e3c3"
}

Get Tree Block Details

Method: GET

URL: https://go.votomobile.org/api/v1/trees/[tree_id]/blocks/[block_id]

Parameters:

  • api_key

Returns:

{
   "status":200,
   "code":1000,
   "data":{
      "tree":[
         {
            "id":"7",
            "starting_block_id":"1366",
            "num_blocks":"16"
         }
      ],
      "blocks":[
         {
            "id":"1360",
            "type":"Multiple Choice Question",
            "num_outputs":"4",
            "is_interactive":1,
            "title":"Are you a registered voter?",
            "choices":[
               "Yes",
               "No",
               "Maybe",
               "Not Interested"
            ],
            "choices_key_press_options":{
               "1":"1",
               "2":"2",
               "3":"3",
               "4":"*"
            },
            "choices_sms_response_options":{
               "1":[
                  "1",
                  "yes"
               ],
               "2":[
                  "2",
                  "no"
               ],
               "3":[
                  "3",
                  "maybe"
               ],
               "4":[
                  "*",
                  "not interested"
               ]
            },
            "repeat_times":2,
            "branching_enabled":1,
            "audio_files":[
               {
                  "language_id":"6",
                  "language_name":"English",
                  "audio_file_id":"16",
                  "audio_file_description":"voter-question-en.wav"
               },
               {
                  "language_id":"7",
                  "language_name":"French",
                  "audio_file_id":"17",
                  "audio_file_description":"voter-question-fr.wav"
               },
               {
                  "language_id":"8",
                  "language_name":"Pidgin",
                  "audio_file_id":"18",
                  "audio_file_description":"voter-question-pdg.wav"
               }
            ],
            "sms_content":[
               {
                  "language_id":"6",
                  "language_name":"English",
                  "sms_content":"Are you a registered voter? Reply 1 for Yes, 2 for No, 3 for Maybe, 4 for Not Interested."
               },
               {
                  "language_id":"7",
                  "language_name":"French",
                  "sms_content":"Êtes-vous un électeur inscrit? Répondre 1 pour Oui , 2 pour Non, 3 pour Peut-être , pour 4 Pas intéressé."
               },
               {
                  "language_id":"10",
                  "language_name":"Pidgin",
                  "sms_content":"You don put your name down as person wey fit vote? Press 1 for Yes, 2 say No, 3 say e be like so, 4 say you e no concern you."
               }
            ],
            "connections_to_block":[
               "1366",
               "1359",
               "1368"
            ],
            "connections_from_block":[
               "1359",
               "1361",
               "1362"
            ]
         }
      ]
   },
   "message":"Tree 7 and details for Block 1360 fetched successfully",
   "more_info":"",
   "pagination":null,
   "url":"https://192.168.3.5/api/v1/trees/7/blocks/1360?api_key=125d50ceb4e4e2186cf47e3c3"
}