RESTful API

Android App Registration

Overview

Push Notifications are messages sent from the Campaign Manager tool to user's smartphones. Clients need an Android App registered to the Campaign Manager to handle the message.

You could request our home brewed Android App if you don't have one

URL

Parameters on the following URL are inside braces { }

{base_url}/rest/api/tools/registerPushAndroidApp/{instanceId}/{appName}/{apiKey}/{redirectURL}/{publicKey}/{signature}
Parameter Name Description
instanceId An instance id is the workspace identification number, if you don't know yours please request it using our ticketing tool, you will need to provide your Mobile Engagement Campaign Manager's URL and your user login
appName Your Android App's name which will receive your Push Notifications. This parameter must be Base64 encoded.
apiKey Required when sending to Android devices. The API Key generated from Google APIs console page.
redirectURL The URL that users will be redirected after registration finished. This parameter must be Base64 encoded.
publicKey The public key to access this API. if you don't know yours please request it using our ticketing tool, you will need to provide your Mobile Engagement Campaign Manager's URL and your user login
signature The unique SHA256 signature for this call, it's involve all input parameters. To learn about generating the correct signature please visit our Java Example

Response

The Response XML is divided in a static part and a dynamic one, we call it dynamic because it will vary depending on the method you invoke. Please read our Response XML Basics section if you want to learn more about the response parts.

<input>registerPushAndroidApp</input>
<status>OK</status>
<description>Completed</description>
<result>
	<transactionResult> 
		<successful>true</successful>
		<message>Successful registration</message>
	</transactionResult>
</result>
Result parameters
Parameter Name Description Possible Values
successful Indicates if the registration was successful or not true
false
message A human readable explanation Text

Android Device Registration

Overview

Once you have your registered Android App you need to implement the device registration process. This process will connect your audience to your Push Channel once completed.

To receive Push Notifications using the Android's Platform your app must be registered to the Google Cloud Messaging.

You can complete this process completely by using this method from within your App.

Please be aware that your App just need to do those registrations once per installation, consider this when implementing.

We recommend to combine the Google Cloud Messaging registration and this device registration into a single process and shows it as a lobby page on your App, this lobby page just appear once per installation.

URL

Parameters on the following URL are inside braces { }

{base_url}/rest/api/tools/registerPushAndroidDevice/{instanceId}/{deviceId}/{appName}/{registrationId}/{publicKey}/{signature}
Parameter Name Description
instanceId An instance id is the workspace identification number, if you don't know yours please request it using our ticketing tool, you will need to provide your Mobile Engagement Campaign Manager's URL and your user login
deviceId The device unique identifier, On Android devices please use the phone IMEI. You can request it through the TelephonyManager
appName Your Android App's name which will receive your Push Notifications
registrationId This is your device ID on Google Cloud Messaging, this documentation will help you to get the registration id needed at this point
publicKey The public key to access this API. if you don't know yours please request it using our ticketing tool, you will need to provide your Mobile Engagement Campaign Manager's URL and your user login
signature The unique SHA256 signature for this call, it's involve all input parameters. To learn about generating the correct signature please visit our Java Example

Response

The Response XML is divided in a static part and a dynamic one, we call it dynamic because it will vary depending on the method you invoke. Please read our Response XML Basics section if you want to learn more about the response parts.

<input>registerPushAndroidDevice</input>
<status>OK</status>
<description>Completed</description>
<result>
	<transactionResult> 
		<successful>true</successful>
		<message>Successful registration</message>
	</transactionResult>
</result>
Result parameters
Parameter Name Description Possible Values
successful Indicates if the registration was successful or not true
false
message A human readable explanation Text

iOS App Registration

Overview

Push Notifications are messages sent from the Campaign Manager tool to user's smartphones. Clients need an iOS App registered to the Campaign Manager to handle the message.

When using iOS apps to receive Push Notifications you will need to use the Apple Push Notification System (APNs), when you do you will get a certificate that validates against Apple that is you who sending the message.

You must upload your certificate into the Campaign Manager to make it able to send your messages, please use our upload tool for this operation

You could request our home brewed iOS App if you don't have one

URL

Parameters on the following URL are inside braces { }

{base_url}/rest/api/tools/registerPushIosApp/{instanceId}/{appName}/{redirectURL}/{publicKey}/{signature}
Parameter Name Description
instanceId An instance id is the workspace identification number, if you don't know yours please request it using our ticketing tool, you will need to provide your Mobile Engagement Campaign Manager's URL and your user login
appName Your iOS App's name which will receive your Push Notifications. This parameter must be Base64 encoded.
redirectURL The URL that users will be redirected to from Facebook after registration finished. This parameter must be Base64 encoded.
publicKey The public key to access this API. if you don't know yours please request it using our ticketing tool, you will need to provide your Mobile Engagement Campaign Manager's URL and your user login
signature The unique SHA256 signature for this call, it's involve all input parameters. To learn about generating the correct signature please visit our Java Example

Response

The Response XML is divided in a static part and a dynamic one, we call it dynamic because it will vary depending on the method you invoke. Please read our Response XML Basics section if you want to learn more about the response parts.

<input>registerPushIosApp</input>
<status>OK</status>
<description>Completed</description>
<result>
	<transactionResult> 
		<successful>true</successful>
		<message>Successful registration</message>
	</transactionResult>
</result>
Result parameters
Parameter Name Description Possible Values
successful Indicates if the registration was successful or not true
false
message A human readable explanation Text

iOS Device Registration

Overview

Once you have your registered iOS App you need to implement the device registration process. This process will connect your audience to your Push Channel (APNs) once completed.

You can complete this process completely by using this method from within your App.

Please be aware that your App just need to do this registration once per installation, consider this when implementing.

We recommend show this registration process as a lobby page on your App, this lobby page just appear once per installation.

URL

Parameters on the following URL are inside braces { }

{base_url}/rest/api/tools/registerPushIosDevice/{instanceId}/{deviceId}/{appName}/{deviceToken}/{publicKey}/{signature}
Parameter Name Description
instanceId An instance id is the workspace identification number, if you don't know yours please request it using our ticketing tool, you will need to provide your Mobile Engagement Campaign Manager's URL and your user login
deviceId The device unique identifier, On iOS devices you will use the UUID, You can obtain this information through the UIDevice class
appName Your Android App's name which will receive your Push Notifications
deviceToken This is your device ID on the APNs, this documentation will help you to get the registration id needed at this point
publicKey The public key to access this API. if you don't know yours please request it using our ticketing tool, you will need to provide your Mobile Engagement Campaign Manager's URL and your user login
signature The unique SHA256 signature for this call, it's involve all input parameters. To learn about generating the correct signature please visit our Java Example

Response

The Response XML is divided in a static part and a dynamic one, we call it dynamic because it will vary depending on the method you invoke. Please read our Response XML Basics section if you want to learn more about the response parts.

<input>registerPushIosDevice</input>
<status>OK</status>
<description>Completed</description>
<result>
	<transactionResult> 
		<successful>true</successful>
		<message>Successful registration</message>
	</transactionResult>
</result>
Result parameters
Parameter Name Description Possible Values
successful Indicates if the registration was successful or not true
false
message A human readable explanation Text

Mobile Phone Registration

Overview

You also could associate a registered device (Android, iOS) with a phone number in order to send push notifications to a device using a phone number rather than a device ID. Once the phone number is associated with a registered device, Messangi will send a SMS with a validation code to the phone number.

This is extremely useful when you need to keep it simple, because it allows you to broadcast your messages using regular mobile number lists rather than devices id list

If you want to use this mechanism we recommend you to combine it in your lobby page since you just need to do this one time.

Also, remember that you will need the SMS validation code to activate the mobile phone number.

URL

Parameters on the following URL are inside braces { }

{base_url}/rest/api/tools/registerPushPhone/{instanceId}/{deviceId}/{appName}/{platform}/{mobileNumber}/{publicKey}/{signature}
Parameter Name Description
instanceId An instance id is the workspace identification number, if you don't know yours please request it using our ticketing tool, you will need to provide your Mobile Engagement Campaign Manager's URL and your user login
deviceId The device unique identifier, remember this id will vary if the target device is Android or iOS
appName Your Android App's name which will receive your Push Notifications
platform The target platform for the push service. Valid values are: ANDROID or IOS
mobileNumber UserĀ“s mobile number
publicKey The public key to access this API. if you don't know yours please request it using our ticketing tool, you will need to provide your Mobile Engagement Campaign Manager's URL and your user login
signature The unique SHA256 signature for this call, it's involve all input parameters. To learn about generating the correct signature please visit our Java Example

Response

The Response XML is divided in a static part and a dynamic one, we call it dynamic because it will vary depending on the method you invoke. Please read our Response XML Basics section if you want to learn more about the response parts.

<input>registerPushPhone</input>
<status>OK</status>
<description>Completed</description>
<result>
	<transactionResult> 
		<successful>true</successful>
		<message>Successful registration</message>
	</transactionResult>
</result>
Result parameters
Parameter Name Description Possible Values
successful Indicates if the registration was successful or not true
false
message A human readable explanation Text

Mobile Phone Activation

Overview

Once the device receives the SMS with the validation code, this function allows sending the code in order to validate if the provided phone number is valid.

Remember to add a two minutes pause to your lobby screen when the users enter his mobile phone and request the validation code so the user can wait for it with some progress bar or any other kind of notice.

URL

Parameters on the following URL are inside braces { }

{base_url}/rest/api/tools/activateRegisterPushPhone/{instanceId}/{deviceId}/{appName}/{platform}/{activationCode}/{publicKey}/{signature}
Parameter Name Description
instanceId An instance id is the workspace identification number, if you don't know yours please request it using our ticketing tool, you will need to provide your Mobile Engagement Campaign Manager's URL and your user login
deviceId The device unique identifier, remember this id will vary if the target device is Android or iOS
appName Your Android App's name which will receive your Push Notifications
platform The target platform for the push service. Valid values are: ANDROID or IOS
activationCode The activation code must arrive as a SMS after the registration request
publicKey The public key to access this API. if you don't know yours please request it using our ticketing tool, you will need to provide your Mobile Engagement Campaign Manager's URL and your user login
signature The unique SHA256 signature for this call, it's involve all input parameters. To learn about generating the correct signature please visit our Java Example

Response

The Response XML is divided in a static part and a dynamic one, we call it dynamic because it will vary depending on the method you invoke. Please read our Response XML Basics section if you want to learn more about the response parts.

<input>activateRegisterPushPhone</input>
<status>OK</status>
<description>Completed</description>
<result>
	<transactionResult> 
		<successful>true</successful>
		<message>Successful registration</message>
	</transactionResult>
</result>
Result parameters
Parameter Name Description Possible Values
successful Indicates if the registration was successful or not true
false
message A human readable explanation Text