Integration with your server

Introduction

Panacea Mobile’s USSD gateway also allows you to fetch plain text from a web address and display it to a user when they dial your USSD string. User responses can also be pushed back to this address and fetch new text to display, effectively giving you complete control of the campaign/service from your own server. This is called a Proxy Campaign.

Setting up a Proxy Campaign

When setting up a new USSD campaign from your Panacea Mobile Account Dashboard, select Proxy Campaign from the Campaign Type drop-down menu on the New Campaign modal window. This will reveal a new text field to paste the URL that must be called when a new USSD session is started.

What this will do is, when users enter that node, the text they see will be provided by your server, and when they respond there will be no response matched and call your server for the ‘error’ text, essentially creating a proxy. Once you are ready to end the session with the user you will need to include the header in your response headers:

X-ussd-close: 1

Our service will then close the session with the user and allow no further responses.

HTTP Requests

Panacea Mobile’s USSD service can make HTTP requests to your own server to fetch plain text to display on a node in the following scenarios:

  • You have selected 'Text from URL' as a response type on a node

  • You have chosen 'Text from URL' as a response type for error text on a node

  • You have created actions of 'HTTP Request' on your node

Text from URL Request

When you have selected text from the URL as a response type, the Panacea Mobile USSD service will connect to your server to determine what content to show the user.

The request will contain the following data in the query string.

Variable
Type
Description

ussd_msisdn

String

This is the phone number of the user, in international format, eg: 27831234567

ussd_session_id

String

This is the unique session ID for the current user session. This will be the same for multiple requests (if applicable). Allowing upstream applications to have context as to where the users are.

ussd_request

String

This is what the user input was. If it was the start of the session it would be the string (eg: *100*123#). If it was a response it will be their response. ussd_type – integer This is the type of request. Types are:

1 = New session starting

2 = User response

3 = User closed session

4 = Session timed out.

If the user closes the session or the session times out, the last active node will be called (if it is/was a response URL type).

ussd_node_id

Integer

This is the unique node ID that is currently being processed.

ussd_node_name

String

This is the given node name that is currently being processed.

ussd_response_{NodeName}

String

All previous responses will be added to the URL string with the name of the relevant node. For example if a node named ‘User Gender’ was responded to with ‘Male’ in a session, it would be included in the URL query string as ‘&ussd_response_User_Gender=Male’. This is not just the last node but all responses in the session.

Error text from URL Request

This request is the same structure as a standard Text from a URL request.

HTTP Request action

This request is the same structure as a standard Text from URL request.

Last updated