//[[restapi:start|RESTful API]]//

====== Client's Callback URL ======

As you can imagine many of the RESTful API methods are asynchronous, this is why a client's callback is needed, we will be posting there updates and event information when it arises.

If you want to be prepared for those notifications you need to configure a basic WebServer (public URL) that could handle simple POST request with parameters.

<WRAP round tip>
Your URL will be called **- using POST -** when the Campaign Manager needs to send you a notification, such as message delivery failure, new incoming messages and geofencing triggers. 
</WRAP>

Depending of each case we will provide a set of parameters as follows:

===== Incoming MO messages =====

^ Parameter ^ Description ^
| FROM | From where the message comes |
| TO | Message's destination |
| TEXT | Message's content |
| ENCODING | Message's encoding. |
| TYPE | Always **MO_MESSAGE** in this case |

===== Incoming SMS =====

^ Parameter ^ Description ^
| FROM | From where the message comes |
| TO | Message's destination |
| MESSAGE_BODY | Message's content |
| TYPE | Always **SMS** in this case |
| CLIENT_ID | Client's identification ID |
| MESSANGI_ID | Event's Unique identifier |
| STATUS | Message's current status. Valid values at the [[restapi:appx_msg_status#sms|SMS status]] appendix  |

===== Delivered PUSH messages =====

^ Parameter ^ Description ^
| FROM | From where the message was sent |
| TO | The push notification recipient |
| MESSAGE_BODY | Message's content |
| TYPE | Always **PUSH** in this case |
| CLIENT_ID | Client's identification ID |
| MESSANGI_ID | Event's Unique identifier |
| STATUS | Message's current status. Valid values at the [[restapi:appx_msg_status#push|PUSH status]] appendix  |

===== Incoming Facebook messages =====

^ Parameter ^ Description ^
| FROM | Sender's Facebook ID |
| TO | Message's destination |
| MESSAGE_BODY | Message's content |
| TYPE | Always **FACEBOOK** in this case |
| CLIENT_ID | Client's identification ID |
| MESSANGI_ID | Event's Unique identifier |
===== Incoming Email messages =====

^ Parameter ^ Description ^
| FROM | Sender's email |
| TO | Message's destination |
| MESSAGE_BODY | Message's content |
| TYPE | Always **EMAIL** in this case |
| CLIENT_ID | Client's identification ID |
| MESSANGI_ID | Event's Unique identifier |
| STATUS | Message's current status. Valid values at the [[restapi:appx_msg_status#email|Email status]] appendix  |

===== Location =====

^ Parameter ^ Description ^
| client_object_id	| Unique identifier for the Messangi's client. |
| messangi_object_id	| Unique identifier for the object. |
| status | Message's current status. Valid values at the [[restapi:appx_msg_status#location|Location status]] appendix | 
| type	| This is the location’s type, could be: LOCATION, CHK_LOCATION, GEOFENCE or BEACONFENCE |
| device | Identifier for the device. |
| latitude	| The coordinate's latitude of the device's location. |
| longitude	| The coordinate's longitude of the device's location. |
| status_description	| Any additional info. |
| phone_number | Sender's mobile number |
===== Redirect URL Clicked =====

^ Parameter ^ Description ^
| ID	| URL's id |
| EXTERNAL_ID	| ID of the campaign (an arbitrary string, can be a number). |
| ID_TYPE	| ID of the type (example: identifier of Scratchcard) |
| TO | Any of: device, phone number or clicker's email |
| VISITS | Number of times the URL was clicked |
| CLIENT_DATE | Date when URL was clicked |
| ONE_TIME | Limit for using the URL. |
| EVENT_TYPE | Event's type |
| REDIRECT_TYPE	| SCRATCHCARD / PASSBOOK |

===== User Response =====

^ Parameter ^ Description ^
| FROM	| Sender´s phone number or device id |
| TYPE	| USER_RESPONSE in this case |
| TEXT	| Message's content |
| APPNAME | App's name |
| PLATFORM | App's platform |

===== Event Notification =====

^ Field          ^ Description       ^
| DEVICE_ID           | The ID of the device that generated the event. In SDK generated events (push notifications, geofences, iBeacons, etc) this is the Unique Device ID as provided by the Android or iOS platform. For events that are not generated by a native application running in the phone (scratchcards, redirect URLs, etc) this is the internal Messangi ID |
| ORIGIN              | The mobile number (or any other identification token) associated with the event, hashed with SHA-256 |
| CLIENT_ID             | The internal Messangi Client ID. This field is used for aggregations where a master user has visibility over several sub clients |
| CLIENT_NAME | Name of the client |
| CLIENT_DATE | Date when the interaction was received in the client's timezone |
| EVENT_TYPE          | The type of event. Since all events are stored on the same data structure this field will show all the types of events across all applications and channels if no additional aggregations are added. |
| APP                | The name of the application that generated the event. Different apps can generate the same event types which can provide interesting cross channel aggregations. For example, the OPEN event type can be generated by the SCRATCHCARD and MOBILE_SDK apps, representing the action of opening the scratchcard or the mobile app respectively. Without aggregations those two events will be displayed in the dashboard showing the location where users open your campaigns (both of them). Adding an app aggregation shows the OPEN event just for SCRATCHCARD or MOBILE_SDK |
| PLATFORM           | The platform on which the event was generated. If the event was generated by the Mobile SDK the platform is either Android or iOS. If the event was generated by a web interaction (Scratchcard, Passbook, Redirect URL, etc) the platform will be the user-agent |
| ADDRESS            | The IP address from which the event was captured. If the X-Forwarded-For HTTP header is present then it is used instead |
| COUNTRY        | The country code corresponding to the location of the event. Several methods are used to determine this value: if the event was generated by the Mobile SDK and the GPS is enabled and authorized then the country code is obtained from the [latitude, longitude] combination. If the GPS is not available (it is disabled, or the event was generated by a web browser in the case of Scratchcards or redirect URLs) the country code is obtained from the GeoIP location of the IP address |
| EXTRA_INFO          | Any additional information relevant to the event. For push notifications this is the subject, for scratchcards it's the campaign name, etc |
| CAMPAIGN_NAME | Name of the campaign that sent the interaction |
| VERSION            | The version of the app that generated the event. |
| UTC_WHEN               | The date when the event was generated. |
| LOCATION           | The location of the event. This location is obtained from the phone GPS in the case of Mobile SDK events, or the IP address for HTTP based events (Scratchcard, Passbook, Redirect URLs, etc) |
| TYPE               | Always contains the value: EVENT |