//[[restapi:start|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 [[:mmc_otto|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 [[:mmc_otto|ticketing tool]] to request one.// |
| mobileNumber | The target User's mobile phone number. This parameter must be [[restapi:appx_ciphering#base64_-_encode|Base64 encoded]] |
| text | This is the content of the message. This parameter must be [[restapi:appx_ciphering#base64_-_encode|Base64 encoded]] |
| publicKey | The public key to access this API. //if you don't know yours please request it using our [[:mmc_otto|ticketing tool]], you will need to provide your Mobile Engagement Campaign Manager's URL and your user login// |
| signature | The unique [[restapi:appx_ciphering#SHA256 - Cipher|SHA256]] signature for this call, it's involve all input parameters. To learn about generating the correct signature please visit our [[restapi:appx_call_ex|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 [[restapi:appx_resp_xml|Response XML Basics]] section if you want to learn more about the response parts.

<code xml>

<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>

</code>

== Result parameters ==

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

^ 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 [[restapi:appx_msg_status#blast|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 [[restapi:appx_date|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 [[:mmc_otto|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 [[:mmc_otto|ticketing tool]] to request one.// |
| carrier | Mobile operator ID in which the user have his SIM card or contract. \\ <wrap info>Write **//null//** on this placeholder to let the CM look for a suitable carrier </wrap> |
| mobileNumber | The target User's mobile phone number |
| text | This is the content of the message. This parameter must be [[restapi:appx_ciphering#base64_-_encode|Base64 encoded]]|
| publicKey | The public key to access this API. //if you don't know yours please request it using our [[:mmc_otto|ticketing tool]], you will need to provide your Mobile Engagement Campaign Manager's URL and your user login// |
| signature | The unique [[restapi:appx_ciphering#SHA256 - Cipher|SHA256]] signature for this call, it's involve all input parameters. To learn about generating the correct signature please visit our [[restapi:appx_call_ex|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 [[restapi:appx_resp_xml|Response XML Basics]] section if you want to learn more about the response parts.

<code xml>

<input>sendMT</input>
<status>OK</status>
<description>Completed</description>

</code>


====== 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 [[:mmc_otto|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 [[:mmc_otto|ticketing tool]] to request one.// |
| carrier | Mobile operator ID in which the user have his SIM card or contract. \\ <wrap info>Write **//null//** on this placeholder to let the CM look for a suitable carrier </wrap> |
| mobileNumber | The target User's mobile phone number |
| text | This is the content of the message. This parameter must be [[restapi:appx_ciphering#base64_-_encode|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 [[:mmc_otto|ticketing tool]], you will need to provide your Mobile Engagement Campaign Manager's URL and your user login// |
| signature | The unique [[restapi:appx_ciphering#SHA256 - Cipher|SHA256]] signature for this call, it's involve all input parameters. To learn about generating the correct signature please visit our [[restapi:appx_call_ex|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 [[restapi:appx_resp_xml|Response XML Basics]] section if you want to learn more about the response parts.

<code xml>

<input>sendMT</input>
<status>OK</status>
<description>Completed</description>

</code>



====== Generate Mobile PIN ======

==== Overview ====

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

<WRAP round tip>
Useful when a live validation is needed, user cases examples:

  * User own's the mobile number
  * ATM or any other delicate operation
  * Promo code
</WRAP>

==== 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 [[:mmc_otto|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 [[:mmc_otto|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 [[restapi:appx_ciphering#base64_-_encode|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 [[:mmc_otto|ticketing tool]], you will need to provide your Mobile Engagement Campaign Manager's URL and your user login// |
| signature | The unique [[restapi:appx_ciphering#SHA256 - Cipher|SHA256]] signature for this call, it's involve all input parameters. To learn about generating the correct signature please visit our [[restapi:appx_call_ex|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 [[restapi:appx_resp_xml|Response XML Basics]] section if you want to learn more about the response parts.

<code xml>

<input>sendSMSPinMobileNumberConfirm</input>
<status>OK</status>
<description>Completed</description>
<result>
	<PinSMSConfirmation>
			<pin>846547</pin>
	</PinSMSConfirmation>
</result>

</code>

== 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 [[:mmc_otto|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 [[restapi:appx_ciphering#base64_-_encode|Base64 encoded]]|
| publicKey | The public key to access this API. //if you don't know yours please request it using our [[:mmc_otto|ticketing tool]], you will need to provide your Mobile Engagement Campaign Manager's URL and your user login// |
| signature | The unique [[restapi:appx_ciphering#SHA256 - Cipher|SHA256]] signature for this call, it's involve all input parameters. To learn about generating the correct signature please visit our [[restapi:appx_call_ex|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 [[restapi:appx_resp_xml|Response XML Basics]] section if you want to learn more about the response parts.

<code xml>

<input>activateCampaign</input>
<status>OK</status>
<description>Completed</description>

</code>

====== 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: <wrap notice>POST</wrap>

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 [[misc:otto|ticketing tool]], you will need to provide your Mobile Engagement Campaign Manager's URL and your user login// |
| Json \\ <wrap notice>POST</wrap> | Values to fire the message. Learn more about the [[sdk:fire_message_json|Fire message Descriptor]] file |
| publicKey | The public key to access this API. //if you don't know yours please request it using our [[misc:otto|ticketing tool]], you will need to provide your Mobile Engagement Campaign Manager's URL and your user login// |
| signature | The unique [[restapi:appx_ciphering#SHA256 - Cipher|SHA256]] signature for this call, it's involve all input parameters. To learn about generating the correct signature please visit our [[restapi:appx_call_ex|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 [[restapi:appx_resp_xml|Response XML Basics]] section if you want to learn more about the response parts.

<code xml>

<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>

</code>

====== 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 [[:mmc_otto|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 [[restapi:appx_mo_search|MO Inline Search String]] appendix | 
| publicKey | The public key to access this API. //if you don't know yours please request it using our [[:mmc_otto|ticketing tool]], you will need to provide your Mobile Engagement Campaign Manager's URL and your user login// |
| signature | The unique [[restapi:appx_ciphering#SHA256 - Cipher|SHA256]] signature for this call, it's involve all input parameters. To learn about generating the correct signature please visit our [[restapi:appx_call_ex|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 [[restapi:appx_resp_xml|Response XML Basics]] section if you want to learn more about the response parts.

<code xml>

<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>

</code>

== Result parameters ==

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

^ 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 [[restapi:appx_date|pattern letters]] quick reference |