Documentation

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!

MNO Web OptIn Flow

Mobivate currently provides the MNO Web Opt-In in the following regions

South Africa

Nigeria


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

AttributeSample ValueDescription
shortcode30000Your associated shortcode
serviceapple=aaaabbbbcccccdddddKeyword and the ProductID
freq1-7,311-7 messages per week, or if 31 then it's single monthly billing
campaignOur GamesCampaign Description
amount10Amount of Rand (ZAR) billed per billing request
blhttp://yourdomain/logo.pngFull URL to your Header Image
bcffffffHEX value for the background colour
tc000000HEX value for the text colour
returnhttp://yourdomain/returnedReturn URL

Return URL Parameters

ParameterDescription
statusMNO subscription status, either success or failed
messageAny message passed through from the MNO
useridIf the MSISDN was detected, the fully qualified MSISDN
networkMNO 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.

  1. Redirect the user to the MSISDN Detection platform which will return to us ( if successful ) the Network and the User ID.
  2. 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.

AttributeExampleDescription
status success / failedDescribing 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 / etisalatngReturned 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:

ParameterDescription
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

CodeDescription
202Request has been accepted
400Execution Error: …
409Network Generated Error (custom message follows)
417Invalid response received
501Unknown network
600Missing UserID or Keyword parameters
601Request 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:

StatusDescription
0New subscription started
1Positive Billing
2Failed Billing, Insufficient funds
3Inactive 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.