Integration with your server
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 just select ‘Proxy Campaign’ from the ‘Campaign Type’ drop-down menu on the ‘New Campaign’ modal window. This will reveal a new text field for you to paste in the URL that must be called when a new USSD session is started.
What this will do is, when a 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
Formats
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 selected ‘Text from URL’ as a response type for error text on a node
- You have created actions on a node with the type of ‘HTTP Request’ on your node
Text from URL request
When you have selected text from 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 outIf 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 URL request.
HTTP Request action
This request is the same structure as a standard Text from URL request.
| 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_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. |