SmartFocus Cloud Service APIs

Transcription

1 SmartFocus Cloud Service APIs Document name Transactional SMS Messaging API Guide Service Transactional SMS Messaging Protocol REST over HTTP Version Last updated on Monday, March 26, 2018

2 Table of Contents Table of Contents Table of Contents 2 Introduction 3 About This Document 3 About SmartFocus APIs 3 Feedback 3 Support Options 3 Training Options 3 SmartFocus's Products and Services 3 Disclaimer 3 Overview of the Transactional SMS Messaging API 4 Transactional SMS Messaging API Use Case 4 Connection 5 Recommended Token Usage 5 API Authentication Request: Call Volume Throttling 5 Open Connection 6 Close Connection 8 SMS Transactional Post Request 10 REST Example 11 Get Status of RequestId 13 REST Example 13 Get Aggregate Reports 15 REST Example 16 Get Detailed Reports 18 REST Example 19 Reference

3 Introduction Introduction About This Document This document is a reference document for using SmartFocus APIs. It does not explain the purpose or functions of SmartFocus features. For information on these features, please consult the SmartFocus Online Help or the SmartFocus User Guide. This document is intended for developers and project managers. About SmartFocus APIs An Application Programming Interface (API) is a source code interface that a computer system or program library provides in order to support requests for services made from another computer program. The goal of SmartFocus APIs is to offer customers the ability to pilot a complete campaign from their own system. Feedback The Transactional SMS Messaging API Guide is constantly being enhanced to provide you with more and more information on using SmartFocus API methods. If you can't find the information you need or want to provide feedback, simply drop us a line at documentation@smartfocus.com. We look forward to hearing from you! Support Options SmartFocus provides you with a dedicated Account Manager to accompany you throughout the execution of your projects in SmartFocus. Your Account Manager is the gateway to support, training, and professional services. Working with your Account Manager, you can rely on SmartFocus s deliverability and technical support teams for complex troubleshooting and optimization. Training Options SmartFocus provides fully comprehensive training ranging from basic product training through to advanced modules and both strategic and tactical marketing courses. The training courses are designed to help you increase productivity, develop new methods, and share best practices to optimize your , mobile, and social marketing campaigns. To get more information on training, please contact your Account Manager. SmartFocus's Products and Services For more information on SmartFocus's products and services, please see Disclaimer While the information contained in this publication is believed to be true and accurate, SmartFocus cannot accept any legal responsibility for any errors or omissions contained herein. All information is subject to change without notice. None of the material in this publication may be reproduced or transmitted in whole or in part without the express written permission of SmartFocus. 3

4 Overview of the Transactional SMS Messaging API Overview of the Transactional SMS Messaging API The Transactional SMS Messaging API allows you to send transactional SMS messages and view the associated reports. The following methods are available: Connection Method Open Connection Close Connection This method provides a session token when given valid credentials. This method terminates the session token. Template Management Method SMS Transactional Post Request Get Status of RequestId Get Aggregate Reports Get Detailed Reports This method is used to send a transactional SMS message to a cellphone number. The response indicates whether the send was successful. This method retrieves the status of a post request. This method is used to retrieve the aggregate reports of transactional SMS messages sent within a specified period of time. This method is used to retrieve the detailed reports of transactional SMS messages sent to each cellphone number within a specified period. Transactional SMS Messaging API Use Case Post a Transactional SMS Message and Retrieve the Aggregate Report for the Recipient To post a transactional SMS message and retrieve the aggregate report for the recipient, carry out the following procedure: 1. Use the Open Connection method to open the connection. 2. Use the SMS Transactional Post Request method to post the transactional SMS message request. 3. Use the Get Status of RequestId method to check the status of the transational SMS message request. 4. Use the Get Aggregate Reports method to retrieve the statistics of transactional SMS messages sent to the member. 5. Use the Close Connection method to close the connection. 4

5 Connection Connection Prerequisite: To use SmartFocus APIs, you need to have the API manager login provided by SmartFocus and the associated password. To connect through the API, you must first retrieve the manager key from SmartFocus. 1. Go to Account Administration and select Logins. 2. Click the Edit icon next to your API manager. 3. In the API section of the popup window, copy the API key (also known as the manager key) and use it to open a connection to retrieve the token that will be used in your calls. Calling the connect method (with the login, password, manager key) will provide a token, to be used in all subsequent calls. This token will expire in the following cases: When a close connection call is made. When the maximum number of calls per session, defined by the manager in SmartFocus, is reached. When the session times out. Recommended Token Usage An open connection call generates a token that should be used until it expires. Once the token expires, an API call will generate a session exception. At this point, you should open a new connection to continue your API calls. Example: An example workflow: 1. Open the connection to generate the token. 2. Use API method calls as needed. If a call fails due to a problem with the session: a. Send another open connection call to renew the token. b. Resend the call that failed due to the session issue. 3. Send a close connection call once all API method calls for the session have been sent successfully. Note: For time consuming calls (e.g., uploading a large file), you may need to use an open connection call to ensure that the token will remain valid for the duration of the call. API Authentication Request: Call Volume Throttling A rate limit is applied to all authentication request calls to ensure optimal performance of the SmartFocus platform. An IP address will be throttled for 20 minutes whenever 10 or more calls containing the following strings are sent within a period of 10 seconds: /connect/open /authorization The following HTTP 429 error message is sent if your account has been throttled: Your HTTP requests are being throttled please contact your technical account manager for details Once the 20-minute period has elapsed, the throttling is automatically removed from the IP address. 5

6 Open Connection This method provides a session token when given valid credentials. Note: The token is valid for 60 minutes. If there is a period of inactivity for 30 consecutive minutes at any point after opening the connection, the token will expire and the connection will close automatically. This is a POST method. REST Note: The server information you enter in the depends on which of the following data centers your account is associated: Data Center Telecity Equinix Server apir.campaigncommander.com apie.campaigncommander.com For more information, please contact your Account Manager. parameters Required parameters login The login provided for API access return password The password Note: API passwords expire after 365 days. parameters The token to use in all other API calls apikey The manager key copied from SmartFocus (see Connection on page 5) Status code Error code Error messages Access denied JSON error REST Example content-type application/json Body 6

7 { } "login": "{login}", "password": "{password}", "apikey": "{key}" Status 204 No Content 7

8 Close Connection This method terminates the session token. This is a DELETE method. REST WADL Note: The server information you enter in the depends on which of the following data centers your account is associated: Data Center Telecity Equinix Server apir.campaigncommander.com apie.campaigncommander.com For more information, please contact your Account Manager. Note: A token is required to access the WADL. REST parameter Required parameter parameters token The connection token return The connection is closed if the operation was successful, otherwise an error code appears. Status code Error code SC_BAD_ REQUEST TOO_ MANY_ REQUEST Error messages You must fill in the token parameter The maximum number of connection allowed per session has been reached. SC_ INTERNAL_ An error occured on the server SERVER_ ERROR 8

9 REST Example content-type application/json Status 200 OK 9

10 SMS Transactional Post Request SMS Transactional Post Request This method is used to send a transactional SMS message to a cellphone number. The response indicates whether the send was successful. This is a POST method. REST WADL Note: The server information you enter in the depends on which of the following data centers your account is associated: Data Center Telecity Equinix Server apir.campaigncommander.com apie.campaigncommander.com For more information, please contact your Account Manager. Note: A token is required to access the WADL. REST parameter Required parameters token The connection token return cellphone content The cellphone number of the member The content of your SMS message parameter The SMS message details and the requestid 10

11 SMS Transactional Post Request parameter Required parameters The sender name that should appear instead of the sender cellphone number. The name cannot exceed 11 characters. parameter sender Note: If you have subscribed to the branded SMS sender option, depending on the region that you are in, the sender name can be a fixed or customizable value. Fixed branded sender: You must provide the sender parameter containing the branded sender configured for your account. Customizable branded sender: You must provide the sender parameter containing the sender value that you want to use for the SMS campaign using this SMS message. If you have not subscribed to the branded SMS sender option or if you are in a region where the branded SMS sender option is not permitted, the sender parameter should not be included. Status code Error code Error messages Parameter 'content' cannot be empty Parameter 'cellphone' cannot be empty Parameter 'cellphone' is invalid Parameter 'content' is too long Access denied JMS error JSON error Internal server error REST Example content-type application/json Body { } "cellphone":" ", "content":"thank you for purchasing our products.", "sender":"acme SHOES" 11

12 SMS Transactional Post Request Status 200 OK Body { } "cellphone": ", "content":"thank you for purchasing our products.", "sender":"acme SHOES", "requestid":" pum6hgknp31" 12

13 Get Status of RequestId Get Status of RequestId This method retrieves the status of a post request. This is a GET method. REST WADL Note: The server information you enter in the depends on which of the following data centers your account is associated: Data Center Telecity Equinix Server apir.campaigncommander.com apie.campaigncommander.com For more information, please contact your Account Manager. Note: A token is required to access the WADL. REST parameter parameter Required parameters token The connection token return The status of the requestid requestid The requestid number to retrieve Status code Error code Error messages Request not already processed or incorrect. Please try again later REST Example content-type application/json 13

14 Get Status of RequestId Status 200 OK Body { } "requestid":"requestid1", "sendstatus":"waiting", "cellphone": , "requestdate":" t02:20: " 14

15 Get Aggregate Reports Get Aggregate Reports This method is used to retrieve the aggregate reports of transactional SMS messages sent within a specified period of time. This is a GET method. REST WADL Note: The server information you enter in the depends on which of the following data centers your account is associated: Data Center Telecity Equinix Server apir.campaigncommander.com apie.campaigncommander.com For more information, please contact your Account Manager. Note: A token is required to access the WADL. REST parameter Required parameters token The connection token return The start date of the date range. The date format follows the ISO 8601 rules where date and time values are ordered from the most to the least significant. parameter The aggregate report of transactional SMS messages sent during the period startdate Example: : T10:20: T10:20:58+02:00 Note: It is highly recommended to always include the time zone. If the time zone is omitted, the SmartFocus server time zone will be used. 15

16 Get Aggregate Reports parameter Required parameters The end date of the date range. If the end date is omitted, the 24 hours following the start date will be retrieved. parameter The date format follows the ISO 8601 rules where date and time values are ordered from the most to the least significant. enddate Example: : T10:20: T10:20:58+02:00 Note: It is highly recommended to always include the time zone. If the time zone is omitted, the SmartFocus server time zone will be used. Status code Error code Error messages Invalid parameter Search criterias required or invalid The end date is before the start date Access denied. REST Example content-type application/json Status 200 OK Body { "smsdelivered":10, "smstotal":13, "smsnotdelivered":{ "smssenttooperator":1, "smsnotdeliveredtotal":3, 16

17 Get Aggregate Reports } } "smssoftbounce":1, "smshardbounce":1 17

18 Get Detailed Reports Get Detailed Reports This method is used to retrieve the detailed reports of transactional SMS messages sent to each cellphone number within a specified period. This is a GET method. REST WADL Note: The server information you enter in the depends on which of the following data centers your account is associated: Data Center Telecity Equinix Server apir.campaigncommander.com apie.campaigncommander.com For more information, please contact your Account Manager. Note: A token is required to access the WADL. REST parameter Required parameters token The connection token return The start date of the date range. The date format follows the ISO 8601 rules where date and time values are ordered from the most to the least significant. parameter The detailed report of transactional SMS messages sent to each cellphone number during the period startdate Example: : T10:20: T10:20:58+02:00 Note: It is highly recommended to always include the time zone. If the time zone is omitted, the SmartFocus server time zone will be used. 18

19 Get Detailed Reports parameter Required parameters The end date of the date range. If the end date is omitted, the 24 hours following the start date will be retrieved. parameter The date format follows the ISO 8601 rules where date and time values are ordered from the most to the least significant. enddate Example: : T10:20: T10:20:58+02:00 Note: It is highly recommended to always include the time zone. If the time zone is omitted, the SmartFocus server time zone will be used. page perpage The page to return The number of items to return per page Status code Error code Error messages Invalid parameter Search criterias required or invalid The end date is before the start date Access denied. REST Example content-type application/json Status 200 OK 19

20 Get Detailed Reports Link: < 13T07:19:45%2B02:00&page=1&endDate= T21:19:45%2B02:00&perPage=1>; rel="first",< {server}/sms-transactional-ws/reports/details/sms?startdate= t07:19:45%2b02:00&pagee=2&enddate= t21:19:45%2b02:00&perpage=1>; rel="prev",< actional-ws/reports/details/sms?startdate= t07:19:45%2b02:00&page=4&enddate= T21:19:45%2B02:00&perPage=1>; rel="next",< ports/details/sms?startdate= t07:19:45%2b02:00&page=5&enddate= T21:19:45%2B02:00&perPage=1>; rel="last" Total-Count: 2 Body [ ] { }, { } "cellphone": , "aggregatereport":{ "smsdelivered":2, "smsnotdelivered":{ "smshardbounce":0, "smssoftbounce":1, "smssenttooperator":1, "smsnotdeliveredtotal":2 }, "smstotal":4 } "cellphone": , "aggregatereport":{ "smsdelivered":1, "smsnotdelivered":{ "smshardbounce":0, "smssoftbounce":1, "smssenttooperator":1, "smsnotdeliveredtotal":2 }, "smstotal":3 } 20

21 Reference Reference WADL The Web Application Language (WADL) is a machine-readable XML-based language that provides a model for describing HTTP-based web applications (such as REST web services). Web Services The W3C defines a Web service as a software system designed to support interoperable Machine to Machine interaction over a network. Web services are frequently just Web APIs that can be accessed over a network, such as the Internet, and executed on a remote system hosting the requested services. The W3C Web service definition encompasses many different systems, but in common usage the term refers to clients and servers that communicate XML messages that follow the SOAP-standard. Common in both the field and the terminology is the assumption that there is also a machine readable description of the operations supported by the server, a description in the WSDL. The latter is not a requirement of SOAP endpoint, but it is a prerequisite for automated client-side code generation in the mainstream Java and.net SOAP frameworks. Some industry organizations, such as the WS-I, mandate both SOAP and WSDL in their definition of a Web service. WSDL The Web Services Language (WSDL, pronounced 'wiz-dull' or spelled out, 'W-S-D-L') is an XML-based language that provides a model for describing Web services. Version 2.1 has not been endorsed by the World Wide Web Consortium (W3C). Version 2.0, for which several drafts have been released, is expected to become a W3C recommendation. WSDL is an XMLbased service description on how to communicate using web services. The WSDL defines services as collections of network endpoints, or ports. WSDL specification provides an XML format for documents for this purpose. WSDL is often used in combination with SOAP and XML Schema to provide web services over the Internet. A client program connecting to a web service can read the WSDL to determine what functions are available on the server. Any special datatypes used are embedded in the WSDL file in the form of XML Schema. The client can then use SOAP to actually call one of the functions listed in the WSDL. XML The Extensible Markup Language (XML) is a W3C-recommended general-purpose markup language. The XML recommendation specifies both the structure of XML, and the requirements for XML processors. XML is considered "general-purpose" because it enables anyone to originate and use a markup language for many types of applications and problem domains. Numerous formally defined markup languages are based on XML, such as RSS, MathML, GraphML, XHTML, Scalable Vector Graphics, MusicXML, and thousands of others. XML's primary purpose is to facilitate the sharing of data across different information systems, particularly systems connected via the Internet. It is a simplified subset of Standard Generalized Markup Language (SGML), and is designed to be relatively human-legible. 21