SMSGH Unity Platform API Integration Guide:

OverviewThe Unity API is a RESTful HTTP web service and uses the various protocols to authenticate third-party applications. It currently supports URL authentication, Basic authentication, and OAuth 2.0 Protocols.

The API exposes messaging and other related functions of the main SMSGH Unity platform and can be used for a variety of purposes such as sending bulk Sms, receiving inbound Sms to, to managing your short code subscriptions and setting up actions on your premium Sms campaigns.

App TypesApps can consume the Unity API in various ways that suit the needs of the application. The App Types guide will describe further how each of these app types are supported by the Unity API.

Quick Start1. Create an SMSGH Unity Account

1. Signup for a free Unity Account2. Add your App to your account. This will give you a Client ID and a Client Secret. You require this

combination in order to use the API.

 2. Get a Communication Channel3. Use the Buy Credit option to purchase some messaging credit.4. You may need to buy a Number Plan (phone number for receiving messages) if required by your

application.

3. Integrate5. Check out our Github Repository for SDKs and Sample code.6. Refer to our documentation and ask Customer Support if you have issues.

4. Publish your App7. Publish your app on our directory, and we will promote your app to all our users.8. You can read reviews on your app.

Types of ApplicationThe Unity API supports three types of applications Private, Public, and Partner applications.

The table below gives an overview of the types of applications:

Notes AuthenticationPrivate Applications

1. Can access resources on only one Unity Account

2. Useful on only App owner’s Unity Account

3. Used by Custom Applications

1. URL Authentication2. Basic Authentication

Public APPLICATIONS

1. Self-Installed Applications2. App can access resources on

multiple Unity Accounts.3. Requires re-authorization by

user every 30 days.4. Does not receive a Refresh

Authorization token.

1. OAuth 2.0

Partner Applications

1. Apps Installed through App Directory

2. Self-Installed Apps3. Receives Refresh

Authorization Tokens

1. OAuth 2.0

Application SetupAll applications start their life cycle as Private Applications. The basic requirement for integration is the Client ID/Client Secret combination.

Applications are created from the API Access Screen

From this screen you have the option of:

1. Registering a new App that will consume the API2. Removing an existing app3. Regenerating the Client ID / Client Secret keys.4. Updating the details of a registered app.

Registering a New AppTo set up a new app, click on “Register an App” in the options panel on the API Access screen. This action will display the app registration screen for you to supply the basic app details.

Clicking save will register the app and create the Client ID / Client Secret combination you require to authenticate you API requests.

PropertiesName: Details

Description A general description for this app. While this is not required, we strongly advise that you provide this. This description is not necessarily the same name as the App.

API Type We provide multiple endpoints for integration. SMPP only provides a messaging level integration, and is only useful for private applications. Our SMPP API documentation gives more details on SMPP integration.

Viewing and Editing App DetailsClicking on Details in the Api Access screen brings up the Edit App Registration screen. You can modify the details of the app here, and copy the Client ID / Client Secret from here.

You can also set up the details of public and partner applications from here.

PropertiesName: DetailsDescription A general description for this app. While this is not required, we strongly

advise that you provide this. This description is not necessarily the same name as the App.

Client ID * The Client ID for authenticating API requestsCLiENT Secret * The Client Secret for authenticating requestsEVENT CALLBACK URL: Events on your account will be pushed to this URL. Only events related to

requests on this App registration will be posted to this URL. To set up a global event callback, use the notification tab on the Account Preferences page.

API Type We provide multiple endpoints for integration. SMPP only provides a messaging level integration, and is only useful for private applications. Our SMPP API documentation gives more details on SMPP integration.

Private ApplicationsOverviewPrivate apps have access to only the owner’s Unity account. You can create an unlimited number of private applications on your account.

Private applications are useful if your application will only access resources on your Unity account. Private applications have access to all resources on your Unity account.

AuthenticationPrivate apps are authenticated by the Client ID / Client Secret combination using:

HTTP Basic Authentication:You authenticate your request by using your client ID as username, and client secret as password.

URL Authentication:You authenticate by requesting the API endpoint with the ClientID=<#####> and ClientSecret=<#####> url parameters.

Public ApplicationsOverviewPublic applications have the ability to access resources on other Unity accounts. Public apps are useful for services that complement the features of Unity. Public apps use standard OAuth 2.0 authorization process to have access to Unity account resources. In general if you have an application that will be using multiple applications, we recommend that you use OAuth 2.0.

AuthenticationApplications that need to access resources on behalf of another user should use OAuth. HTTP basic authentication, and URL authentication would require the users of an application to provide their own Client ID and Client Secret combinations: most users would simply not be able to provide this information.

OAuth uses tokens to authorize an application on behalf of a user. It provides two main features:

Restricted Access: OAuth has been described a valet key for the web. A valet key allows the valet to drive a car, but the valet key cannot be used to open the trunk or glove compartment of the car. The same way, OAuth gives a client application access to restricted resources on a user’s account. For example an application can only be given access to read a user’s contacts, but not be able to alter the contacts. Providing a username and password, would however enable an app to fully impersonate a user account, and could lead to serious problems with security as well as requiring the application to be informed of every password change.

Revokable Access: A user can at any time remove the access given by an application. This can be done for each individual application without affecting other applications that the user has authorized.

Establishing a Connection to Unity API via OAuthA user must grant your application permission to her Unity account before the application can access the API on behalf of that user. This is achieved using an OAuth 2.0 web flow.

1. The user clicks on “Install Application” or “Connect to SMSGH” or a similar button in your application.

2. The user is redirected to SMSGH Unity Portal, and they may be prompted to log in if they are not logged in.

3. The user will then be redirected to a grant access where your application will inform the user of the required permissions, and invite the user to accept the access request.

4. Once your app is authorized, the user will be redirected to your app’s Access URL.5. Users can remove authorization for your app from their account settings page.

OAuth 2.0 makes extensive use of the following tokens:

1. Access Token – These tokens are valid for 30 days by default.2. Refresh Token (Public Apps do not receive refresh tokens. To receive a refresh token, you must

publish your app as a partner application.)

The tokens must be kept secure and should not be shared under and circumstances.

Registering Public ApplicationsYour public application will being its life as a private application. The you provide the details for making it a public application by completing the settings on the public applications tab.

1. Register you app as a private application as shown in Application Registration2. Go to the API Access screen and click on details link for the app. This will show you the current

details of the application.

3. Switch to the Public App Details tab and provide the required information4. Click save when you are done to complete the process. Make sure that you check the “Public

App” option.

Public Application PropertiesName: DetailsPublic App Check this option to indicate that the application is a public application, and

will be using OAuth for its authentication.APP DISPLAY MODE * Indicate if the app will be a Canvas App or a Connected app. More on this

option can be found below.DISPLAY NAME * This is the name of the app as you want users to see it.CALLBACK URL: Your application’s callback URL. This URL will be hit once the user has

authorized your application. Find out more information on the OAuth Implementation Page

Deauthorization Callback:

This URL will be fetched when the user removes authorization for you app. Find out more details on the OAuth Implementation Page.

Application The access requirements for your application. Find out more details on the

Permissions: OAuth Implementation Page.Connected vs Canvas AppsYour apps can be made to sit inside a framed canvas on the Unity Portal. Canvas applications are displayed in a framed canvas, while Connected applications define their own user interface completely independent of the Unity user interface.

Canvas apps can integrate their own menu into the Unity UI main menu. This is very convenient when the user needs to swap applications within one browser window.

Both types of applications can fully consume the Unity API and its resources.

Partner ApplicationsPartner apps are public applications that have been published for display on the Unity Portal application directory.

Partner applications indicate a higher degree of trust between SMSGH and the publisher of the application.

Establishing a Connection via OAuth 2The process by which a user authorizes your app is identical to the web flow for public apps. The only difference is that your app’s default callback URL will receive a refresh token as well as the access token.

Partner RequirementsPartner Applications require more details from you (the publisher) and must go through an approval process from SMSGH.

1. You need to register your app a private application.2. Provide the public application details.3. Switch to the Partner Apps details tab and complete to the fullest extent possible.4. Click “Save and Publish” to start the approval process for publishing a partner application.5. SMSGH will then review the published app and approve the application, or revert with a support

ticket if there are any issues to be reolved.

Partner Application PropertiesName: DetailsApp Access URL Your application’s access URL. If the app is a mobile app, this URL must

point to the App Store link for your platform. If your app is multi-platform, then this URL can point to the landing page for selecting a platform.

Category A category for your app to help users find your app in the application directory.

Short Description A brief description of your app. Typically a few sentences describing the key features of your app. Markdown formatting may be used here.

Long Description A more detailed description of your app. You may highlight all the features in your application. Markdown formatting may be used here.

Small Icon URL A 64 by 64 pixel icon for display in the Apps Grid MenuLarge Icon URL A larger logo for your application. It must have a maximum height of 128

pixels. Marketing URL A wonderful URL for your app where you can fully convince the user to get

your app. You may display screenshots, demo videos etc.Terms Of Service URL Your application’s terms of service. This will be shown to users prior to

them authorizing your app.Privacy Policy URL Your application’s privacy policy. This will be shown to users prior to them

authorizing your app.Publisher Name Your company name, or your full name if you are publishing an app as an

individual.Publisher Website Your website address.Publisher Email Your email address.

AddressPublisher Address Your physical address.Publisher Logo URL Your company logo.

Setting up OAuth 2.0 Access for Your ApplicationSetting up your app on the Unity Portal as a Public Application will enable it to make requests to the API using OAuth requests.

In order for your app to fully use OAuth 2 to access the Unity API, you need a firm grasp of the OAuth 2.0 concepts.

TokensOAuth is an authorization protocol that makes heavy use of tokens as a replacement for usernames and passwords. Users would otherwise have to provide your application with a new username and password anytime the passwords were changed. Tokens must be guarded just like how usernames and passwords are guarded.

The following tokens are of importance:

Authorization CodeAn authorization code is a short-lived token created by the authorization server and passed to the client application via the web browser or web view components in some instances of native mobile applications. The client application sends the authorization code to the authorization server to obtain an access token and, a refresh token if your app is a Partner Application.

Access TokenThe access token is used by the client to make authorized requests on behalf of the Unity user. It has a longer lifetime than the authorization code, typically on the order of minutes or hours. When the access token expires, attempts to use it will fail, and a new access token must be obtained. Partner applications can simply use the refresh token to obtain a new access token. Public applications however must go through the OAuth2 web flow.

The access tokens are long-lived for partner applications and will expire every 30 days. Public application access tokens have a much shorter expiration period of 3 hours; and will require the user to log in and re-authorize after expiry.

Refresh TokenRefresh tokens are used to obtain new access tokens. The refresh token may have a much longer validity time. The client application can store the refresh token, using it to periodically obtain fresh access tokens, but should be careful to protect it against unauthorized access, since, it can be repeatedly used to gain access to the resource server.

Refresh tokens may expire or be revoked by the user outside the control of the client application, the client must handle failure to obtain an access token, by passing the user through the entire OAuth 2 flow once again.

The idea of refresh tokens is that if an access token is compromised, because it is short-lived, the attacker has a limited window in which to abuse it.

Refresh tokens, if compromised, are useless because the attacker requires the client id and secret in addition to the refresh token in order to gain an access token.

Handling OAuth ErrorsYour application must be able to handle exceptional scenarios when things go wrong. Errors may happen at both the authorization and token steps. Errors are turned with two attributes:

Attribute: Descriptionerror The error code or short nameerror_description A detailed description of the error.

Common Errors:Error: DetailInvalid Client This error occurs when either the client ID, or client

secret is not valid. It may also occur in cases where you app has been suspended.

Invalid Redirect URLs (Not matching with the default)

The redirect URI does not match what you have set as your default callback.

Access Denied The user has declined access for your application.Invalid Authorization Code / Invalid Refresh Code

The authorization code is either invalid or has been used. The refresh token may also have expired or been revoked by the user.

Bad Request This usually means one or more required parameters is missing from your request.

Handle App De-AuthorizationsUsers may occasionally de-authorize or uninstall your app from their SMSGH Unity account. When this happens, we will notify you by making am HTTP GET request to your De-Authorization Callback URL specified under your app’s public details. This URL will only be called if you have specified it.

When this happens we will make the following request:

GET https://app.example.com/oauth_deauthorizeThe URL above is an example substituting your actual URL.

Parameters

Name Type Descriptionaccess_token

string Your application’s access token.

Authorizing Web Server Based Applications - OAuth 2.0 Web Server FlowIn order for third-party web applications to get access to a Unity user’s account, the application must be authorized using an OAuth web flow. This method depends on the security of you web server. It is assumed that you application will securely store both access tokens and web tokens. The following steps describe how to implement the OAuth 2 web flow.

1. User will click on a click to connect to the user’s SMSGH Unity account.2. Your app must redirect the user to Unity Portal to request authorization as follows

GET https://unity.smsgh.com/oauth

Parameters

Name Type Description

client_id string Required. The API Client ID for your app.

redirect_uri string Required: The URL in your app where users will be sent after authorization.

scope string Required. A space separated list of permissions. If not provided, scope defaults to an empty list of scopes for users that don’t have a valid token for the app. For users who do already have a valid token for the app, the user won’t be shown the OAuth authorization page with the list of scopes. Instead, this step of the flow will automatically complete with the same scopes that were used last time the user completed the flow.

response_type string Required. The type of response expected:1. token: Use token for client or native applications2. code: Use code for web or other secure applications

state string Required: A user-defined string for identifying a particular request. It is sent back as part of the callback. It is useful in protecting against cross-site request forgery attacks. It is important that it is kept secret.

This should display the consent screen as shown below.

3. The user will then grant access to your app by clicking accept on the consent screen.

4. The user will be redirected to your app with the authorization code you can use to obtain an access token as follows:

GET https://app.example.com/oauth_callback The URL above will be the same as the redirect URL in step 2 above.

Parameters

Name Type Descriptioncode string The authorization code you will use to get an access token.state string The same state value you sent in step two above. You must ensure that the state

values in both steps match.

5. Your must then exchange the authorization code for an access token as follows:

POST https://unity.smsgh.com/oauth/token

Parameters

Name Type Descriptionclient_id string Required. The API Client ID for your app.client_secret string Required. The API Client Secret for your app.code string Required. The authorization code your app received in step 4.redirect_uri string Required. grant_type string Required. Indicates the type of token/code being used to get the access

token. Options are:authorization_code: Specified if you are using an authorization code to get an access token. It may only be used once.refresh_token: Specified if you are using a refresh token to get an access_token. It may be used at any time to get an access token.

Response

Name Type Descriptionaccess_token string The new access tokenrefresh_token

string The new refresh token. Only partner applications will receive a refresh_token

expires_in string The access token expiry time in secondsscope string The list of granted scopestoken_type string The type of token that has been supplied. Typically, a bearer token.

The server will respond to the type of accept header you send by returning the appropriate format. By default the data is returned as application/x-www-form-urlencoded. The server will also return application/json and application/xml if those accept headers are sent.

6. You can then use the access token to access the Unity API. The access token allows you application to make requests on behalf of the user.

You pass the access token into the request as an Authorization header with the bearer scheme as follows:

Authorization: bearer <access_token>

7. Your app must the handle the response from the API in the intended way.

Authorizing Client Apps (JavaScript or Native Apps) - OAuth 2.0 Client Application FlowMobile, Desktop, and JavaScript browser applications cannot guarantee the security of a common client secret, thus a different method must be used to ensure a secure exchange of data via the API.

1. In this flow, the user will click on a click to connect to the user’s SMSGH Unity account.Your app must redirect the user to Unity Portal to request authorization as follows:

GET https://unity.smsgh.com/oauth

Parameters

Name Type Description

client_id string Required. The API Client ID for your app.

redirect_uri string Required: The URL in your app where users will be sent after

authorization.

Scope string Required. A space separated list of permissions. If not provided, scope defaults to an empty list of scopes for users that don’t have a valid token for the app. For users who do already have a valid token for the app, the user won’t be shown the OAuth authorization page with the list of scopes. Instead, this step of the flow will automatically complete with the same scopes that were used last time the user completed the flow.

response_type string Required. The type of response expected:1. token: Use token for client or native applications2. code: Use code for web or other secure applicationsThe response_type in this flow should be token.

State string Required: A user-defined string for identifying a particular request. It is sent back as part of the callback. It is useful in protecting against cross-site request forgery attacks. It is important that it is kept secret.

This should display the consent screen as shown below.

2. The user will then grant access to your app by clicking accept on the consent screen.

3. Instead of the user being redirected to the call back URL, a redirect is returned containing the access token and other parameters in a URL fragment (example: http://myurl#access_token=<token>&state=<state>). Parameters being passed in a URL fragment means the parameters will not be passed on to any web server.

Parameters:

Name Type Descriptionaccess_token string The new access token

expires_in string The access token expiry time in secondsscope string The list of granted scopestoken_type string The type of token that has been supplied. Typically, a bearer token.state string The same state parameter supplied in the authorization request.

4. You can then use the access token to access the Unity API. The access token allows you application to make requests on behalf of the user.

You pass the access token into the request as an Authorization header with the bearer scheme as follows:

Authorization: bearer <access_token>

Your app must the handle the response from the API in the intended way.

Unity API OAuth ScopesBy authorizing your application, the user will typically have granted permission to your application to access resources within one or more scopes.

In order for your application to function correctly, the user must grant access to all your requested scopes. The user cannot grant you less than you requested.

There are certain cases where some scopes will implicitly require that other scopes are granted. In this case the required scopes will be automatically added for the user to review and consent when your app is requesting authorization.

Below is a list of scopes available on the Uniy API. This list may change when more resources become available on the API.

As you can see, scope names are formatted as object.action, where “object” referrers to a Unity API data resource, and “action” indicates what can be done on the resource. A more detailed description of each action can be found in our Unity API Objects field guide.

Name Descriptionaccount.balance Account: Know your account balanceaccount.details Account: Retrieve your account detailsaccount.invoices Account: Read all invoices associated with your accountaccount.settings Account: Modify your account's preferencesaccount.topup Account: Top-up your accountcampaigns.assignkeyword Campaigns: Assign a keyword for a campaigncampaigns.create Campaigns: Create a new campaigncampaigns.delete Campaigns: Delete a campaigncampaigns.edit Campaigns: Edit a campaigncampaigns.read Campaigns: Read your campaign informationcampaigns.setdefaultemail Campaigns: Set a default email forwarding address for a campaigncampaigns.setdefaultreply Campaigns: Set a default text message reply for a campaigncampaigns.setdynamicurl Campaigns: Set a URL source for a campaigncampaigns.setforwardtomobile Campaigns: Set a mobile number for a campaigncampaigns.setforwardtosmpp Campaigns: Set an SMPP address for a campaigncontacts.create Contacts: Create a contact for your accountcontacts.delete Contacts: Delete your account's contact(s)contacts.edit Contacts: Modify your account's contact(s)contacts.read Contacts: Read your account contactsgroups.create Groups: Create a group on your behalfgroups.delete Groups: Delete a group from your accountgroups.edit Groups: Edit your account groupsgroups.read Groups: Read your account groups.keywords.create Keywords: Create a keywordkeywords.delete Keywords: Delete a keywordkeywords.edit Keywords: Edit a keywordkeywords.read Keywords: Read your keywordsmessages.read Messages: Read your messaging history

messages.send Messages: Send SMS for your accountmsgtemplate.delete Message Templates: Delete a message template from your accountmsgtemplates.create Message Templates: Create a new message templatemsgtemplates.delete Message Templates: Delete your message template(s)msgtemplates.edit Message Templates: Edit your message template(s)msgtemplates.read Message Templates: Read your message templatesnumberplans.create Number Plans: Create a number plannumberplans.delete Number Plans: Delete a number plannumberplans.edit Number Plans: Edit a number plannumberplans.read Number Plans: Read your number plansoffline_access Account: Access your account even when you are logged out of the

systemsenderids.create Sender ID: Create sender ids on your behalfsenderids.delete Sender ID: Delete one or more sender ids in your accountsenderids.edit Sender ID: Edit a sender id in your accountsenderids.read Sender ID: Retrieve your sender IDs