Documentation
Table of Contents
MNO Web Opt-in
Web Opt-in is practically a single-click opt-in, but it will ONLY work if the user is browsing via his/her mobile device while connected to the MNOs Mobile Data.
It will NOT work if the user is connected to the WiFi!
Mobivate currently provides the MNO Web Opt-In in the following regions
South Africa
Flow: Redirect the user to the Lookup URL. Once the lookup is performed, user will be sent back to your Return URL. Upon the return the user will already be subscribed to your service and you can start sending billed messages, but only if the status
variable is success
https://content.mobivate.com/lookup/za/ ?shortcode={shortcode}&service={keyword}={product_id}&freq={billing frequency} &campaign={campaign name}&amount={billing amount}&bl={brand logo} &bc={background color}&tc={text colour}&return={your return URL}
Required Parameters
Attribute | Sample Value | Description |
---|---|---|
shortcode | 30000 | Your associated shortcode |
service | apple=aaaabbbbcccccddddd | Keyword and the ProductID |
freq | 1-7,31 | 1 -7 messages per week, or if 31 then it's single monthly billing |
campaign | Our Games | Campaign Description |
amount | 10 | Amount of Rand (ZAR) billed per billing request |
bl | http://yourdomain/logo.png | Full URL to your Header Image |
bc | ffffff | HEX value for the background colour |
tc | 000000 | HEX value for the text colour |
return | http://yourdomain/returned | Return URL |
Return URL Parameters
Parameter | Description |
---|---|
status | MNO subscription status, either success or failed |
message | Any message passed through from the MNO |
userid | If the MSISDN was detected, the fully qualified MSISDN |
network | MNO identifier |
Example
http://yourdomain/returned?status=success&userid=277123456789&network=vodacomsa
Nigeria
User Detection & Subscription in Nigeria
To subscribe a user in Nigeria, for Direct Carrier Billing, we must perform two separate steps.
- Redirect the user to the MSISDN Detection platform which will return to us ( if successful ) the Network and the User ID.
- Call the Subscribe method on the API providing the UserID and the ServiceID.
Requesting the UserID
To request the UserID, you should have the following information ready:
Return URL
(Your FULL URL, including the http://... . User will be sent back to this url upon completion.)MTN Product ID
(required for detecting MTN customers)Your Reference ID
(optional)
Flow: Redirect the user to the Lookup URL. Once the lookup is performed, user will be sent back to your Return URL
https://content.mobivate.com/lookup/ng/?return={RETURN_URL}&ad_id={MTN_PRODUCT_ID}&ref_id={YOUR_REFERENCE}
The user will return to the given Return URL with the following (GET) parameters appended.
Attribute | Example | Description |
---|---|---|
status | success / failed | Describing the status of the lookup |
userid | abcd4321_-$ | Returned only if status==success! An ASCII value unique to this subscriber, instead of the MSISDN. |
network | mtnng / etisalatng | Returned only if status==success! Network name for the subscriber |
message | Returned only if status==failed! Error description |
Examples
On Successful detection user will return to your domain:
http://www.yourdomain.com/nigeria-user-detection?status=success&userid=$abcd1234$&network=etisalatng
On failure, the user will return to your domain while:
http://www.yourdomain.com/nigeria-user-detection?status=failed&message=Failed+to+detect+UserID.
Subscribing the User to the Service
Once you have the UserID you can request a subscription to your service. For this you can use our NetworkSubscription API. The User ID is normally the MSISDN number associated with the subscription.
For subscribing a MTN Customer request:
GET: https://content.mobivate.com/lookup/subscribe/mtnng/?userid={USERID}&keyword={PRODUCT_ID}
For subscribing an Etisalat Customer request:
GET: https://content.mobivate.com/lookup/subscribe/etisalatng/?userid={USERID}&keyword={PRODUCT_ID}
Where the required parameters are:
Parameter | Description |
---|---|
userid | The userid that was sent to your Return URL |
keyword | The ProductID that you wish to subscribe the user to. Bear in mind, if subscribing the user to MTNNG, you must use the same MTN_PRODUCT_ID as you did when requesting the USER ID |
The Response All requests will return HTTP Code 200 and a JSON body.
Examples
On Success:
{ subscribed: true, message: "Subscription request has been accepted!", code: 202 }
or on Failure:
{ subscribed: false, message: "Execution Error: Invalid Ad Id", code: 400 }
Unsubscribing user from the Service
Unsubscription works the same way the Subscription request does except the URL endpoint is slightly different.
For un-subscribing a MTN Customer request:
GET: https://content.mobivate.com/lookup/unsubscribe/mtnng/?userid={USERID}&keyword={PRODUCT_ID}
For un-subscribing a Etisalat Customer request:
GET: https://content.mobivate.com/lookup/unsubscribe/etisalatng/?userid={USERID}&keyword={PRODUCT_ID}
Error Codes
Code | Description |
---|---|
202 | Request has been accepted |
400 | Execution Error: … |
409 | Network Generated Error (custom message follows) |
417 | Invalid response received |
501 | Unknown network |
600 | Missing UserID or Keyword parameters |
601 | Request failed for unknown reason |
Delivery Notifications
On successfully billed request, a notification will be sent to your nominated URL.
Example
GET: http://www.yourdomain.com/nigeria-notifications?user-identity=$abcd1234$&service-id=xyz&status=1
Where the possible status codes are:
Status | Description |
---|---|
0 | New subscription started |
1 | Positive Billing |
2 | Failed Billing, Insufficient funds |
3 | Inactive Subscription, User opted out |
What If MNO web opt-in fails?
As previously mentioned:
“MNO web opt-in will only work if the user is browsing via his/her mobile device while connected to the MNOs Mobile Data. It will NOT work if the user is connected to the WiFi!”
But this does not mean that you cannot point a failed MNO opt-in to another opt-in flow. For example, it is recommended on failure to point a user to the NDOI opt-in flow.
On a failed MNO web opt-in the user will be returned to your return URL with the STATUS set to FAILED like below:
http://yourdomain/returned?status=failed&message=<Network Message>
Where “&message=” will explain the specific network error received. The server hosting your return URL must be able to redirect based on this “&status=failed” parameter.
You would then pass the parameters described in the section Network Double Opt-in (NDOI) to the NDOI endpoint. While also redirecting the user to your content page.