Setup

  • Run the following command to install
pip install ussd_airflow
  • Add ussd_airflow in Installed application

    INSTALLED_APPS = [
    'ussd.apps.UssdConfig',
    ]
    
  • Change session serializer to pickle serializer

    SESSION_SERIALIZER = 'django.contrib.sessions.serializers.PickleSerializer'
    
  • Add ussd view to handle ussd request.
    • To use an existing ussd view that is implemented to handle AfricasTalking ussd gateway

      from ussd.views import AfricasTalkingUssdGateway
      
      urlpatterns = [
          url(r'^africastalking_gateway',
              AfricasTalkingUssdGateway.as_view(),
              name='africastalking_url')
          ]
      

      To use the existing Africastalking ussd gateway and your own ussd screen. Create a yaml file. On the yaml create your ussd screen. Learn more on how to create ussd screen here Creating ussd screens. For quick start copy the below yaml

      initial_screen: enter_name
      
      enter_name:
        type: input_screen
        text: Enter your name
        input_identifier: name
        next_screen: enter_age
      
      enter_age:
        type: input_screen
        text: Enter your age
        input_identifier: age
        next_screen: show_details
      
      show_details:
        type: quit_screen
        text: You have entered name as {{name}} and age as {{age}}
      

      Next step add this to your settings. For ussd airflow to know where your ussd screens files are located.

      DEFAULT_USSD_SCREEN_JOURNEY = "/file/path/of/the/screen"
      

      To validate your ussd screen file. Run this command

      python manage.py validate_ussd_journey /file/path
      

      To test the ussd view do this curl request.

      curl -X POST -H "Content-Type: application/json"
      -H "Cache-Control: no-cache"
      -H "Postman-Token: 3e3f3fb9-99b9-b47d-a358-618900d486c6"
      -d '{"phoneNumber": "400","sessionId": "105","text":"1",
      "serviceCode": "312"}'
      "http://{your_host}/{you_path}/africastalking_gateway"
      
    • To create your own Ussd View.
      class ussd.core.UssdView(**kwargs)[source]
      To create Ussd View requires the following things:
      • Inherit from UssdView (Mandatory)
        from ussd.core import UssdView
        
      • Define Http method either get or post (Mandatory)

        The http method should return Ussd Request

        class UssdRequest(session_id, phone_number, ussd_input, language, default_language=None, use_built_in_session_management=False, expiry=180, **kwargs)
        Parameters:
        • session_id

          used to get session or create session if does not exits.

          If session is less than 8 we add s to make the session equal to 8

        • phone_number – This the user identifier
        • input – This ussd input the user has entered.
        • language – Language to use to display ussd
        • kwargs

          Extra arguments. All the extra arguments will be set to the self attribute

          For instance:

          from ussd.core import UssdRequest
          
          ussdRequest = UssdRequest(
              '12345678', '702729654', '1', 'en',
              name='mwas'
          )
          
          # accessing kwarg argument
          ussdRequest.name
          
      • define this varialbe customer_journey_conf

        This is the path of the file that has ussd screens If you want your file to be dynamic implement the following method get_customer_journey_conf it will be called by request object

      • define this variable customer_journey_namespace

        Ussd_airflow uses this namespace to save the customer journey content in memory. If you want customer_journey_namespace to be dynamic implement this method get_customer_journey_namespace it will be called with request object

      • override HttpResponse

        In ussd airflow the http method return UssdRequest object not Http response. Then ussd view gets UssdResponse object and convert it to HttpResponse. The default HttpResponse returned is a normal HttpResponse with body being ussd text

        To override HttpResponse returned define this method. ussd_response_handler it will be called with UssdResponse object.

        class ussd.core.UssdResponse(text, status=True, session=None)[source]
        Parameters:
        • text – This is the ussd text to display to the user
        • status

          This shows the status of ussd session.

          True -> to continue with the session

          False -> to end the session

        • session – This is the session object of the ussd session

      Example of Ussd view

      from ussd.core import UssdView, UssdRequest
      
      
      class SampleOne(UssdView):
      
          def get(self, req):
              return UssdRequest(
                  phone_number=req.data['phoneNumber'].strip('+'),
                  session_id=req.data['sessionId'],
                  ussd_input=text,
                  service_code=req.data['serviceCode'],
                  language=req.data.get('language', 'en')
              )
      

      Example of Ussd View that defines its own HttpResponse.

      from ussd.core import UssdView, UssdRequest
      
      
      class SampleOne(UssdView):
      
          def get(self, req):
              return UssdRequest(
                  phone_number=req.data['phoneNumber'].strip('+'),
                  session_id=req.data['sessionId'],
                  ussd_input=text,
                  service_code=req.data['serviceCode'],
                  language=req.data.get('language', 'en')
              )
      
          def ussd_response_handler(self, ussd_response):
                  if ussd_response.status:
                      res = 'CON' + ' ' + str(ussd_response)
                      response = HttpResponse(res)
                  else:
                      res = 'END' + ' ' + str(ussd_response)
                      response = HttpResponse(res)
                  return response