Skip to main content

WAP API guide

Overview

In general, WAP services behave in a similar manner to USSD services, with the key difference of being viewed through the web browser instead of a USSD screen. WAP services unlike USSD ones do not support redirects.

WAP applications have following properties:

  • id - the application's identifier
  • appUrl - the application's address to which session events will be sent to
  • configurable default process
  • customizable SMS message format to start the session with
  • public application address that the user interacts with in their browser

Implementing a WAP API service

New session initiated by WAP push

WAP sessions can be initiated by pushes, which send an SMS message to the client with a link to start the session. In order to initiate a WAP session, one should call the following endpoint:

POST https://deep.qrios.com/api/wap/app/push

Headers:
  X-Client-Id: x97uJ23b
  X-Client-Secret: [secret]

{
  "appId": "a12u3ui",
  "customerMsisdn": "2341234512345",
  "process": {
    "id": "menu",
    "params": {
      "channel": "WAP"
    }
  }
}

What does the request contain?

  • X-Client-Id header - the developer's identifier in Qrios API
  • X-Client-Secret header - the developer's authorization secret (generated together with developer's identifier during an onboarding process)
  • appId - the developer's WAP application identifier
  • customerMsisdn - the MSISDN of customer who is going to receive the push message
  • process - custom process to start the session with instead of default one (can be omitted)

The response will be as follows:

HTTP 200 (OK)
{
  "message": "Session initiated with id de6da59a-79fb-4559-bceb-8f67f23ce14c",
  "sessionId": "de6da59a-79fb-4559-bceb-8f67f23ce14c",
  "status": "OK"
}

The customer will receive an SMS with a URL allowing them to start a WAP session. When the customer enters the link, he will start the session in a browser and the developer will receive /ussdSessionEvent/new request

POST https://example-developer-wap-app.com/ussdSessionEvent/new
Headers:
  Authorization: e7457445-1998-4846-9254-117dd5eb122d
  
{
  "clientId": "x97uJ23b",
  "appId": "a12u3ui",
  "sessionId": "de6da59a-79fb-4559-bceb-8f67f23ce14c",
  "msisdn": "2341234512345",
  "operator": "mtn",
  "input": {
    "processId": "menu",
    "process": {
      "id": "menu",
      "params": {
        "channel": "WAP"
      }
    },
    "type": "Redirect"
  }
}

What we have here:

  • https://example-developer-wap-app.com - developer's wap app address
  • Authorization (header) - the authorization secret value according to the configured authorization method of the WAP app
  • clientId - a developer's profile identifier
  • appId - a developer's WAP application identifier on Qrios platform
  • sessionId - a unique identifier of current WAP session (it stays unchanged from the beginning of the session to its end)
  • msisdn - a customer phone number
  • operator - a network operator of customer's phone number
  • input - this field contains an input with type redirect, with optional process definition

When the developer's application receives request like the one above, it's required to handle it and return a response with instructions what Qrios platform should send to the customer. The response can look like this:

  1. First option - InputView
HTTP 200 (OK)
{
  "action": {
    "type": "ShowView",
    "view": {
      "type": "InputView",
      "message": "Hello world! Please enter your name:"
    }
  },
  "contextData": "devCorrelationId:12345"
}

What does the response mean? Here, we'd like to instruct Qrios Platform to:

  • send user a message ("type": "ShowView") - the message content is defined in "message": "Hello world! Please enter your name:"
  • wait for user input and then continue WAP session ("type": "InputView")
  • pass on developer's data, which will be shipped with next request ("contextData": "devCorrelationId:12345")

The customer, on his phone, should be able to see the response in formatted like this: Hello world! Please enter your name:

Moreover, he will be able to continue WAP session by providing further input and hitting submit button.

  1. Second option - ChooserView
HTTP 200 (OK)
{
  "action": {
    "view": {
      "type": "ChooserView",
      "title": "Select one of the account numbers:",
      "items": [
        {
          "accessKey": "1",
          "label": "1230000123"
        },
        {
          "accessKey": "2",
          "label": "4560000456"
        },
        {
          "accessKey": "3",
          "label": "9999999999"
        }
      ]
    },
    "type": "ShowView"
  },
  "contextData": "devCorrelationId:12345"
}

What does the response mean? Here, we'd like to instruct Qrios Platform to:

  • send user a message ("type": "ShowView") that will be displayed as a chooser menu (ChooserView)
Select one of the account numbers:
1230000123
4560000456
9999999999
  • the title field is a text that will be displayed at the beginning, before the chooser items (here it is Select one of the account numbers:)
  • the items field is a list of chooser items, there must be at least one chooser item,
  • each of the items must contain:
    • accessKey field - selected items will be identified using this value, accessKey's must be unique
    • label field - the description of the item, as shown in the example above
  • the customer must choose one of the chooser items - by providing text input equal to one of the accessKey's
  • if the customer provides some invalid input (not corresponding to any of the chooser items), then Qrios platform will ask the customer to retry
  • the input retries will be handled internally by the Qrios platform, without sending any requests to the developer's app
  • developer's app will receive the user input - the accessKey of the selected chooser item
  • pass on developer's data, which will be shipped with next request ("contextData": "devCorrelationId:12345")

Continue existing session

Let's assume that the customer wants to continue the session. He enters: Kelechi Iheanacho and hits submit button. This is what is going to be sent to the developer's application:

POST https://example-developer-wap-app.com/ussdSessionEvent/continue
Headers:
  Authorization: e7457445-1998-4846-9254-117dd5eb122d

{
  "clientId": "x97uJ23b",
  "appId": "a12u3ui",
  "sessionId": "de6da59a-79fb-4559-bceb-8f67f23ce14c",
  "result": {
    "type": "InputResult",
    "value": "Kelechi Iheanacho"
  }
}

It will work very similarly if there was a ChooserView:

Select one of the account numbers:
1230000123
4560000456
9999999999

The options will be displayed as clickable links, and each selected option will be identified using its corresponding accessKey. This is what is going to be sent to the developer's application if the customer clicked on 4560000456, with its accessKey being 2:

POST https://example-developer-wap-app.com/ussdSessionEvent/continue
Headers:
  Authorization: e7457445-1998-4846-9254-117dd5eb122d

{
  "clientId": "x97uJ23b",
  "appId": "a12u3ui",
  "sessionId": "de6da59a-79fb-4559-bceb-8f67f23ce14c",
  "result": {
    "type": "InputResult",
    "value": "2"
  }
}

As we can see, the request is a little bit different, than the one we saw in context of the new session. Here we also see sessionId parameter and its value is the same as on new session. Input type is InputResult, which means that under value field we should expect string entered by the customer.

Also here, the developer's application is expected to handle it and send a response. The response format is the same as for the new session request. But let's see another example of it:

HTTP 200 (OK)
{
  "action": {
    "type": "ShowView",
    "view": {
      "type": "InfoView",
      "message": "Welome Kelechi Iheanacho! You rocks!!!"
    }
  },
  "contextData": "devCorrelationId:12345"
}

It looks almost the same with one exception - "type": "InfoView". It means that WAP application doesn't expect customer to provide further input. There will be no other interaction with the customer within current (de6da59a-79fb-4559-bceb-8f67f23ce14c) session and the session is going to be closed.

Closing session

In the last response our example WAP application, Qrios platform was instructed to send Welome Kelechi Iheanacho! You rocks!!! to the customer with expectation of no further interaction. Qrios platform sends the message and then closes the de6da59a-79fb-4559-bceb-8f67f23ce14c session. The developer's application will be notified about the fact of session closing using request like below:

POST https://example-developer-wap-app.com/ussdSessionEvent/close
Headers:
  Authorization: e7457445-1998-4846-9254-117dd5eb122d

{
  "clientId": "x97uJ23b",
  "appId": "a12u3ui",
  "sessionId": "de6da59a-79fb-4559-bceb-8f67f23ce14c",
  "reason": {
    "type": "End"
  },
  "contextData": "devCorrelationId:12345"
}

There is no requirement for body response expected to be sent. Response to the request can look like this:

HTTP 204 (No content)

Field reason contains the type of session close. We can distinguish 2 types - different reasons of session closing:

  • End - it is sent when the session is closed naturally (there is no further customer input needed)
  • Timeout - duration of a WAP session is limited by a network operator. You should assume that after 2 minutes, a session will be forced to close by the operator.

Session aborting

In exceptional cases a session could be aborted. We distinguish following reasons of session aborting:

  • UnexpectedAppResponse - previous WAP app response was malformed or not expected
  • InternalError - there was some internal error in Qrios API or WAP app is not achievable or responded too long

In general, this request means that Qrios platform cannot continue the session any more, so it was exceptionally closed.

POST https://example-developer-wap-app.com/ussdSessionEvent/abort
Headers:
  Authorization: e7457445-1998-4846-9254-117dd5eb122d

{
  "clientId": "x97uJ23b",
  "appId": "a12u3ui",
  "sessionId": "de6da59a-79fb-4559-bceb-8f67f23ce14c",
  "reason": {
    "type": "UnexpectedAppResponse"
  },
  "contextData": "devCorrelationId:12345"
}

POST https://example-developer-wap-app.com/ussdSessionEvent/abort
Headers:
  Authorization: e7457445-1998-4846-9254-117dd5eb122d

{
  "clientId": "x97uJ23b",
  "appId": "a12u3ui",
  "sessionId": "de6da59a-79fb-4559-bceb-8f67f23ce14c",
  "reason": {
    "type": "InternalError"
  },
  "contextData": "devCorrelationId:12345"
}

Expected response:

HTTP 204 (No content)