Registration process overview

This is a technical overview of the Uliza registration process.

Prerequisites

The following environment variables must be configured on the host system running the registration service:

• VOTO_API_KEY must be a valid API key.
• VOTO_API_URL must be set to https://go.votomobile.org/api/v1.
• ULIZA_API_URL must point to the Uliza API root URL (e.g., http://dev.uliza.fm/api/v1).

These optional variables can also be defined to override the default settings:

• CALL_SCHEDULE_OFFSET: Time to wait (in seconds) before scheduling a registration call (default: 600)
• MIN_RESCHEDULE_DELAY: Minimum time (in seconds) that must elapse between registration calls (default: 172800)

1. Survey-Tree association

For a registration call to be scheduled when a participant responds to a VOTO survey question, the survey must be associated with the registration tree in the Uliza system. There are currently two ways to achieve this:

• Recommended option: Append a tree_id query parameter to the webhook URL when configuring the survey from VOTO. This is explained under Response webhook.
• Follow the instructions on Survey‐Tree association to permanently associate a VOTO survey with a registration tree in the Uliza system.

2. Survey response

The Uliza registration process is triggered by a VOTO survey response.

3. Response webhook

A VOTO survey must be configured to send webhooks to the registration service. First construct an URL in the following format:

http://{__REG_SERVICE__}/responses?tree_id=<tree_id>

Substitute the actual VOTO tree id for <tree_id>. (This parameter is not required if you have previously associated the survey with a registration tree, following the steps described under Response webhook.)

Open the survey in VOTO, and under "Advanced Options":

• Enter the created URL in the webhook "Destination" field, and
• Select POST in the "Method" drop-down.

Alternatively, if the survey is scheduled programmatically, this can be given as the webhook_url and webhook_method parameters.

curl \
  -X POST \
  -F "api_key=xxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -F "survey_id=xx" \
  -F "send_to_phones=xxxxxxxxxxxx" \
  -F "webhook_url=http://dev.uliza.fm/responses?tree_id=xxxxx" \
  -F 'webhook_method=POST' \
  https://go.votomobile.org/api/v1/outgoing_calls

4. Create participant

When VOTO receives a response, a webhook is sent to the registration middleware. If a participant matching the subscriber from whom the response originates doesn't already exist in Uliza, one is first created. (A participant is identified by their phone number) New participants will have their registration status set to 'NOT_REGISTERED'. A voto_webhook_log entry is created in the database for all incoming webhooks (independent of the result of processing the request).

5. Create registration call

The system determines if a registration call should be scheduled based on the following criteria:

• Is the participant already registered?
• Has the participant previously declined to register with the service?
• Is a registration call already due for the participant?
• Did a call to the participant take place recently (see below for exact meaning)?

For a new call to be created in Uliza, the answer to all these questions must be negative. The time required between registration calls is determined by the MIN_RESCHEDULE_DELAY environment variable. This value is given in seconds. If this variable is not set, a default value of 172800 seconds (i.e., 48 hours) will be used.

6. Schedule call

Next, if a call is created in step 5, a VOTO API request is made to schedule the call.

7. Call status updates

Webhooks are not available for trees in VOTO, so instead the middleware must listen for status updates for the call itself. (The endpoint responsible for this is passed along with the request to schedule the call.)

8. Register participant

Throughout the call lifecycle, status updates are sent to the call_status_updates endpoint, exposed by the registration service. These messages contain a delivery status code (documented here). The system will wait for a notification that the subscriber hung up the call (status code 6), and subsequently:

• Update the participant with the attributes captured during the registration call.
• Set the participant's registration status to 'REGISTERED'.
• Retrieve the tree response log from VOTO and store this as a JSON blob with the registration call in Uliza.