Transcription
P.O. Box: 21419Sharjah, U.A.E.Tel: (971) 6 5254491Fax: (971) 6 5254343E-Mail: info@ucssolutions.comwww.ucssolutions.comReson8 REST API DocumentationVersion No: 7.11Date Updated: 01/07/2021Prepared By: Harpal Singh1
P.O. Box: 21419Sharjah, U.A.E.Tel: (971) 6 5254491Fax: (971) 6 5254343E-Mail: info@ucssolutions.comwww.ucssolutions.comRevision HistoryDocument NameDateReason For ChangesVersionUpdated ByReson8 – REST API20/11/2018Initial Draft1.0Harpal SinghReson8 – REST API28/08/2019Added campaign API2.0Harpal SinghReson8 – REST API29/08/2019Included curl samples3.0Harpal SinghReson8 – REST API13/11/2019Added OTP API4.0Harpal SinghReson8 – REST API16/01/2020Added status feedback web-hook payloadinfo5.0Harpal SinghReson8 – REST API09/02/2020Added incoming message payload info,web-hook security details, and correctedOTP API response parameters6.0Harpal SinghReson8 – REST API10/02/2020Corrected documentation6.1Harpal SinghReson8 – REST API12/02/2020Added template messaging API7.0Harpal SinghReson8 – REST API27/02/2020Added template campaign API7.1Harpal SinghReson8 – REST API03/03/2020Added scheduling option to templatemessaging API7.2Harpal SinghReson8 – REST API27/04/2020Added url-shortening option in basic andcampaign functions.7.3Harpal Singh7.4Harpal SinghAdded number validation APIReson8 – REST API27/05/2020Added address-book functions for contactcreation and opt-outAdded URL unique-id validation functionfor one-time use linksReson8 – REST API28/05/2020Added function for getting contact info7.5Harpal SinghReson8 – REST API07/06/2020Added web-push functions7.6Harpal SinghReson8 – REST API28/09/2020Added mobile-push functions7.7Harpal SinghReson8 – REST API16/03/2021Added filter option in incoming-messages7.8Harpal SinghReson8 – REST API24/03/2021Added appendix B for android payloadoptions, and appendix C for iOS7.9Harpal SinghReson8 – REST API01/07/2021Added email option in OTP API7.10Harpal SinghReson8 – REST API01/07/2021Corrected OTP API email-templateparameter7.11Harpal Singh2
P.O. Box: 21419Sharjah, U.A.E.Tel: (971) 6 5254491Fax: (971) 6 5254343E-Mail: info@ucssolutions.comwww.ucssolutions.comTable of ContentsGetting Started . 5How to get my Reson8 account? . 6How to get access to the API key? . 6Send Message – (Basic) . 7Send Message – (Campaign) . 9Send Message – (2-Way Tracking) . 11Send Message – (Template) . 13Send Message – (Template Campaign). 16Check Status . 19Get Incoming Message . 21Acknowledge Incoming Message. 23Send OTP message . 25Verify OTP . 27Validate Mobile Number. 29Retrieve Mobile Number Info . 31Add/Update Contact . 34Get Contact Info . 37Opt-out Contact. 39Validate URL Tracking-ID. 41Initialize VAPID keys for Web-Push . 43Register Device for Web-Push . 45Set Profile Information for a Web Browser . 48Update Tags/Segmentation for a Web Browser . 50Send Web-Push Notification . 52Check Status of Web-Push Notification. 54Initialize FCM/APNS keys for Mobile-Push . 56Initialize app key for Mobile-Push . 58Register Device for Mobile-Push . 60Set Profile Information for a Mobile Device . 62Update Tags/Segmentation for a Mobile Device . 643
P.O. Box: 21419Sharjah, U.A.E.Tel: (971) 6 5254491Fax: (971) 6 5254343E-Mail: info@ucssolutions.comwww.ucssolutions.comSend Mobile-Push Notification . 66Check Status of Mobile-Push Notification . 68Curl Samples for Sending Messages and Checking the Status . 70Status feedback web-hook payload information . 71Incoming message web-hook payload information. 72Web-hook security information . 73Appendix A (Time-zone codes) . 74Appendix B (Android Payload Options) . 77Appendix C (iOS Payload Options). 80Support Info. 824
P.O. Box: 21419Sharjah, U.A.E.Tel: (971) 6 5254491Fax: (971) 6 5254343E-Mail: ionREST APIs provide an efficient and very streamlined way of integrating services into Weband Mobile apps.Representational State Transfer (REST) is a software architectural style that defines a set ofconstraints to be used for creating Web services. Web services that conform to the RESTarchitectural style, called RESTful Web services (RWS), provide interoperability betweencomputer systems on the Internet. RESTful Web services allow the requesting systems toaccess and manipulate textual representations of Web resources by using a uniform andpredefined set of stateless operations.Getting StartedIn order to use the Reson8 gateway you need a Reson8 account and at least one registeredconnection (API sub-product instance) between your application and our gateway. Eachconnection method is known as a sub-product (of our API product). You can follow thesesteps to get started:5
P.O. Box: 21419Sharjah, U.A.E.Tel: (971) 6 5254491Fax: (971) 6 5254343E-Mail: info@ucssolutions.comwww.ucssolutions.comHow to get my Reson8 account?Getting a Reson8 account is very quick and easy. Sign up here for an account by entering afew details.How to get access to the API key?Instructions to access the API key are mentioned below.In Order to access API Key, Kindly follow below mentioned steps: Login to your Reson8 Account.Click on User Profile Icon available on top. Once On the user profile page, API key can be accessed as shown below.Click on ‘Eye’ Icon and API key will be accessible.6
P.O. Box: 21419Sharjah, U.A.E.Tel: (971) 6 5254491Fax: (971) 6 5254343E-Mail: info@ucssolutions.comwww.ucssolutions.comSend Message – (Basic)Purpose of the APIThe purpose of the API is to send basic messagesRequest t MethodThe API can be requested via POSTRequest-Input-FormatThe format for the request input is: application/jsonSecurity b31de07d84eeb3f83d11c6825Refer section: How to get access to the API keyRequest om-address, i.e., short-code or message-headerto-address, i.e., recipient mobile numbermessage text to be sent (max length: 938 for english, and 469 for non-english)specify value as “Y” to shorten URLs in message text (default: “N”)Sample Request Body{"from": "1234","to": "971500000000","text": "This is a test message"}7
P.O. Box: 21419Sharjah, U.A.E.Tel: (971) 6 5254491Fax: (971) 6 5254343E-Mail: info@ucssolutions.comwww.ucssolutions.comResponse campaignIDunique request reference (available only post authentication)error category (available only post authentication)status/error descriptioncampaign-id (if the message was queued successfully)Sample Response{"requestID": ": 9001,"procResponse": "Unregistered from-address (464)"}Response error-levelsError Level0900090019998/9999Descriptionrequest completed successfullyinvalid input structuredata validation failureunexpected application errorExact error/status description will be available in the procResponse attribute in theresponse bodyHTTP Response CodesHTTP Status Code200401429500503ReasonOKUnauthorizedToo many requestsUnexpected application errorService temporarily not available8
P.O. Box: 21419Sharjah, U.A.E.Tel: (971) 6 5254491Fax: (971) 6 5254343E-Mail: info@ucssolutions.comwww.ucssolutions.comSend Message – (Campaign)Purpose of the APIThe purpose of the API is to send messages for a bulk campaignRequest ignRequest MethodThe API can be requested via POSTRequest-Input-FormatThe format for the request input is: application/jsonSecurity b31de07d84eeb3f83d11c6825Refer section: How to get access to the API keyRequest gValuefrom-address, i.e., short-code or message-headerto-address, i.e., one or more recipient mobile numbers (max count: 100)message text to be sent (max length: 938 for English, and 469 for non-English)campaign name (max length: 100)Marketing/Operationalspecify value as “Y” to shorten URLs in message text (default: “N”)9
P.O. Box: 21419Sharjah, U.A.E.Tel: (971) 6 5254491Fax: (971) 6 5254343E-Mail: info@ucssolutions.comwww.ucssolutions.comSample Request Body{"from": "1234","to": ["971500000000","971560000000"]"text": "This is a test message","name": "Test campaign","type": "Marketing"}ResponseAttributes Error %ERRORDESC% /Error NameValuerequestIDunique request reference (available only post authentication) Error %ERRORDESC% /Error errorLevelerror category (available only post authentication)procResponsestatus/error descriptioncampaignIDcampaign-id (if the message was queued successfully)Sample Response{"requestID": ": 9001,"procResponse": "Unregistered from-address (464)"}Response Error-LevelsError Level0900090019998/9999Descriptionrequest completed successfullyinvalid input structuredata validation failureunexpected application errorExact error/status description will be available in the procResponse attribute in theresponse bodyHTTP Response CodesHTTP Status Code200401429500503ReasonOKUnauthorizedToo many requestsUnexpected application errorService temporarily not available10
P.O. Box: 21419Sharjah, U.A.E.Tel: (971) 6 5254491Fax: (971) 6 5254343E-Mail: info@ucssolutions.comwww.ucssolutions.comSend Message – (2-Way Tracking)Purpose of the APIThe purpose of the API is send messages with the option of response trackingRequest edRequest MethodThe API can be requested via POSTRequest-Input-FormatThe format for the request input is: application/jsonSecurity b31de07d84eeb3f83d11c6825Refer section: How to get access to the API keyRequest efrom-address, i.e., short-code or message-headerto-address, i.e., recipient mobile numbermessage text to be sent (max length: 938 for English, and 469 for non-English)specify value as "Y" only if a reply is expected for this message, else specify the valueas "N"Sample Request Body{"from": "1234","to": "971500000000","text": "This is a test message","enableResponseTracking": "N"} Error %ERRORDESC% /Error Error %ERRORDESC% /Error 11
P.O. Box: 21419Sharjah, U.A.E.Tel: (971) 6 5254491Fax: (971) 6 5254343E-Mail: info@ucssolutions.comwww.ucssolutions.comResponse campaignIDunique request reference (available only post authentication)error category (available only post authentication)status/error descriptioncampaign-id (if the message was queued successfully)Sample Response{"requestID": ": 9001,"procResponse": "Unregistered from-address (464)"}Response error-levelsError Level0900090019998/9999Descriptionrequest completed successfullyinvalid input structuredata validation failureunexpected application errorExact error/status description will be available in the procResponse attribute in theresponse bodyHTTP Response CodesHTTP Status Code200401429500503ReasonOKUnauthorizedToo many requestsUnexpected application errorService temporarily not available12
P.O. Box: 21419Sharjah, U.A.E.Tel: (971) 6 5254491Fax: (971) 6 5254343E-Mail: info@ucssolutions.comwww.ucssolutions.comSend Message – (Template)Purpose of the APIThe purpose of the API is to send template based messageRequest ateRequest MethodThe API can be requested via POSTRequest-Input-FormatThe format for the request input is: application/jsonSecurity b31de07d84eeb3f83d11c6825Refer section: How to get access to the API keyRequest neValuefrom-address, i.e., short-code or message-headerto-addresstemplate-idtemplate parametersspecify value as “Y” to shorten URLs in message text (default: “N”)specify value as "Y" only if an SMS reply is expected for this message(default: “N”)schedule date-time in yyyy-MM-dd HH:mm format (optional)schedule time-zone code, please refer Appendix A (optional)13
P.O. Box: 21419Sharjah, U.A.E.Tel: (971) 6 5254491Fax: (971) 6 5254343E-Mail: info@ucssolutions.comwww.ucssolutions.comSample Request Body{"from": "Reson8SMS","to": "971xxyyyyyy","tid": 9999999,"params": [{"name": "PARAM-1","value": "Value 1"}]}Response campaignIDextTrackingIDunique request reference (available only post authentication)error category (available only post authentication)status/error descriptioncampaign-id (if the message was queued successfully)external tracking-id (if the message template contains an EXT TRACKING IDparameter)Sample Response{"requestID": ": 9001,"procResponse": "Unregistered from-address (464)"}Response Error-LevelsError Level0900090019998/9999Descriptionrequest completed successfullyinvalid input structuredata validation failureunexpected application error14
P.O. Box: 21419Sharjah, U.A.E.Tel: (971) 6 5254491Fax: (971) 6 5254343E-Mail: info@ucssolutions.comwww.ucssolutions.comExact error/status description will be available in the procResponse attribute in theresponse bodyHTTP Response CodesHTTP Status Code200401429500503ReasonOKUnauthorizedToo many requestsUnexpected application errorService temporarily not available15
P.O. Box: 21419Sharjah, U.A.E.Tel: (971) 6 5254491Fax: (971) 6 5254343E-Mail: info@ucssolutions.comwww.ucssolutions.comSend Message – (Template Campaign)Purpose of the APIThe purpose of the API is to send template based campaignsRequest ate/campaignRequest MethodThe API can be requested via POSTRequest-Input-FormatThe format for the request input is: application/jsonSecurity b31de07d84eeb3f83d11c6825Refer section: How to get access to the API keyRequest LShorteningValuefrom-address, i.e., short-code or message-headertemplate-idrecipient-wise template parameterscampaign name (max length: 100)Marketing/Operationalspecify value as “Y” to shorten URLs in message text (default: “N”)16
P.O. Box: 21419Sharjah, U.A.E.Tel: (971) 6 5254491Fax: (971) 6 5254343E-Mail: info@ucssolutions.comwww.ucssolutions.comSample Request Body{"from": "Reson8SMS","tid": 9999999,"recipientData": [{"to": "971xxyyyyy1","params": [{"name": "PARAM-1","value": "Value 123"},{"name": "PARAM-2","value": "Value 456"}]},{"to": "971xxyyyyy2","params": [{"name": "PARAM-1","value": "Value ABC"},{"name": "PARAM-2","value": "Value XYZ"}]}],"name": "Test Campaign","type": "Marketing","enableURLShortening": "N"}17
P.O. Box: 21419Sharjah, U.A.E.Tel: (971) 6 5254491Fax: (971) 6 5254343E-Mail: info@ucssolutions.comwww.ucssolutions.comResponse campaignIDunique request reference (available only post authentication)error category (available only post authentication)status/error descriptioncampaign-id (if the message was queued successfully)Sample Response{"requestID": ": 9001,"procResponse": "Unregistered from-address (464)"}Response Error-LevelsError Level0900090019998/9999Descriptionrequest completed successfullyinvalid input structuredata validation failureunexpected application errorExact error/status description will be available in the procResponse attribute in theresponse bodyHTTP Response CodesHTTP Status Code200401429500503ReasonOKUnauthorizedToo many requestsUnexpected application errorService temporarily not available18
P.O. Box: 21419Sharjah, U.A.E.Tel: (971) 6 5254491Fax: (971) 6 5254343E-Mail: info@ucssolutions.comwww.ucssolutions.comCheck StatusPurpose of the APIThe purpose of the API is to check the status of the messageRequest sRequest MethodThe API can be requested via GETRequest-Input-FormatThe format for the request input is: path-parametersSecurity b31de07d84eeb3f83d11c6825Refer section: How to get access to the API keyRequest AttributesNamecampaignIDValuecampaign-id of the message for which status needs to be checkedSample tatus/0a7acabe-f8f7-4cab-b5256f2e890683fcResponse sInfoValueunique request reference (available only post authentication)error category (available only post authentication)status/error descriptionarray of objects providing recipient-wise status-information19
P.O. Box: 21419Sharjah, U.A.E.Tel: (971) 6 5254491Fax: (971) 6 5254343E-Mail: info@ucssolutions.comwww.ucssolutions.comSample Response{"requestID": ": 9002,"procResponse": "No status information available"}Response error-levelsError LevelDescription0900190029998/9999request completed successfullydata validation failurerequest processing/information retrieval failureunexpected application errorExact error/status description will be available in the procResponse attribute in theresponse bodyHTTP Response CodesHTTP Status Code200401429500ReasonOKUnauthorizedToo many requestsUnexpected application error20
P.O. Box: 21419Sharjah, U.A.E.Tel: (971) 6 5254491Fax: (971) 6 5254343E-Mail: info@ucssolutions.comwww.ucssolutions.comGet Incoming MessageAPI PurposeThe purpose of the API is to fetch incoming messageRequest agesRequest MethodThe API can be requested via GETRequest-Input-FormatThe format for the request input is: query-parametersSecurity b31de07d84eeb3f83d11c6825Refer section: How to get access to the API keyRequest AttributesNametoValuefor filtering by destination address (optional)Sample messages21
P.O. Box: 21419Sharjah, U.A.E.Tel: (971) 6 5254491Fax: (971) 6 5254343E-Mail: info@ucssolutions.comwww.ucssolutions.comResponse gesValueunique request reference (available only post authentication)error category (available only post authentication)status/error descriptionarray of objects providing incoming messages dataSample Response{"requestID": ": 0,"messages": [{"messageID": 12345,"from": "971500000000","to": "1234","text": "Y","receivedAt": "1990-01-16 11:18:15.0","campaignID": "7986273f-4787-44d6-b18a-a579bda8304f"}}Response error-levelsError Level090029998/9999Descriptionrequest completed successfullyrequest processing/information retrieval failureunexpected application errorExact error/status description will be available in the procResponse attribute in theresponse bodyHTTP Response CodesHTTP Status Code200401429500ReasonOKUnauthorizedToo many requestsUnexpected application error22
P.O. Box: 21419Sharjah, U.A.E.Tel: (971) 6 5254491Fax: (971) 6 5254343E-Mail: ge Incoming MessageAPI PurposeThe purpose of the API is to acknowledge incoming message (i.e., update as read)Request ages/ackRequest MethodThe API can be requested via POSTRequest-Input-FormatThe format for the request input is: path-parametersSecurity b31de07d84eeb3f83d11c6825Refer section: How to get access to the API keyRequest AttributesNamemsgIDValuemessage-id of the incoming message that is to be acknowledgedSample messages/ack/1234523
P.O. Box: 21419Sharjah, U.A.E.Tel: (971) 6 5254491Fax: (971) 6 5254343E-Mail: info@ucssolutions.comwww.ucssolutions.comResponse unique request reference (available only post authentication)error category (available only post authentication)status/error descriptionSample Response{"requestID": ": 9001,"procResponse": "Invalid message-id (227)"}Response error-levelsError Level0900190029998/9999Descriptionrequest completed successfullydata validation failurerequest processing/information retrieval failureunexpected application errorExact error/status description will be available in the procResponse attribute in theresponse bodyHTTP Response CodesHTTP Status Code200401500ReasonOKUnauthorizedUnexpected application error24
P.O. Box: 21419Sharjah, U.A.E.Tel: (971) 6 5254491Fax: (971) 6 5254343E-Mail: info@ucssolutions.comwww.ucssolutions.comSend OTP messageAPI PurposeThe purpose of the API is to send OTP messageRequest st MethodThe API can be requested via POSTRequest-Input-FormatThe format for the request input is: application/jsonSecurity b31de07d84eeb3f83d11c6825Refer section: How to get access to the API keyRequest efrom-address, i.e., short-code or message-headerrecipient mobile numberlanguage indicator for OTP SMS text (possible values: EN/AR, default: EN)custom message template (placeholders: %OTP% for the OTP code,%OTP VALIDITY% for the validity)length of OTP code (min: 4, max: 8, default: 6)validity of OTP code in minutes (min: 1, max: 5, default: 3)for sending OTP as per SMS Retriever API guidelines to enable automatic verificationrecipient email addressemail subject (mandatory for sending OTP by email)custom message template (placeholders: %OTP% for the OTP code,%OTP VALIDITY% for the validity)25
P.O. Box: 21419Sharjah, U.A.E.Tel: (971) 6 5254491Fax: (971) 6 5254343E-Mail: info@ucssolutions.comwww.ucssolutions.comSample Request{"from": "1234","to": e request reference (available only post authentication)error category (available only post authentication)status/error descriptioncampaign-id (if the message was queued successfully)OTP reference code (for use in verification request)Sample Response{"requestID": ": 9001,"procResponse": "Unregistered from-address (464)"}Response error-levelsError Level0900090019998/9999Descriptionrequest completed successfullyinvalid input structuredata validation failureunexpected application errorExact error/status description will be available in the procResponse attribute in theresponse bodyHTTP Response CodesHTTP Status Code200401429500503ReasonOKUnauthorizedToo many requestsUnexpected application errorService temporarily not available26
P.O. Box: 21419Sharjah, U.A.E.Tel: (971) 6 5254491Fax: (971) 6 5254343E-Mail: info@ucssolutions.comwww.ucssolutions.comVerify OTPAPI PurposeThe purpose of the API is to verify OTP messageRequest uest MethodThe API can be requested via POSTRequest-Input-FormatThe format for the request input is: application/jsonSecurity b31de07d84eeb3f83d11c6825Refer section: How to get access to the API keyRequest AttributesNameotpReferenceotpCodeValueOTP reference received from Send-OTP API requestOTP code provided by userSample Request{"otpReference": "01234567-0123-0123-0123-012345678901","otpCode": "000000"}27
P.O. Box: 21419Sharjah, U.A.E.Tel: (971) 6 5254491Fax: (971) 6 5254343E-Mail: info@ucssolutions.comwww.ucssolutions.comResponse ignIDValueunique request reference (available only post authentication)error category (available only post authentication)status/error descriptioncampaign-id (if the message was queued successfully)Sample Response{"requestID": ": 0,"procResponse": "OTP verified successfully"}Response error-levelsError Level09000900190029998/9999Descriptionrequest completed successfullyinvalid input structuredata validation failureOTP validation failureunexpected application errorExact error/status description will be available in the procResponse attribute in theresponse bodyHTTP Response CodesHTTP Status Code200401429500503ReasonOKUnauthorizedToo many requestsUnexpected application errorService temporarily not available28
P.O. Box: 21419Sharjah, U.A.E.Tel: (971) 6 5254491Fax: (971) 6 5254343E-Mail: info@ucssolutions.comwww.ucssolutions.comValidate Mobile NumberAPI PurposeThe purpose of the API is to validate if a number is structurally a valid mobile numberRequest teRequest MethodThe API can be requested via POSTRequest-Input-FormatThe format for the request input is: application/jsonSecurity b31de07d84eeb3f83d11c6825Refer section: How to get access to the API keyRequest Body: an array of mobile numbers (maximum 100 per-request)Sample Request["971500000000","971511111111"]Response AttributesNamerequestIDerrorLevelpr
Reson8 - REST API 09/02/2020 Added incoming message payload info, web-hook security details, and corrected OTP API response parameters 6.0 Harpal Singh Reson8 - REST API 10/02/2020 Corrected documentation 6.1 Harpal Singh Reson8 - REST API 12/02/2020 Added template messaging API 7.0 Harpal Singh Reson8 - REST API 27/02/2020 Added .
