One Off Service

One-off text messaging services

One-off text messaging services are by nature single transaction. A mobile consumer sends your application a text message and your application/service responds to it at a predefined monetary rate (Premium Rate). You are expected to offer content perceived as having the value for which you advertise your service to the mobile consumer. Abusing this trust will simply get you into trouble with carriers and will result in premature termination of your service.

Zong API (ZAPI) exposes this single transaction concept in the form of a URL which you provide (Transaction Handler) and we call using HTTP GET upon receiving an inbound text message destined to the shortcode and keyword of the markets in your service, this is a synchronous process. Browsing the API Doc you will see that we provide your transaction handler with a bunch of parameters which are intended to help your application specific business logic. Your application processes the request in a reasonable amount of time (30 to 45 seconds) and returns the response. Failing to respond in a reasonable amount of will result in ZAPI closing the socket and no text message returned to the mobile consumer however the message delivery process will be retried again as described here

Example flows for a one-off transaction

Below are a few example of possible flows. In this example, by US law, a double opt-in process is required. You don't need to implement it as we take care of it for you. Your transaction handler will get hit only once the user has responded to the first text message with a positive response. For countries not requiring a double opt-in process, it will be left out.

Weather Service @ USD 0.25

<- User sends the keyword WEATHER followed by Miami to the US shortcode 91010 (weather miami)

-> ZAPI replies to user: You have requested a onetime transaction for the Weather service at USD 0.25 Respond Y to receive this message. Send HELP to 91010 for info <- User responds with Y

Your transaction handler gets a hit and checks the weather in miami returning the following XML as the response

<?xml version="1.0" encoding="UTF-8"?>
<oneoff_response xmlns="https://api.zong.com/zapi/v1" reverse_charged="true" fragmentable="false">
    <text_content>The current weather in Miami is partly cloudy with a temperature of 80F. NE Winds @ 10mph</text_content>
</oneoff_response>

-> ZAPI sends a text message to the user "The current weather in Miami is partly cloudy with a temperature of 80F. NE Winds @ 10mph"

Horoscope service @ USD 0.50

<- User sends the keyword horoscope to the US shortcode 91010 (horoscope)

-> ZAPI replies to user: You have requested a onetime transaction for the Horoscope service at USD 0.50 Respond Y to receive this message. Send HELP to 91010 for info <- User responds with Y

Your transaction handler gets a hit and responds with the following XML (notice this message is sent at standard rate by setting reverse_charged="false")

<?xml version="1.0" encoding="UTF-8"?>
<oneoff_response xmlns="https://api.zong.com/zapi/v1" reverse_charged="false" fragmentable="false">
    <text_content>To complete your request, send birth date as ddMMyyyy to 91010. Example 05061970 for June 5 1970</text_content>
</oneoff_response>

<- User sends 13041971 to 91010

Your transaction handler gets a hit, gets the appropriate horoscope and responds with the following XML (notice this message is sent at premium rate by setting reverse_charged="true")

<?xml version="1.0" encoding="UTF-8"?>
<oneoff_response xmlns="https://api.zong.com/zapi/v1" reverse_charged="true" fragmentable="false">
    <text_content>[Gemini] The dynamics of Mars give you energy to complete your projects on time</text_content>
</oneoff_response>