RESTful API

Send SMS

Overview

Send a text message to a cell phone using its mobile number as target.

URL

Parameters on the following URL are inside braces { }

{base_url}/rest/api/tools/sendSMS/{instanceId}/{carrier}/{from}/{mobileNumber}/{text}/{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
carrier Mobile operator in which the user have his SIM card or contract
from Short or Long code that will be used to originate the SMS. If you don't have one assigned yet please contact our support team trough our ticketing tool to request one.
mobileNumber The target User's mobile phone number. This parameter must be Base64 encoded
text This is the content of the message. 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>sendSMS</input>
<status>OK</status>
<description>Completed</description>
<result>
	<messages>
		<message>
			<id>-8174720676710228700</id>
			<carrier>carrierName</carrier>
			<from>19893653744</from>
			<to>13056708084</to>
			<text>OGANGI TEST MESSAGE</text>
			<status>SENT_TO_CARRIER</status>
			<statusDescription>Sent to Carrier</statusDescription>
			<encoding>UTF-8</encoding>
			<date>2013-09-17T10:13:59.176-04:30</date>
			<timezone>America/Caracas</timezone>
			<clientId>As223sdadq8d8287v5v</clientId>
		</message>
	</messages>
</result>
Result parameters

Please be aware that the <message> tag and its content is a generic object and may apply to other responses in other methods.

Parameter Name Description Possible Values
message.id Unique identifier for the message created Text
message.carrierName The carrier name used for this delivery Text
message.from Who sent the message for PUSH, Application that sent the message
for SMS, Short/Long code which originated the message
for EMAIL, the email address which sent the message.
message.to Recipient for this message Any of the following:
deviceId
mobile number
email address
message.text Message's content Text
message.status Indicates the message's status at the origination moment See our Message's Status page
message.statusDescription A simple explanation about the message's status Text
message.encoding The charset encoding used for the message's text Valid encoding name
message.date Time mark at the origination moment A formatted date string: yyyy-MM-dd'T'HH:mm:ss.SSSZZ
For more information please review the pattern letters quick reference
message.timezone Timezone used Text
message.clientId The client identification (sender) Text

Send SMS (Campaign Manager)

Overview

Send a text message to a cell phone using its mobile number as target.

URL

Parameters on the following URL are inside braces { }

{base_url}/rest/api/sendMT/{instanceId}/{from}/{carrier}/{mobileNumber}/{text}/{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
from Short or Long code that will be used to originate the SMS. If you don't have one assigned yet please contact our support team trough our ticketing tool to request one.
carrier Mobile operator ID in which the user have his SIM card or contract.
Write null on this placeholder to let the CM look for a suitable carrier
mobileNumber The target User's mobile phone number
text This is the content of the message. 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>sendMT</input>
<status>OK</status>
<description>Completed</description>

Send SMS With Flags (Campaign Manager)

Overview

Send a text message to a cell phone using its mobile number as target.

URL

Parameters on the following URL are inside braces { }

{base_url}/rest/api/sendMT/{instanceId}/{from}/{carrier}/{mobileNumber}/{text}/{flags}/{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
from Short or Long code that will be used to originate the SMS. If you don't have one assigned yet please contact our support team trough our ticketing tool to request one.
carrier Mobile operator ID in which the user have his SIM card or contract.
Write null on this placeholder to let the CM look for a suitable carrier
mobileNumber The target User's mobile phone number
text This is the content of the message. This parameter must be Base64 encoded
flags Additional flags to be used by a backend job
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>sendMT</input>
<status>OK</status>
<description>Completed</description>

Generate Mobile PIN

Overview

Generates and send a PIN code to a mobile device via SMS.

Useful when a live validation is needed, user cases examples:

  • User own's the mobile number
  • ATM or any other delicate operation
  • Promo code

URL

Parameters on the following URL are inside braces { }

{base_url}/rest/api/tools/sendSMSPinMobileNumberConfirm/{instanceId}/{carrier}/{from}/{mobileNumber}/{text}/{length}/{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
carrier Mobile operator name (case sensitive) in which the user have his SIM card or contract
from Short or Long code that will be used to originate the SMS. If you don't have one assigned yet please contact our support team trough our ticketing tool to request one.
mobileNumber The target User's mobile phone number
text This is the content of the message. This parameter must be Base64 encoded
length PIN's length (how many characters long)
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>sendSMSPinMobileNumberConfirm</input>
<status>OK</status>
<description>Completed</description>
<result>
	<PinSMSConfirmation>
			<pin>846547</pin>
	</PinSMSConfirmation>
</result>
Result parameters
Parameter Name Description Possible Values
PinSMSConfirmation.pin The generated PIN Text

Fire Message

Overview

Trigger an incoming message to the campaign manager (MO) for the given user information, useful when a user will respond to the campaign using a third party interface and no its mobile device. The response to this message will came using the intended response mechanism of the target campaign.

URL

Parameters on the following URL are inside braces { }

{base_url}/rest/api/fireMessage/{instanceId}/{mobileNumber}/{text}/{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
mobileNumber The target user mobile phone number
text This is the content of the message. 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>activateCampaign</input>
<status>OK</status>
<description>Completed</description>

Fire Message (POST)

Overview

Fire an MO to the ME with the given user information, useful when a user will respond to the campaign using a third party interface and no its mobile device. The response to this message will came using the intended response mechanism of the target campaign.

URL

Http access method: POST

Parameters on the following URL are inside braces { }

{base_url}/rest/api/fireMessage/{instanceId}/{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
Json
POST
Values to fire the message. Learn more about the Fire message Descriptor file
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>fireMessage</input>
   <status>OK</status>
   <description>Completed</description>
   <result>
      <mo>
         <instanceId>43</instanceId>
         <mobileNumber>1200000001</mobileNumber>
         <text>Test qa API fireMessage.</text>
      </mo>
   </result>

List Incoming Messages

Overview

Retrieve messages received, you can even narrow the results by adding some filters.

URL

Parameters on the following URL are inside braces { }

{base_url}/rest/api/tools/getMOMessages/{instanceId}/{page}/{resultsPerPage}/{parameters}/{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
page This is a paginated method, so please use page to indicate the actual page you want to retrieve.
resultsPerPage How many results to show per page. Note that this will affect the total amount of pages
parameters This parameters are special filters to narrow results when dealing with big amounts of data, Please find more information about these filters in the MO Inline Search String appendix
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>getMOMessages</input>
<status>OK</status>
<description>Completed</description>
<result>
	<MOMessageList>
		<records>17</records>
		<MessageList>
			<MOMessage>
				<text>Test</text>
				<from>58123456789</from>
				<to>19893143924</to>
				<encoding>UTF-8</encoding>
				<keyword>^OGANGI.*</keyword>
				<carrier>Movistar</carrier>
				<sendDate>2014-10-13 10:30:51.922</sendDate>
			</MOMessage>
		</MessageList>
	<MOMessageList>
</result>
Result parameters

Please be aware that the <MOMessage> tag and its content is a generic object and may apply to other responses in other methods.

Parameter Name Description Possible Values
MOMessageList.records Total found Number
MOMessage.text Message's content Text
MOMessage.from Who sent the message Short/Long code which originated the message
MOMessage.to Recipient for this message User's mobile number
MOMessage.encoding The charset encoding used for the message's text Valid encoding name
MOMessage.keyword Keyword in the message content. Text
MOMessage.carrier The carrier name used for this delivery Text
MOMessage.sendDate Time mark at the origination moment A formatted date string: yyyy-MM-dd'T'HH:mm:ss.SSSZZ
For more information please review the pattern letters quick reference