Transactional SMS Messaging API Guide - REST · Introduction AboutThisDocument ThisdocumentisareferencedocumentforusingSmartFocusAPIs.ItdoesnotexplainthepurposeorfunctionsofSmartFocus

SmartFocus Cloud Service APIsDocument name Transactional SMS Messaging API GuideService Transactional SMS MessagingProtocol REST over HTTPVersion 11.24Last updated on Thursday, February 7, 2019

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

2

Transactional SMS Messaging API GuideTable of Contents

Introduction

About This Document

This document is a reference document for using SmartFocus APIs. It does not explain the purpose or functions of SmartFocusfeatures. 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 inorder 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 onusing SmartFocus API methods.

If you can't find the information you need or want to provide feedback, simply drop us a line [email protected].

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 inSmartFocus. Your Account Manager is the gateway to support, training, and professional services. Working with your AccountManager, you can rely on SmartFocus’s deliverability and technical support teams for complex troubleshooting andoptimization.

Training Options

SmartFocus provides fully comprehensive training ranging from basic product training through to advanced modules and bothstrategic and tactical marketing courses. The training courses are designed to help you increase productivity, develop newmethods, and share best practices to optimize your email, 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 www.smartfocus.com

Disclaimer

While the information contained in this publication is believed to be true and accurate, SmartFocus cannot accept any legalresponsibility 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 writtenpermission of SmartFocus.

3

Transactional SMS Messaging API GuideIntroduction

mailto:[email protected]?subject=API Help

http://www.smartfocus.com/

Overview of the Transactional SMS Messaging APIThe Transactional SMS Messaging API allows you to send transactional SMS messages and view the associated reports.

The following methods are available:

l ConnectionMethod Description

Open Connection This method provides a session token when given valid credentials.

Close Connection This method terminates the session token.

l Template ManagementMethod Description

SMS TransactionalPost Request

This method is used to send a transactional SMS message to a cellphone number. The responseindicates whether the send was successful.

Get Status ofRequestId This method retrieves the status of a post request.

Get AggregateReports

This method is used to retrieve the aggregate reports of transactional SMS messages sentwithin a specified period of time.

Get Detailed ReportsThis method is used to retrieve the detailed reports of transactional SMS messages sent to eachcellphone 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.

www.smartfocus.com 4

Transactional SMS Messaging API GuideOverview of the Transactional SMS Messaging API


Connection

Prerequisite: To use SmartFocus APIs, you need to have the API manager login provided by SmartFocus and the associatedpassword.

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:

l When a close connection call is made.l When the maximum number of calls per session, defined by the manager in SmartFocus, is reached.l 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 willgenerate 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 thetoken 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 aperiod of 10 seconds:

l /connect/open

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

Transactional SMS Messaging API GuideConnection

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 openingthe connection, the token will expire and the connection will close automatically.

This is a POST method.

REST URL

https://{server}/sms-transactional-ws/authorization

Note: The server information you enter in the URL depends on which of the following data centers your account is asso-ciated:

Data Center Server

Telecity apir.campaigncommander.com

Equinix apie.campaigncommander.com

For more information, please contact your Account Manager.

Inputparameters

Requiredparameters

Description Outputparameters Description

login The login provided for API access returnThe token to use in all otherAPI calls

passwordThe password

Note: API passwords expire after 365 days.

apiKeyThe manager key copied from SmartFocus (seeConnection on page 5)

Status code Error code Error messages

403 003 Access denied.500 204 JSON error

REST Example

Input

URL


Header

content-type application/json

Body

6

Transactional SMS Messaging API Guide

{"login": "{login}","password": "{password}","apiKey": "{key}"

}

Output

Status

204 No Content

Header

CCMD_API_TOKEN {token}

7


Close Connection

This method terminates the session token.

This is a DELETE method.

REST WADL

URL

https://{server}/sms-transactional-ws/application.wadl

Header



Data Center Server




Note: A token is required to access the WADL.

REST URL


Inputparameter

Requiredparameters

Description Outputparameter Description

tokenThe connectiontoken

returnThe connection is closed if the operation was successful, otherwisean error code appears.

Statuscode

Errorcode

Error messages

400 SC_BAD_REQUEST You must fill in the token parameter

429TOO_MANY_REQUEST

The maximum number of connection allowed per session has beenreached.

500

SC_INTERNAL_SERVER_ERROR

An error occured on the server

8


REST Example

Input

URL


Header



Output

Status

200 OK

9


SMS Transactional Post RequestThis method is used to send a transactional SMS message to a cellphone number. The response indicates whether the sendwas successful.

This is a POST method.

REST WADL

URL


Header



Data Center Server





REST URL

https://{server}/sms-transactional-ws/request

Inputparameter

Requiredparameters


token The connection token return

The SMSmessage detailsand therequestId

cellphone The cellphone number of the membercontent The content of your SMS message


Transactional SMS Messaging API GuideSMS Transactional Post Request


Inputparameter

Requiredparameters


sender

The sender name that should appear instead of the sender cellphonenumber. The name cannot exceed 11 characters.

Note: If you have subscribed to the branded SMS sender option, dependingon the region that you are in, the sender name can be a fixed orcustomizable value.

l Fixed branded sender: You must provide the sender parametercontaining the branded sender configured for your account.

l Customizable branded sender: You must provide the senderparameter containing the sender value that you want to use for theSMS campaign using this SMS message.

If you have not subscribed to the branded SMS sender option or if you arein a region where the branded SMS sender option is not permitted, thesender parameter should not be included.


400 101Parameter 'content' cannot be empty

Parameter 'cellphone' cannot be empty400 103 Parameter 'cellphone' is invalid400 104 Parameter 'content' is too long403 003 Access denied.500 203 JMS error500 204 JSON error500 000 Internal server error

REST Example

Input

URL

https://{server}/sms-transactional-ws/request

Header



Body

{"cellphone":"33611223344","content":"Thank you for purchasing our products.","sender":"ACME SHOES"

}




Output

Status

200 OK

Body

{"cellphone":33611223344","content":"Thank you for purchasing our products.","sender":"ACME SHOES","requestId":"1382106598412pUm6HGknp31"

}




Get Status of RequestIdThis method retrieves the status of a post request.

This is a GETmethod.

REST WADL

URL


Header



Data Center Server





REST URL

https://{server}/sms-transactional-ws/request/{requestId}

Input parameter

Required parametersDescription Output parameter Description

token The connection token return The status of the requestIdrequestId The requestId number to retrieve


404 109 Request not already processed or incorrect. Please try again later

REST Example

Input

URL

https://{server}/sms-transactional-ws/request/requestId1

Header




Transactional SMS Messaging API GuideGet Status of RequestId


Output

Status

200 OK

Body

{"requestId":"requestId1","sendStatus":"WAITING","cellPhone":33607480674,"requestDate":"2013-12-15T02:20:20.000+0000"

}


Transactional SMS Messaging API GuideGet Status of RequestId


Get Aggregate ReportsThis 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

URL


Header



Data Center Server





REST URL

https://{server}/sms-transactional-ws/reports/aggregate/sms

Inputparameter

Requiredparameters


token The connection token returnThe aggregate report oftransactional SMS messages sentduring the period

startDate

The start date of the date range.

The date format follows the ISO 8601 rules where date andtime values are ordered from the most to the least significant.

Example:

l 2013-04-05l 2013-04-05+02:00l 2013-04-05T10:20:58l 2013-04-05T10:20:58+02:00

Note: It is highly recommended to always include the timezone. If the time zone is omitted, the SmartFocus servertime zone will be used.


Transactional SMS Messaging API GuideGet Aggregate Reports


Inputparameter

Requiredparameters


endDate

The end date of the date range. If the end date is omitted, the24 hours following the start date will be retrieved.

The date format follows the ISO 8601 rules where date andtime values are ordered from the most to the least significant.

Example:

l 2013-04-05l 2013-04-05+02:00l 2013-04-05T10:20:58l 2013-04-05T10:20:58+02:00

Note: It is highly recommended to always include the timezone. If the time zone is omitted, the SmartFocus servertime zone will be used.


400 103 Invalid parameter400 107 Search criterias required or invalid400 108 The end date is before the start date403 003 Access denied.

REST Example

Input

URL

https://{server}/sms-transactional-ws/reports/aggregate/sms?startDate=2013-12-19T13:23:23-11:00&endDate=2013-12-20T13:23:23-11:00

Header



Output

Status

200 OK

Body

{"smsDelivered":10,"smsTotal":13,"smsNotDelivered":{

"smsSentToOperator":1,"smsNotDeliveredTotal":3,




"smsSoftBounce":1,"smsHardBounce":1

}}




Get Detailed ReportsThis method is used to retrieve the detailed reports of transactional SMS messages sent to each cellphone number within aspecified period.

This is a GET method.

REST WADL

URL


Header



Data Center Server





REST URL

https://{server}/sms-transactional-ws/reports/details/sms

Inputparameter

Requiredparameters


token The connection token returnThe detailed report of transactionalSMS messages sent to each cellphonenumber during the period

startDate

The start date of the date range.

The date format follows the ISO 8601 rules where dateand time values are ordered from the most to the leastsignificant.

Example:

l 2013-04-05l 2013-04-05+02:00l 2013-04-05T10:20:58l 2013-04-05T10:20:58+02:00

Note: It is highly recommended to always include thetime zone. If the time zone is omitted, the SmartFocusserver time zone will be used.


Transactional SMS Messaging API GuideGet Detailed Reports


Inputparameter

Requiredparameters


endDate

The end date of the date range. If the end date isomitted, the 24 hours following the start date will beretrieved.

The date format follows the ISO 8601 rules where dateand time values are ordered from the most to the leastsignificant.

Example:

l 2013-04-05l 2013-04-05+02:00l 2013-04-05T10:20:58l 2013-04-05T10:20:58+02:00

Note: It is highly recommended to always include thetime zone. If the time zone is omitted, the SmartFocusserver time zone will be used.

page The page to returnperPage The number of items to return per page


400 103 Invalid parameter400 107 Search criterias required or invalid400 108 The end date is before the start date403 003 Access denied.

REST Example

Input

URL

https://{server}/sms-transactional-ws/reports/details/sms?startDate=2013-12-19T13:23:23-11:00&endDate=2013-12-20T13:23:23-11:00&page=1&perPage=2

Header



Output

Status

200 OK

Header




Link: <https://{server}/sms-transactional-ws/reports/details/sms?startDate=2013-12-13T07:19:45%2B02:00&page=1&endDate=2014-12-14T21:19:45%2B02:00&perPage=1>; rel="first",<https://{server}/sms-transactional-ws/reports/details/sms?startDate=2013-12-13T07:19:45%2B02:00&page-e=2&endDate=2014-12-14T21:19:45%2B02:00&perPage=1>; rel="prev",<https://{server}/sms-trans-actional-ws/reports/details/sms?startDate=2013-12-13T07:19:45%2B02:00&page=4&endDate=2014-12-14T21:19:45%2B02:00&perPage=1>; rel="next",<https://{server}/sms-transactional-ws/re-ports/details/sms?startDate=2013-12-13T07:19:45%2B02:00&page=5&endDate=2014-12-14T21:19:45%2B02:00&perPage=1>; rel="last"Total-Count: 2

Body

[{

"cellphone":33607480674,"aggregateReport":{

"smsDelivered":2,"smsNotDelivered":{

"smsHardBounce":0,"smsSoftBounce":1,"smsSentToOperator":1,"smsNotDeliveredTotal":2

},"smsTotal":4

}},{

"cellphone":33612233444,"aggregateReport":{

"smsDelivered":1,"smsNotDelivered":{

"smsHardBounce":0,"smsSoftBounce":1,"smsSentToOperator":1,"smsNotDeliveredTotal":2

},"smsTotal":3

}}

]




Reference

WADLThe Web Application Description Language (WADL) is a machine-readable XML-based languagethat provides a model for describing HTTP-based web applications (such as REST web services).

Web ServicesThe W3C defines a Web service as a software system designed to support interoperableMachine to Machine interaction over a network. Web services are frequently just Web APIs thatcan be accessed over a network, such as the Internet, and executed on a remote system hostingthe 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 messagesthat follow the SOAP-standard. Common in both the field and the terminology is the assumptionthat there is also a machine readable description of the operations supported by the server, adescription in the WSDL. The latter is not a requirement of SOAP endpoint, but it is a pre-requisite for automated client-side code generation in the mainstream Java and .NET SOAPframeworks. Some industry organizations, such as the WS-I, mandate both SOAP and WSDL intheir definition of a Web service.

WSDLThe Web Services Description 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 hasnot been endorsed by the World Wide Web Consortium (W3C). Version 2.0, for which severaldrafts have been released, is expected to become a W3C recommendation. WSDL is an XML-based service description on how to communicate using web services. The WSDL defines ser-vices as collections of network endpoints, or ports. WSDL specification provides an XML formatfor documents for this purpose. WSDL is often used in combination with SOAP and XML Schemato provide web services over the Internet. A client program connecting to a web service canread the WSDL to determine what functions are available on the server. Any special datatypesused are embedded in the WSDL file in the form of XML Schema. The client can then use SOAPto actually call one of the functions listed in the WSDL.

XMLThe Extensible Markup Language (XML) is a W3C-recommended general-purpose markup lan-guage. The XML recommendation specifies both the structure of XML, and the requirements forXML processors. XML is considered "general-purpose" because it enables anyone to originateand use a markup language for many types of applications and problem domains. Numerousformally 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 facil-itate the sharing of data across different information systems, particularly systems connectedvia the Internet. It is a simplified subset of Standard Generalized Markup Language (SGML), andis designed to be relatively human-legible.


Transactional SMS Messaging API GuideReference


Documents

Transactional SMS Messaging API Guide - REST · Introduction AboutThisDocument ThisdocumentisareferencedocumentforusingSmartFocusAPIs.ItdoesnotexplainthepurposeorfunctionsofSmartFocus