Forms

We thought that sometimes, all you want to do is collect responses. For instance, collecting attendance, running a survey, etc. USSDK offers a way to do this and track the responses from the dashboard.

Forms are useful when you don't need to call your own API just to save simple responses. You define the questions in your USSD flow, tell USSDK which answers should be saved, and then use the @ussdk/forms hook to store them.

Creating a form

How do you do this? In just two easy steps:

1. Make sure you set keys for steps that you want to save responses for.
2. On the step where you want the response saved, set the hook as @ussdk/forms/wedding_rsvp.

In the example above, wedding_rsvp is the name of the form. You can choose any name that helps you identify the responses later.

By just doing this, USSDK creates a table you can access from the app's Forms page. This table will be populated with values entered for steps that have their key set.

Example

Let's say you want to collect responses for a wedding RSVP.

You may have these steps:

On the final step, set the hook to:

@ussdk/forms/wedding_rsvp

When a user completes the flow, USSDK saves the values like this:

{
  "name": "Ama",
  "attendance": "yes",
  "guests": "2"
}

The submission also includes the user's phone number and the date the response was saved.

Where to add the forms hook

Add the @ussdk/forms/form_name hook on the step where you want the responses to be saved.

In most cases, this should be the last step of the flow. This ensures that the user has answered all the questions before USSDK saves the submission.

For example:

Thank you for registering.

Hook:

@ussdk/forms/event_registration

When this step is reached, USSDK collects all the values saved so far in the session and stores them in the event_registration form.

What gets saved?

USSDK saves values from steps that have a key.

If a step does not have a key, the user's response on that step will not be saved to the form.

For example, if your flow has these keys:

name
email
region

Your form table will have columns for name, email, and region.

USSDK also saves:

• Date
• Phone number

The phone number is the msisdn from the USSD session.

Viewing submissions

After responses are submitted, go to the app's Forms page. You will see the forms that have records.

Select a form to view its submissions. Each row represents one saved USSD session response.

From there, you can also export the form as CSV. The exported file includes:

• Date
• Phone number
• All saved keys from the submissions

Naming forms

The form name comes from the hook URL:

@ussdk/forms/form_name

Use simple names that describe what you're collecting. For example:

@ussdk/forms/wedding_rsvp
@ussdk/forms/event_registration
@ussdk/forms/customer_feedback

If the form does not exist yet, USSDK creates it when the first submission is saved.

When to use forms

Use forms when you simply want to collect and view responses in USSDK.

Forms work well for:

• Attendance
• Surveys
• Registrations
• Feedback
• Simple reports

If you need to validate input, call an external service, send an SMS, or save data in your own database, use a custom hook instead.

Summary

In summary:

1. Add keys to the steps you want to save.
2. Add @ussdk/forms/form_name as the hook on the step where the response should be saved.
3. Let users complete the flow.
4. View and export submissions from the app's Forms page.