Sei sulla pagina 1di 21

SMSGH Unity Platform API Integration

Guide:

Overview
The 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 Types
Apps 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 Start
1. Create an SMSGH Unity Account
1. Signup for a free Unity Account
2. 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 Channel
3. 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. Integrate
5. 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 App
7. 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 Application
The Unity API supports three types of applications Private, Public, and Partner applications.
The table below gives an overview of the types of applications:
Notes Authentication
Private
Applications
1. Can access resources on
only one Unity Account
2. Useful on only App owners
Unity Account
3. Used by Custom
Applications
1. URL Authentication
2. Basic Authentication
Public
APPLICATIONS
1. Self-Installed Applications
2. 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 Apps
3. Receives Refresh
Authorization Tokens
1. OAuth 2.0


Application Setup
All 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 API
2. Removing an existing app
3. Regenerating the Client ID / Client Secret keys.
4. Updating the details of a registered app.
Registering a New App
To 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.

Properties
Name: 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 Details
Clicking 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.

Properties
Name: 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.
Client ID * The Client ID for authenticating API requests
CLiENT Secret * The Client Secret for authenticating requests
EVENT 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 Applications
Overview
Private apps have access to only the owners 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.
Authentication
Private 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 Applications
Overview
Public 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.
Authentication
Applications 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 users
account. For example an application can only be given access to read a users 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 OAuth
A 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 apps 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 Applications
Your 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 Registration
2. 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 information
4. Click save when you are done to complete the process. Make sure that you check the Public
App option.
Public Application Properties
Name: Details
Public 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 applications 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 Apps
Your 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 Applications
Partner 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 2
The process by which a user authorizes your app is identical to the web flow for public apps. The only
difference is that your apps default callback URL will receive a refresh token as well as the access token.
Partner Requirements
Partner 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 Properties
Name: Details
App Access URL Your applications 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 Menu
Large 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 applications terms of service. This will be shown to users prior to
them authorizing your app.
Privacy Policy URL Your applications 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
Address
Your email address.
Publisher Address Your physical address.
Publisher Logo URL Your company logo.


Setting up OAuth 2.0 Access for Your Application
Setting 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.
Tokens
OAuth 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 Code
An 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 Token
The 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 Token
Refresh 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 Errors
Your 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: Description
error The error code or short name
error_description A detailed description of the error.

Common Errors:
Error: Detail
Invalid 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-Authorizations
Users 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 apps 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_deauthorize
The URL above is an example substituting your actual URL.
Parameters
Name Type Description
access_token string Your applications access token.


Authorizing Web Server Based Applications - OAuth 2.0 Web Server Flow
In order for third-party web applications to get access to a Unity users 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.
Client Application SMSGH Unity API
Resource Server
SMSGH Unity Portal (Authorization
Server)
User
1. Request Service
2. Redirect
3. Authorize
4. Redirect with Authorization Code
5. Request Access Token
6. Request Data
7. Response

1. User will click on a click to connect to the users 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 dont have
a valid token for the app. For users who do already have a valid
token for the app, the user wont 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 applications
2. 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 Description
code 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 Description
client_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 Description
access_token string The new access token
refresh_token string The new refresh token. Only partner applications will receive a
refresh_token
expires_in string The access token expiry time in seconds
scope string The list of granted scopes
token_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 Flow
Mobile, 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.
Client Application SMSGH Unity API
Resource Server
SMSGH Unity Portal (Authorization
Server)
1. Request Token
2. Authorize
3. Redirect with Authorization Code
4. Request Data

1. In this flow, the user will click on a click to connect to the users 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 dont have
a valid token for the app. For users who do already have a valid
token for the app, the user wont 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 applications
2. code: Use code for web or other secure applications
The 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 Description
access_token string The new access token
expires_in string The access token expiry time in seconds
scope string The list of granted scopes
token_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 Scopes
By 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 Description
account.balance Account: Know your account balance
account.details Account: Retrieve your account details
account.invoices Account: Read all invoices associated with your account
account.settings Account: Modify your account's preferences
account.topup Account: Top-up your account
campaigns.assignkeyword Campaigns: Assign a keyword for a campaign
campaigns.create Campaigns: Create a new campaign
campaigns.delete Campaigns: Delete a campaign
campaigns.edit Campaigns: Edit a campaign
campaigns.read Campaigns: Read your campaign information
campaigns.setdefaultemail Campaigns: Set a default email forwarding address for a campaign
campaigns.setdefaultreply Campaigns: Set a default text message reply for a campaign
campaigns.setdynamicurl Campaigns: Set a URL source for a campaign
campaigns.setforwardtomobile Campaigns: Set a mobile number for a campaign
campaigns.setforwardtosmpp Campaigns: Set an SMPP address for a campaign
contacts.create Contacts: Create a contact for your account
contacts.delete Contacts: Delete your account's contact(s)
contacts.edit Contacts: Modify your account's contact(s)
contacts.read Contacts: Read your account contacts
groups.create Groups: Create a group on your behalf
groups.delete Groups: Delete a group from your account
groups.edit Groups: Edit your account groups
groups.read Groups: Read your account groups.
keywords.create Keywords: Create a keyword
keywords.delete Keywords: Delete a keyword
keywords.edit Keywords: Edit a keyword
keywords.read Keywords: Read your keywords
messages.read Messages: Read your messaging history
messages.send Messages: Send SMS for your account
msgtemplate.delete Message Templates: Delete a message template from your account
msgtemplates.create Message Templates: Create a new message template
msgtemplates.delete Message Templates: Delete your message template(s)
msgtemplates.edit Message Templates: Edit your message template(s)
msgtemplates.read Message Templates: Read your message templates
numberplans.create Number Plans: Create a number plan
numberplans.delete Number Plans: Delete a number plan
numberplans.edit Number Plans: Edit a number plan
numberplans.read Number Plans: Read your number plans
offline_access Account: Access your account even when you are logged out of the
system
senderids.create Sender ID: Create sender ids on your behalf
senderids.delete Sender ID: Delete one or more sender ids in your account
senderids.edit Sender ID: Edit a sender id in your account
senderids.read Sender ID: Retrieve your sender IDs

Potrebbero piacerti anche