Developer Garden REST API

Developer Garden REST API
REST API version 5.2.0
Generated by Doxygen 1.8.5
Mon Aug 11 2014 10:01:21
Contents
1
2
3
4
Introduction
1
1.1
Objective
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1
1.2
Document Change History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1
1.3
Feedback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1
1.4
Copyright . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2
Developer Garden Basics
3
2.1
Create Account . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3
2.2
Activate Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4
2.3
Top-Up and Credit Transfer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4
2.4
Create and use a Developer Garden App . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4
2.5
SDK vs Direct Invocation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6
2.6
Service Environments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6
2.7
Quota . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
7
2.8
Account Based Service Use . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
7
2.9
Reference: Global Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
7
2.10 Phone Number Formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8
2.11 Date Formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8
REST API Basic Usage
9
3.1
Request Formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
9
3.1.1
JSON Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
9
3.1.2
XML Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
10
3.1.3
Plaintext Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
10
Authentication via OAuth 2.0
13
4.1
Background on Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
13
4.2
OAuth 2.0 Clientflow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
13
4.2.1
Authorization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
13
Clientflow Authentication Sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
14
4.3.1
Request Access Token (client credentials) . . . . . . . . . . . . . . . . . . . . . . . . . .
14
4.3.2
cURL authentication
14
4.3
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
iv
5
6
7
CONTENTS
9
Access Token Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
14
4.3.4
Refresh Access Token . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
15
4.3.5
Revoke Authorization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
15
Service: Administration (Quota)
17
5.1
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
17
5.2
REST Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
17
5.2.1
Request Quota . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
18
5.2.2
Set Quota . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
20
5.2.3
Query Account Balance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
21
5.2.4
Get Charged Amount . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
22
5.3
FAQ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
23
5.4
Reference: Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
23
Service: IP Location
25
6.1
REST Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
25
6.1.1
determine local information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
25
6.2
FAQ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
26
6.3
Reference: Region Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
26
6.4
Reference: Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
28
Service: Phone Number Validation (SmsValidation)
29
7.1
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
29
7.2
REST Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
30
7.2.1
getValidatedNumbers - query list of validated numbers
. . . . . . . . . . . . . . . . . . .
30
7.2.2
sendValidationKeyword - send a validation SMS . . . . . . . . . . . . . . . . . . . . . . .
31
7.2.3
validate - validation of a phone number . . . . . . . . . . . . . . . . . . . . . . . . . . . .
32
7.2.4
invalidate - withdrawal of a validation, termination of a validation process . . . . . . . . . .
33
Reference: Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
33
7.3
8
4.3.3
Service: Send MMS
35
8.1
Features and Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
35
8.2
REST Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
36
8.2.1
sendMMS - send an MMS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
36
8.3
FAQ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
37
8.4
Reference: Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
37
Service: Global SMS
41
9.1
Environmental information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
41
9.2
General Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
41
9.3
Basic Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
42
9.4
API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
42
Generated on Mon Aug 11 2014 10:01:21 for Developer Garden REST API by Doxygen
CONTENTS
v
9.5
Further Knowledge . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
42
9.6
Features and Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
42
9.7
REST Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
44
9.7.1
sendSMS - send an SMS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
44
9.7.2
sendSMS - query the delivery report . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
47
9.7.3
sendSMS - Subscribe to SMS delivery notifications . . . . . . . . . . . . . . . . . . . . .
48
9.7.4
sendSMS - Stop the subscription to SMS delivery notifications . . . . . . . . . . . . . . .
50
9.7.5
Receive SMS sent to your app . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
51
9.7.6
Subscribe to notifications of messages sent to your application . . . . . . . . . . . . . . .
52
9.7.7
Stop the subscription to message notifications . . . . . . . . . . . . . . . . . . . . . . . .
55
9.8
Reference: Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
55
9.9
Related Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
58
10 Service: Speech to Text
59
11 Contact and Support
61
Generated on Mon Aug 11 2014 10:01:21 for Developer Garden REST API by Doxygen
Chapter 1
Introduction
1.1
Objective
The objective of this documentation is to describe the usage of Developer Garden services using the REST API.
It is aimed at developers with prior knowledge in the following areas:
• Programming experience with REST based web services in your favorite language
• Basic knowledge about web services
Note
If there is an SDK for your programming language, it is recommended to leverage it’s functionality instead of
invoking the API directly.
1.2
Document Change History
Date
2014-08-11
2013-11-18
2013-10-12
2013-09-14
2013-07-17
2013-02-22
2012-08-29
2012-07-03
1.3
Changes to the previous version
New version 5.2.0. Conference Call and Voice Call
API removed.
New version 5.1.2. AS24 removed. Corrections &
fixes.
Corrections & fixes.
Corrections & fixes. The search function was
improved.
Corrections & fixes. Added a guide of how to create
an app.
Send SMS 3.0 and OAuth client credential
authentication added.
Add new parameters to Conference Call API
(joinConfirmDialIn and joinConfirmDialOut)
First public version
Feedback
We welcome your suggestions, comments and questions. Visit www.developergarden.com to get up-to-date
information and exchange with other users.
2
1.4
Introduction
Copyright
This user documentation is copyright protected. All rights reserved.
Generated on Mon Aug 11 2014 10:01:21 for Developer Garden REST API by Doxygen
Chapter 2
Developer Garden Basics
Welcome in Developer Garden. This chapter is dedicated to get started with the provided services.
To access Developer Garden services, it is neccesary to create an account first. After relevant services are activated, it is also neccesary to top up the account to access services with costs.
After the above steps it’s the right time to create your first Developer Garden app .
For the different ways of communicating with the service, please refer to SDK vs Direct Invocation. Especially during
development, please note that there are different service environments before switching into "production".
It is also worth knowing that service usage can be monitored and limited with a built-in quota mechanism. Further
dividing expenses to multiple sub-accounts may provide enhanced overview.
Finally, there are references for common status codes and accepted phone number formats. Also the expected date
formats are specified.
Proceed with the first step: Create account
2.1
Create Account
You can do some nice things without an account:
• Investigate the REST API Documentation
• Download SDKs
But there are a lot of things you can only do by using a Developer Garden account:
• Activate API usage
• Manage sub-accounts, top up credits, request bills
• Manage user data / contact
• Create application credentials
• Comment blog articles
• post to our forums
• Manage your developer profile
• Subscribe to newsletter
• Sign up for research panels
4
Developer Garden Basics
How to create a Developer Garden Account
Visit www.developergarden.com and register for a new account. We recommend to activate the newsletter
as well, as valuable updates will be spread occasionally.
You should receive a confirmation mail immediatelly, please follow the instructions to complete the creation of your
account. If you did not receive any mail, consider looking for it in your spam/junk folders as well.
Note
You can manage your applications and services via the new Developer Garden Portal. If you’re already a
Developer Garden user and want to use one of our old SDKs before version 5.0 you must still book and
manage the services via Developer Garden Portal.
2.2
Activate Services
To use the different Developer Garden services, it is neccesary to activate them in the Developer Garden Portal.
Visit Your DG API Management Site and log in with your account credentials. You browser should get
forwarded to the API activation page, providing an overview on currently activated services.
Click on the "Activate" link next to the relevant service - check basic fee and contract duration before completing the
process by selecting "OK". Or, abort activation by selecting "Cancel".
Note
Please note that to use services in production environment, it is neccesary to top up the account at least once.
Otherwise each service call will fail with an "internal error".
2.3
Top-Up and Credit Transfer
Credit management takes place in Developer Garden Portal - Account Management. Log in and
proceed to "Menu -> Account Management".
Top-Up
It is neccesary to top up your account with sufficient credits before using paid services.
If you have multiple subaccounts, select the one to top up and choose "Top-up your account". Follow the instructions.
You will be asked about how many credits to top up and your desired payment method.
After completion, available Euro as shown in Developer Garden Portal have increased by the selected amount
purchased.
Transfer Credits
If you are using multiple accounts, it may be neccesary to transfer credits between two accounts.
At "Transfer credits to" enter the amount of credits to transfer. Select destination account, enter the amount in Euro
and start the process with the button "Transfer".
After completion, the changed points show up in account overview.
2.4
Create and use a Developer Garden App
To create and use a Developer Garden App you need to login to your Developer Garden Account. Then click on My
Account
Generated on Mon Aug 11 2014 10:01:21 for Developer Garden REST API by Doxygen
2.4 Create and use a Developer Garden App
5
In order to create an App you need to Book an API beforehand.
On the left side you will see Application Management and after clicking on it you can see a Add a new
application Link at the very center of your screen.
When clicking on this link you will be prompted to choose between the two types of apps Developer Garden provides:
• DG API
• Telekom Tropo API
Now you can give a name to the API and a description and in case of the DG API give the app rights to use one or
more of your booked services.
To complete the process click Add and you’re ready to use the apps client id and secret for your development
projects.
Generated on Mon Aug 11 2014 10:01:21 for Developer Garden REST API by Doxygen
6
Developer Garden Basics
When you selected Telekom Tropo API you’re prompted to specify if you want to use WebAPI or
Scripting for the Telekom Tropo Service. There is a difference in usage between these two as of WebAPI needs you to host the files yourself, whereas the Scripting API has a built in file hosting for your scripts. You
still can host the scripts yourself when selecting Scripting. You can find out more about this in the Telekom
Tropo FAQ or in the Telekom Tropo Documentation.
2.5
SDK vs Direct Invocation
For convenient access to Developer Garden services, Deutsche Telekom provides SDKs for Java, C#, PHP
Objective-C and Python. The interface is stable as far as possible and there is extensive support for SDK users.
However, if there is no SDK for your programming language, the web service can be accessed directly - there are
two interfaces in SOAP and REST style.
2.6
Service Environments
There are three different environments available for service invocation.
Enviroment specification:
Sandbox:
Generated on Mon Aug 11 2014 10:01:21 for Developer Garden REST API by Doxygen
2.7 Quota
Programming language
Interface stability
Documentation
7
Use of a provided SDK
Supported: Java, C#, PHP,
Objective-C, Python
Stable
SDK method documentation with
working sample code in target
language
Direct addressing
Any language with web service
support (SOAP or REST)
Can be subject to future changes
Web service method
documentation, no sample code
Table 2.1: Comparison: SDK vs Web Service API
Functional scope
Costs
Quota
Production
All services are available
in the full functional
scope
Billing with each use
User and system quota
Sandbox
Some services are not
available or are limited
(e.g., call duration,
number of characters for
an SMS or available
quota)
Free-of-charge use
Mock
The interfaces to the
services are available but
without functionality.
Not applicable
Table 2.2: Comparison of Available Environments
• In SMS sandbox enviroment you can use up to 3 telephone numbers as recipients.
• On the following link you can find further information about the service environments: Environmental information
2.7
Quota
Some services offered are restricted in terms of their usage frequency. A limited number of quota points are available
to a user on any given day. Quota points decrease each time a service is used. If all quota points are exhausted, it
is not possible to further use the relevant service on this day. The quota point status is reset on a daily basis at the
first service invocation.
The current quota status can be queried using the Administration service. To control costs, a user can also define
his or her own user quota which must not be exceeded within a 24 hour period. Please note, that these limits can
not surpass the system limits.
2.8
Account Based Service Use
You can create and manage different, self-defined sub-accounts using the Developer Garden Portal Account Management’s account administration panel. This mechanism can be used for the monitoring and the
finely-granulated control of the service use. It is possible to assign and transfer credit between accounts.
A sub-account has a display name and is identified by it’s unique account ID. Set the account ID with any chargeable
use of the services to specify that this sub-account should be billed. If no account ID is specified, the main account
is billed.
Note
The creation of sub accounts is available only after the first top up.
2.9
Reference: Global Error Codes
Some status codes are common to all services, they can be found in the following table:
Generated on Mon Aug 11 2014 10:01:21 for Developer Garden REST API by Doxygen
8
Developer Garden Basics
Status code
0000
0001
0015
0020
0023
0030
0040
0042
0043
0050
0090
Meaning
The service call was successful. (No error)
An internal error occurred.
The environment is invalid.
No authorization to use the service.
The HTTP Accept header is unknown.
Insufficient quota points.
Token has expired.
Account does not exist or does not belong to user.
The given ID was not found.
Insufficient credit.
Invalid token.
Table 2.3: Common Status and Errror Codes
2.10
Phone Number Formats
When a phone number is specified, the following formats are supported:
• +49-6151-11223344
• 0049615111223344
• 0615111223344
• (06151) 11223344
• +49-6151-OpenDev
In addition to +, - , figures ([0-9]) and letters ([a-zA-Z]), the following characters are accepted in phone
numbers: ()[]/<>-.
If a phone number does not contain a country code (e.g. +49 or 0049), it is automatically enhanced with +49
(Germany).
2.11
Date Formats
When making a call via the API the preferred date format is requested like
2013-12-15
So the format is YYYY-MM-DD.
Generated on Mon Aug 11 2014 10:01:21 for Developer Garden REST API by Doxygen
Chapter 3
REST API Basic Usage
The host / URL prefix for all resources described in this document is https://gateway.developer.telekom.com. The final resource URL consists of prefix + service prefix + resource URI.
E.g., the path to send an SMS would be: https://gateway.developer.telekom.com/plone/sms/rest/productio
The REST API of Developer Garden expects a well-formatted requests, which are shown in Request Formats.
3.1
Request Formats
The authentication token has to be included in the HTTP header at every request, like this:
Authorization: OAuth realm="developergarden.com",oauth_token="KDfueW4OphJ..."
Therefore, a request may look like the following:
POST /plone/odg-voicebutler/rest/production/call HTTP/1.1
Host: gateway.developer.telekom.com
Authorization: OAuth realm="developergarden.com",oauth_token="KDfueW4OphJ..."
Accept: text/xml
Content-Type: application/x-www-form-urlencoded
anumber=%2B491234676378&bnumber=%2B4928373827832%2C%2B4938823723&expiration=10&maxduration=20&maxwait=5&bpriva
Parameters can be encoded either as application/x-www-form-urlencoded (as shown) or as
multipart/form-data. For requests that contain file attachments, only multipart/form-data is
possible.
Depending on the Accept HTTP header field, the answer is formatted differently. The possibilities are shown using
a common example response:
status
statusCode = 0000
statusMessage = Success.
maxQuota = 10
maxUserQuota = 0
quotaLevel = 0
3.1.1
JSON Response
The response data looks like this formatted in application/json
{
"status" : {
10
REST API Basic Usage
"statusCode" : "0000",
"statusMessage" : "Success."
},
"maxQuota":"10",
"maxUserQuota":"0",
"quotaLevel":"0"
}
3.1.2
XML Response
For text/xml, the following rules apply:
• The whole response is represented as a result element.
• Name value pairs are represented as nested elements.
• Characters reserved for XML (like < > ") are converted into their respective XML escape sequences
• Single values are represented as text nodes within the enclosing element.
• Arrays are represented as nested elements. Every item of an array is enclosed by a value element.
• The type of a nested objects is not represented.
• All values are encoded as UTF-8
So the example response will look like this:
<?xml version="1.0"?>
<result>
<status>
<statusCode>0000</statusCode>
<statusMessage>OK</statusMessage>
</status>
<quotaStatus>
<maxQuota>10</maxQuota>
<maxUserQuota>0</maxUserQuota>
<quotaLevel>0</quotaLevel>
</quotaStatus>
</result>
3.1.3
Plaintext Response
For text/plain, the following rules apply:
• The whole response is represented as name value pairs ("name=value"). The name can be prepended by a
prefix. Prefixes are divided by ".".
• Name value pairs are transferred directly into the output.
• Line breaks within values are converted to \r or \n resp. Tab stops are converted to \t.
• Array items are prepended with a prefix, which is named like the property which defines the array.
• An additional property count (of items) is added to every array to easily compute the end of an array.
• Every array item is prepended by a prefix representing its index in the array.
• Nested objects are prepended by a prefix representing the property defining the object. The type of the
nested object i not represented.
• All values are encoded as UTF-8.
The example response will look like this:
Generated on Mon Aug 11 2014 10:01:21 for Developer Garden REST API by Doxygen
3.1 Request Formats
status.statusCode=0000
status.statusMessage=OK
quotaStatus.maxQuota=10
quotaStatus.maxUserQuota=0
quotaStatus.quotaLevel=0
Generated on Mon Aug 11 2014 10:01:21 for Developer Garden REST API by Doxygen
11
12
REST API Basic Usage
Generated on Mon Aug 11 2014 10:01:21 for Developer Garden REST API by Doxygen
Chapter 4
Authentication via OAuth 2.0
This chapter is divided into the following sections:
• Background on Authentication
Authentication method
• OAuth 2.0 Clientflow
Example
• Clientflow Authentication Sample
4.1
Background on Authentication
To access the services, the user must be authenticated against the Deutsche Telekom OAuth service. The procedure is as described below:
• The Client fetches an authentication token from the Deutsche Telekom OAuth service.
• The Client uses the authentication token for subsequent service invocations.
An authentication token is a string that has to be passed as-is to further service calls. Since it has limited validity,
an expiration date is returned as well. How to deal with expired tokens is specific to the selected authentication
method.
Find additional information regarding this topic in the OAuth 2.0 RFC. A detailed description of the client workflow also can be found there.
4.2
OAuth 2.0 Clientflow
The client credentials flow is as simple as described below.
However if you want more details you may contact us or find additional information here.
4.2.1
Authorization
If you want your app to be authorized to access Developer Garden services the sequence is the following:
14
Authentication via OAuth 2.0
• Provide your clientId and clientSecret to the SDK.
• Request an access token
• You’ll receive a response containing an access token AND validity OR an error message
• The access token is used for subsequent service invocations
4.3
Clientflow Authentication Sample
Note
Unlike other Developer Garden services, the Telekom OAuth service does not accept parameters given as
form/multipart. Please make sure use the default content type application/x-www-form-urlencoded
for the requests.
4.3.1
Request Access Token (client credentials)
The access token is fetched with a HTTP request:
REST resource information
HTTP Method
REST URL
POST
https://global.telekom.com/gcp-web-api/oauth
Note
The clientId and clientSecret need to be put as Basic Auth Header to the request.
Parameters
Parameter
grant_type
scope
4.3.2
Meaning
Type of grant request, in this case the fixed value
"client_credentials".
scope is a string shown in your app’s control panel
on the Developer Garden website
cURL authentication
Another way for obtaining your access token is using cURL. The following cURL command will help you:
curl -H "Content-Type: application/x-www-form-urlencoded" -u Client_ID:Client_Secret -X POST --verbose https:/
Bear in mind that you should replace Client_ID with your personal Client ID, Client_Secret with your personal Client
secret. Keep the ":" sign between them because the command will not work properly if it is not there. The last thing
you need to change is the SCOPE at the end of the cURL command. Please put the Scope of the application you
are trying to run.
4.3.3
Access Token Response
The Accept HTTP header field of your requests decides in which format the access token is returned. Each
representation contains the expiration time as "seconds from now".
E.g., the response body for Accept:
application/json looks like:
Generated on Mon Aug 11 2014 10:01:21 for Developer Garden REST API by Doxygen
4.3 Clientflow Authentication Sample
15
{
"access_token":"ECDyMMt2....",
"token_type":"bearer",
"expires_in":"28800",
"scope":"THESCOPE"
}
I.e., the access token is valid for 8 hours.
Other valid Accept types are text/xml and text/plain, the response is then formatted accordingly.
During authentication, the user has the choice to grant permanent access. In this case, the access token respone
contains a refresh token as well:
{
"token_type":"BEARER",
"access_token":"ECDyMMt2....",
"expires_in":"28800",
"refresh_token":"XwAgR0A3....",
"scope":"THESCOPE"
}
The field content of access_token is then used for authorized service calls, see REST API Basic Usage.
4.3.4
Refresh Access Token
If available, the refresh token can be used to fetch a new access token to avoid expiration. This is done with another
HTTP request:
REST resource information
HTTP Method
REST URL
POST
https://global.telekom.com/gcp-web-api/oauth
Parameters
Parameter
client_id
Meaning
Type of grant request, in this case the fixed value
"refresh_token".
Your application’s id
refresh_token
The previous refresh token
scope
scope is a string shown in your app’s control panel
grant_type
on the Developer Garden website
This request returns a new access token and another refresh token that can be used for subsequent refresh requests.
4.3.5
Revoke Authorization
The user may decide to revoke a previously given authorization. This effectively marks the refresh token as invalid
in Telekom servers.
To revoke, issue another HTTP request:
REST resource information
Generated on Mon Aug 11 2014 10:01:21 for Developer Garden REST API by Doxygen
16
HTTP Method
REST URL
Authentication via OAuth 2.0
POST
https://global.telekom.com/gcp-web-api/oauth/revoke
Parameters
Parameter
client_id
Meaning
Your application’s id
token
The refresh token that you want to invalidate
Generated on Mon Aug 11 2014 10:01:21 for Developer Garden REST API by Doxygen
Chapter 5
Service: Administration (Quota)
This chapter is divided into the following sections:
• Introduction
API
• REST Methods
Further Knowledge
• FAQ
• Reference: Error Codes
5.1
Introduction
The Administration service enables to query remaining quota points of the other services. Additionally, user quotas
can be defined.
See also: Quota and Account Based Service Use
5.2
REST Methods
All resources are located under the common base path /p3gw-mod-odg-admin/rest/{environment},
where {environment} is one of "production", "sandbox" or "mock" - see Service Environments.
The content type of the requests has to be application/form-url-encoded and application/json will not work. Request
always return responses in JSON format.
The following methods are available:
• Request Quota
• Set Quota
• Query Account Balance
• Get Charged Amount
18
5.2.1
Service: Administration (Quota)
Request Quota
REST resource information
Generated on Mon Aug 11 2014 10:01:21 for Developer Garden REST API by Doxygen
5.2 REST Methods
19
HTTP Method
REST URI
GET
/quotainfo/{moduleID}
Path element
Meaning
/quotainfo
/{moduleID}
Identification for service and environment:
• "GlobalSmsSandbox": Global SMS, sandbox
environment
• "GlobalSmsPremium": Global Send SMS,
production environment
• "MmsProduction": Send MMS, production
environment
• "MmsSandbox": Send MMS, sandbox
environment
• "IPLocationProduction": IP Location, production
environment
• "IPLocationSandbox": IP Location, sandbox
environment
Example request
GET https://gateway.developer.telekom.com/p3gw-mod-odg-admin/rest/production/quotainfo/GlobalSmsPremium
HTTP/1.1
Host: gateway.developer.telekom.com
Authorization: OAuth realm="developergarden.com", oauth_token="ECDyMMt2...."
Return values
Field
status
Meaning
Status information
statusCode
status code, see Reference: Error Codes
statusMessage
Status message
maxQuota
System-defined limit of maximum quota points that
can be consumed per day.
This system quota cannot be exceeded by the user
quota ( maxUserQuota).
maxUserQuota
User-defined limit of maximum quota points that can
be consumed per day.
This user quota cannot exceed the system quota (
maxQuota).
Generated on Mon Aug 11 2014 10:01:21 for Developer Garden REST API by Doxygen
20
Service: Administration (Quota)
quotaLevel
Number of quota points consumed today.
Example response
HTTP/1.1 200 OK
Content-Type: application/json
Date: Wed, 16 Oct 2013 15:51:06 GMT
{
"status": {
"statusCode": "0000",
"statusMessage": "Success."
},
"maxQuota": "1000000",
"maxUserQuota": "0",
"quotaLevel": "0"}
5.2.2
Set Quota
REST resource information
HTTP Method
REST URI
PUT
/userquota/{moduleID}
Path element
Meaning
/userquota
/{moduleID}
Identification for service and environment:
• "GlobalSmsSandbox": Global SMS, sandbox
environment
• "GlobalSmsPremium": Global Send SMS,
production environment
• "MmsProduction": Send MMS, production
environment
• "MmsSandbox": Send MMS, sandbox
environment
• "IPLocationProduction": IP Location, production
environment
• "IPLocationSandbox": IP Location, sandbox
environment
Parameters
Parameter
value
Meaning
The new maximum available quota per day
Example request
PUT /p3gw-mod-odg-admin/rest/production/userquota/GlobalSmsPremium HTTP/1.1
Host: gateway.developer.telekom.com
Authorization: OAuth realm="developergarden.com",oauth_token=""
Content-Type: application/x-www-form-urlencoded
value=99
Generated on Mon Aug 11 2014 10:01:21 for Developer Garden REST API by Doxygen
5.2 REST Methods
21
Return values
Field
status
Meaning
Status information
statusCode
status code, see Reference: Error Codes
statusMessage
Status message
Example response
{
"status": {
"statusCode": "0000",
"statusMessage": "Success."
}
}
5.2.3
Query Account Balance
REST resource information
HTTP Method
REST URI
POST
/account/balance
Parameters
Parameter
accountID
Meaning
Account ID of the sub-account that should be queried.
(optional)
See: Account Based Service Use
Example request
POST /p3gw-mod-odg-admin/rest/production/account/balance HTTP/1.1
Host: gateway.developer.telekom.com
Authorization: OAuth realm="developergarden.com",oauth_token="eyJhbGci...."
Content-Type: application/x-www-form-urlencoded
Return values
Field
status
Meaning
Status information
statusCode
status code, see Reference: Error Codes
statusMessage
Status message
Generated on Mon Aug 11 2014 10:01:21 for Developer Garden REST API by Doxygen
22
Service: Administration (Quota)
accounts[]
account
credits
List of sub-accounts
Account ID of a sub-account
Account balance of the sub-account
Example response
{
"status": {
"statusCode": "0000",
"statusMessage": "Success."
},
"accounts": [
{
"account": "121927",
"credits": "10000"
},
{
"account": "258200",
"credits": "0"
}
]
}
5.2.4
Get Charged Amount
REST resource information
HTTP Method
REST URI
GET
/charge/{ID}
Path element
Meaning
/charge
/{ID}
Parameters
Parameter
accountID
Meaning
Account ID of the sub-account that has been billed for
the call. If the parameter is not specified, the main
account is selected. (optional)
See: Account Based Service Use
Example request
GET /p3gw-mod-odg-admin/rest/production/charge/dbcc5bb6-47a5.... HTTP/1.1
Host: gateway.developer.telekom.com
Authorization: OAuth realm="developergarden.com",oauth_token="eyJhbGciO...."
Content-Type: application/x-www-form-urlencoded
Return values
Generated on Mon Aug 11 2014 10:01:21 for Developer Garden REST API by Doxygen
5.3 FAQ
23
Field
Meaning
Status information
status
statusCode
status code, see Reference: Error Codes
statusMessage
Status message
Cost amount of the requested call
charge
Example response
{
"status": {
"statusCode": "0000",
"statusMessage": "Success."
},
"charge": "392"
}
5.3
FAQ
Q: The service returns "invalid quota value" when trying to set a quota value of 0.∗
A: Although the user quota defaults to 0, it is not possible to set it back to 0 from a different value. Please use the
system limit as value to remove the user limitation.
Q: The call to get the charged amount fails because the ID was not found, although it is correct.∗
A: Please make sure that you have set the correct account ID as well. Also, the data is not available before 15
minutes after the end of the call.
5.4
Reference: Error Codes
Status code
HTTP code
0060
403
0075
404
0100
400
Meaning
The quotes are selected
by the user is too high or
too low.
The moduleId is
invalid.
Invalid value for quota.
See also Reference: Global Error Codes.
Generated on Mon Aug 11 2014 10:01:21 for Developer Garden REST API by Doxygen
Status message
User quota not
allowed.
Invalid module
id.
Invalid quota
value.
24
Service: Administration (Quota)
Generated on Mon Aug 11 2014 10:01:21 for Developer Garden REST API by Doxygen
Chapter 6
Service: IP Location
The IP Location service makes it possible to localize IP addresses from Deutsche Telekom AG’s address space.
API
• REST Methods
Further knowledge
• FAQ
• Reference: Region Codes
• Reference: Error Codes
6.1
REST Methods
All resources are located under the common base path /p3gw-mod-odg-iplocation/rest/{environment},
where {environment} is one of "production", "sandbox" or "mock" - see Service Environments.
This service provides only one method:
• determine local information
6.1.1
determine local information
REST resource information
HTTP Method
REST URI
GET
/location
Parameters
Parameter
ipaddress
Return values
Meaning
Comma separated list of IP adresses, which are to be
located.
26
Service: IP Location
Field
Meaning
Status information
status
statusCode
status code
statusMessage
Status message
Local information for one or more IP addresses.
results[]
ipAddress
The IP address
radius
Field not currently in use.
isInRegion
Regional information about the IP address (optional)
6.2
countryCode
Code of the country the IP address belongs to.
regionCode
Reserved for future use.
regionName
The name of the region (see Reference: Region
Codes)
FAQ
Q: The looked up IP doesn’t produce any results. Why?∗
A: Only IPs from Deutsche Telekom AG’s address space are currently supported by this service.
6.3
Reference: Region Codes
Code
AAC
AUG
BAU
BAY
BBG
BER
BIE
BOC
BON
BRA
BRH
BRM
CHE
COT
DAR
DRE
DSS
DTM
Meaning
Aachen
Augsburg
Bautzen
Bayreuth
Brandenburg
Berlin
Bielefeld
Bochum
Bonn
Braunschweig
Bremerhaven
Bremen
Chemnitz
Cottbus
Darmstadt
Dresden
Düsseldorf
Dortmund
Generated on Mon Aug 11 2014 10:01:21 for Developer Garden REST API by Doxygen
6.3 Reference: Region Codes
DUI
ERF
ESS
FFM
FFO
FLE
FRE
FUL
GER
GIE
GOT
GRW
HAL
HLB
HMB
HNO
KAI
KAR
KAS
KEM
KIE
KLN
KOB
KON
KRE
LEE
LEI
LIN
LUB
MAG
MAI
MAN
MES
MST
MUN
NBB
NBG
OFF
OLD
OSN
PAD
PAS
RGB
ROS
RTW
SIG
SRB
27
Duisburg
Erfurt
Essen
Frankfurt_Main
Frankfurt_Oder
Flensburg
Freiburg
Fulda
Gera
Giessen
Göttingen
Greifswald
Halle
Heilbronn
Hamburg
Hannover
Kaiserslautern
Karlsruhe
Kassel
Kempten
Kiel
Cologne
Koblenz
Konstanz
Krefeld
Leer
Leipzig
Lingen
Lübeck
Magdeburg
Mainz
Mannheim
Meschede
Münster
Munich
Neubrandenburg
Nuremberg
Offenburg
Oldenburg
Osnabrück
Paderborn
Passau
Regensburg
Rostock
Rottweil
Siegen
Saarbrücken
Generated on Mon Aug 11 2014 10:01:21 for Developer Garden REST API by Doxygen
28
Service: IP Location
Stuttgart
Schwerin
Traunstein
Trier
Ulm
Wesel
Würzburg
Wuppertal
STG
SWN
TRA
TRI
ULM
WES
WUB
WUP
6.4
Reference: Error Codes
Status code
HTTP code
0004
400
0093
403
0102
400
0103
200
Meaning
More than the maximum
number of possible IP
addresses have been
entered.
No authorization to use
the service.
An attempt was made to
resolve an IPv6 address.
This is not yet supported.
An unknown IP address
was specified.
Status message
Limit exceeded.
Required
permissions are
missing.
One or more IP
not valid.
One or more IP
cannot be
localized.
See also Reference: Global Error Codes.
Generated on Mon Aug 11 2014 10:01:21 for Developer Garden REST API by Doxygen
Chapter 7
Service: Phone Number Validation (SmsValidation)
This chapter is divided into the following sections:
Basic Information
• Introduction
API
• REST Methods
Further Knowledge
• Reference: Error Codes
7.1
Introduction
The phone number validation services allows to prove ownership of phone numbers. This is neccesary to be able
to use a number as originator in Send SMS and Send MMS services.
Workflow Diagram
The following diagram shows the interaction neccesary to validate a phone number as originator.
30
Service: Phone Number Validation (SmsValidation)
Figure 7.1: Workflow of a Phone Number Validation
7.2
REST Methods
All resources are located under the common base path /plone/odg-sms-validation/rest/{environment},
where {environment} is one of "production", "sandbox" or "mock" - see Service Environments.
• getValidatedNumbers - query list of validated numbers
• sendValidationKeyword - send a validation SMS
• validate - validation of a phone number
• invalidate - withdrawal of a validation, termination of a validation process
7.2.1
getValidatedNumbers - query list of validated numbers
REST resource information
HTTP Method
GET
Generated on Mon Aug 11 2014 10:01:21 for Developer Garden REST API by Doxygen
7.2 REST Methods
REST URI
31
/validatednumbers
Return values
Field
status
Meaning
Status information
statusCode
Status code, see Reference: Error Codes
statusMessage
Status message
numbers[]
A list of already validated phone numbers. in the
format:
• number - The phone number
• validUntil - The end of the validity period.
null if validity is unlimited.
7.2.2
sendValidationKeyword - send a validation SMS
REST resource information
HTTP Method
REST URI
POST
/send
Parameters
Parameter
number
message
Meaning
The number to be validated.
The accompanying message that should be sent with
the validation code. (optional)
This message must contain two placeholders:
• #key#
• #validUntil#.
A sample message is: "The keyword for validating
your phone number with example.com is #key# and is
valid until #validUntil#."
If this parameter is omitted or the placeholders do not
exist, the following German standard message is sent:
"Ihr Validierungsschluessel ist #key#. Er ist gueltig bis
#validUntil#."
Generated on Mon Aug 11 2014 10:01:21 for Developer Garden REST API by Doxygen
32
Service: Phone Number Validation (SmsValidation)
originator
The sender as displayed to the recipient. (optional)
The sender can consist of a maximum of 11
characters. Permitted characters are letters and
numbers. The single use of numbers is not permitted.
account
Account ID of the sub-account that should be billed for
the service use. If the parameter is not specified, the
main account is billed. (optional)
Return values
Field
status
Meaning
Status information
statusCode
Status code, see Reference: Error Codes
statusMessage
Status message
7.2.3
validate - validation of a phone number
REST resource information
HTTP Method
REST URI
POST
/validatednumbers/{number}
Path element
Meaning
/validatednumbers
/{number}
Phone number to validate.
Parameters
Parameter
key
Meaning
The validation code that was sent to the phone
number to be validated.
The format of the code is alphanumeric and six-digit,
such as: A3B5DG
The code becomes invalid after the third incorrect
entry and the phone number is blocked for another
validation for 10 minutes.
The block can be removed if the validation process is
terminated using method invalidate and restarted
using sendValidationKeyword.
Return values
Field
status
Meaning
Status information
Generated on Mon Aug 11 2014 10:01:21 for Developer Garden REST API by Doxygen
7.3 Reference: Error Codes
33
statusCode
Status code, see Reference: Error Codes
statusMessage
Status message
7.2.4
invalidate - withdrawal of a validation, termination of a validation process
REST resource information
HTTP Method
REST URI
DELETE
/validatednumbers/{number}
Path element
Meaning
/validatednumbers
/{number}
Phone number to invalidate or whose validation
process to terminate.
Return values
Field
Meaning
Status information
status
7.3
statusCode
Status code, see Reference: Error Codes
statusMessage
Status message
Reference: Error Codes
Status code
HTTP code
0002
400
0003
400
0005
400
0016
404
0102
401
0103
0104
400
409
0106
200
0107
409
Meaning
The message sent was
too long.
No recipient number was
transferred or none of the
transferred phone
numbers were valid.
No recipient was
transferred or the
recipient was not valid.
The environment is
invalid.
Validation failed.
Invalid number.
The number is not
validated.
The number is already
validated.
A validation has already
started for the specified
phone number.
Generated on Mon Aug 11 2014 10:01:21 for Developer Garden REST API by Doxygen
Status message
Message too
long.
Invalid
recipient.
Invalid sender
name.
The environment
is invalid.
Validation
failed.
Invalid number.
Not validated.
Already
validated.
Validation in
progress.
34
Service: Phone Number Validation (SmsValidation)
0108
409
0109
400
The phone number
cannot be validated as
no validation process has
been started for it.
The phone number to be
validated is blocked.
No validation in
progress.
Given number is
suspended.
See also Reference: Global Error Codes.
Generated on Mon Aug 11 2014 10:01:21 for Developer Garden REST API by Doxygen
Chapter 8
Service: Send MMS
The Send MMS service allows sending MMS messages to mobile phones.
This chapter is divided into the following sections:
Basic Information
• Features and Restrictions
API
• REST Methods
Further Knowledge
• FAQ
• Reference: Error Codes
8.1
Features and Restrictions
Features
• Send MMS with a text, an attachment or both.
• Optionally specify a custom originator phone number. The number requires validation, see Service: Phone
Number Validation (SmsValidation).
• The following MIME content types are supported:
– text/plain
– audio/x-wav
– audio/x-midi
– audio/x-mpeg
– audio/x-pn-realaudio
– image/gif
– image/jpeg
– image/png
– image/tiff
– image/vnd.wap.wbmp
– video/3gpp
36
Service: Send MMS
Restrictions
The following restrictions apply to the use of the Send MMS service:
• MMS can only be sent to German phone numbers.
• It is not possible to specify an originator that is not a phone number.
• If an attachment is to be sent, a content type and a filename must be provided as well.
• The text message must not be longer than 255 characters.
• The subject must not be longer than 40 characters.
• All attachments are sent Base64 encoded and must not be larger than 300kB which results in a limit of about
240kB for the (unencoded) attachment.
• In the sandbox environment, a maximum of 10 MMS can be sent per day.
Special Features in the Mock Environment
There is no mock environment for the Send MMS service.
8.2
REST Methods
All resources are located under the common base path /p3gw-mod-odg-mms/rest/{environment},
where {environment} is one of "production", "sandbox" or "mock" - see Service Environments.
This service provides only a single method:
• sendMMS - send an MMS
8.2.1
sendMMS - send an MMS
REST resource information
HTTP Method
REST URI
POST
/sendMMS
Parameters
Parameter
number
subject
message
Meaning
Recipient phone numbers, separated by commas (",").
See Phone Number Formats.
The subject line.
A text message. (optional)
At least one of the fields, message and
attachment, has to be present.
Generated on Mon Aug 11 2014 10:01:21 for Developer Garden REST API by Doxygen
8.3 FAQ
37
attachment
Base64 encoded attachment to send. (optional)
Attachments of arbitrary type (Picture, Sound, Video,
Text) are supported. The file type has to be specified
through contentType. Furthermore, the file name
has to be specified through filename.
At least one of the fields, message and
attachment, has to be present.
filename
File name of the attachment, if an attachment is to be
sent. (optional)
contentType
File type of the attachment, if an attachment is to be
sent. (optional)
For supported mime types, see Features and
Restrictions.
originator
The sender as displayed to the recipient. (optional)
If not empty, only validated numbers are allowed, see:
Service: Phone Number Validation (SmsValidation).
account
Account ID of the sub-account that should be billed for
the service use. If the parameter is not specified, the
main account is billed. (optional)
See: Account Based Service Use
Return values
Field
Meaning
Status information
status
8.3
statusCode
Status code, see Reference: Error Codes
statusMessage
Status message
FAQ
Q: Do I have to encode the attachment to Base64 on my own?∗
A: It depends. If you are using the SOAP or REST interface directly, you have to. The SDKs for the different
programming languages take care of this step, if not otherwise specified.
8.4
Reference: Error Codes
Status code
HTTP code
Meaning
Status message
0002
400
The message to be sent
is too long.
Message too
long.
Generated on Mon Aug 11 2014 10:01:21 for Developer Garden REST API by Doxygen
38
Service: Send MMS
0003
400
None of the phone
numbers were valid.
(See supported Phone
number formats)
No valid
recipients
given.
0004
400
Too many numbers have
been past.
0005
400
The name of the sender
is invalid.
0006
400
No message was
specified.
Too many numbers
have been passed
(Count: {0}).
The name of the
sender is
invalid.
No valid message
given.
0007
400
The subject is not
specified.
No subject
given.
0008
400
The subject is too long.
0009
400
The recipient is part of
an unsupported
destination network.
0010
400
Some messages could
not be delivered.
0011
400
The attachment is too
big.
Subject too
long.
Recipient is
part of an
invalid
destination
network.
Undelivered
Messages:
Recipients({0})
Attachment too
big.
0012
400
The file name is missing.
0013
400
The content type is
missing
Missing file
name.
Missing content
type.
0014
400
The attachment is not
base64 encoded.
Attachment not
base64 encoded.
0015
400
The file type of the
attachment is not
supported.
Please note that code 15
also occurs if an invalid
environment was
specified.
Invalid content
type
Generated on Mon Aug 11 2014 10:01:21 for Developer Garden REST API by Doxygen
8.4 Reference: Error Codes
0016
39
404
The environment is
invalid.
See also Reference: Global Error Codes.
Generated on Mon Aug 11 2014 10:01:21 for Developer Garden REST API by Doxygen
The environment
is invalid.
40
Service: Send MMS
Generated on Mon Aug 11 2014 10:01:21 for Developer Garden REST API by Doxygen
Chapter 9
Service: Global SMS
The Global SMS service allows sending SMS messages to mobile phones and receive text messages from a
webservice for a specific number.
9.1
Environmental information
As a new feature to Global SMS there are different environments. Each environment must be specified in the URI
of the request.
// for example:
https://gateway.developer.telekom.com/plone/sms/rest/{environment}/ //[...]
Possible environments are:
Environment
premium
mock
sandbox
9.2
Description
Premium production environment with full feature set.
Behaves like premium environment without actually
sending a SMS.
Test environment behaves like production
environment but with limited number of request per
day.
General Features
Feature
Link sender to validated phone number
Alphanumeric source identifier
Description
Do you want to use an existing telephone number to
appear as the sender of the message? It is easy to do
this: just use the validation process to unlock your
desired telephone number or instruct your users to
unlock their own telephone numbers. In My Account
we provide a direct solution to validate numbers.
People who receive SMS messages want to know
who sent them. An individual source identifier
ensures that they always will. 1 to 11 alphanumeric
characters are possible.
42
Service: Global SMS
Long concatenated messages
Delivery report
Flash messages
Binary messages
Unicode messages
9.3
A standard text message contains 160 characters. If
you’ve got more to say, multiple text messages are
simply joined together. This gives you space for up to
765 characters. If a message contains more than 160
characters, it will be split up into a maximum of five
individual SMS messages containing no more than
153 characters each.
Has the message arrived? Our server will deliver the
answer as long as the recipient’s provider supports
this function.
Do you want to display information straight away on
the display of your cell phone? Flash SMS makes this
possible. Messages are shown in a type of pop-up
dialog window and are not permanently saved.
Binary messages allow you to send small images
(such as product or operator logos), ring tones and
configuration files. Messages can contain up to 690
bytes of data. If a message is larger than 140 bytes, it
will be split up into individual messages containing no
more than 134 bytes each.
Send messages that are USC-2 coded. This allows
you to send messages that contain Arabic or Chinese
letters. This gives you space for up to 335 characters.
If a message contains more than 70 characters, it will
be split up into a maximum of five individual SMS
messages containing no more than 67 characters
each.
Basic Information
• Features and Restrictions
9.4
API
• REST Methods
9.5
Further Knowledge
• Reference: Error Codes
• Related Information
9.6
Features and Restrictions
Features
• Send flash SMS that show up on the screen immediatelly (if supported by receiving device)
• Send long SMS up to 765 characters
• Reach multiple recipients with a single service invocation
• Specify originator to display at the recipient
Generated on Mon Aug 11 2014 10:01:21 for Developer Garden REST API by Doxygen
9.6 Features and Restrictions
43
• Specify a phone number as originator (requires validation, see Service: Phone Number Validation (SmsValidation))
• When sending binary SMS make sure to include the User Data Header (also known as UDH).
• The Telekom service number (0191011) can be used as originator at all times. No validation required.
• A senderName can be set, either with a validated number or the Telekom service number. The length of the
senderName ist restricted to 11 characters.
• When using the Telekom service number as originator, tel: may not be attached.
Restrictions
The following restrictions apply to the use of the SMS service:
• An SMS must not be longer than 765 characters, the following characters are counted as two characters: |
∧
C { } [ ] ∼ \ LF (line feed)
• If an SMS is longer than 160 characters, one message is charged for each 153 characters.
• An SMS can be sent to at most 1000 recipients per service call.
• SMS to landline numbers are not supported.
• If an originator is specified, it has to consist of only alphanumeric characters. The maximum length allowed
for alphanumeric originator is 11 characters.
The following restrictions further apply to the sandbox environment:
• Sent SMS are shortened and a note is added. The maximum length of the message to send is 160 characters.
• A maximum of 10 SMS can be sent per day.
Special Features in the Sandbox Environment
In sandbox environment, you can use 0191011 as sender address without attaching the tel:.
Special Features in the Mock Environment
In mock environment, sending SMS messages succeeds with all phone numbers except +49 111111111.
Special Features in Global SMS Receive
• When receiving an SMS with up to 765 characters, the SMS will either be posted to the specified notification
url or if not reachable to our database for a later url post.
Return values for a delivery status
Name
DeliveredToTerminal
Description
successful delivery to Terminal.
Generated on Mon Aug 11 2014 10:01:21 for Developer Garden REST API by Doxygen
44
Service: Global SMS
DeliveryUncertain
delivery status unknown: e.g. because it was handed
off to another network.
unsuccessful delivery; the message could not be
delivered before it expired.
the message is still queued for delivery. This is a
temporary state, pending transition to one of the
preceding states.
successful delivery to the network enabler responsible
for routing the SMS
DeliveryImpossible
MessageWaiting
DeliveredToNetwork
9.7
REST Methods
All resources are located under the common base path /plone/sms/rest/{environment}/smsmessaging/v1/outbou
where {environment} is one of "premium", "sandbox" or "mock". "Premium" is the production environment.
"Sandbox" is testing environment with some limitations and "mock" is used for development. In "sandbox" you
can send SMS while in "mock" our server responds to your request but does not actually send an SMS. For more
information please contact our support team.
All requests are "application/json" requests. The request header "Content-Type" must be set to "application/json".
The corresponding request body must be in JSON format. Request allways return responses in JSON format.
This service provides currently four methods:
• sendSMS - send an SMS
• sendSMS - query the delivery report
• sendSMS - Subscribe to SMS delivery notifications
• sendSMS - Stop the subscription to SMS delivery notifications
• Receive SMS sent to your app
• Subscribe to notifications of messages sent to your application
• Stop the subscription to message notifications
9.7.1
sendSMS - send an SMS
REST resource information
HTTP Method
REST URI
POST
/{senderAddress}/requests
Parameters
Parameter
address
Meaning
Recipient phone numbers as
JSON array, each number must
have the format "tel:+1630000001"
where "+16" is your country code.
Mandatory
true
Generated on Mon Aug 11 2014 10:01:21 for Developer Garden REST API by Doxygen
9.7 REST Methods
45
clientCorrelator
String uniquely identifies this
create SMS request. If there is a
communication failure during the
request, using the same
clientCorrelator when retrying the
request allows the operator to
avoid sending the same SMS
twice.
false
outboundSMSTextMessage.message
Short message content.
exactly one
outboundSMSBinaryMessage.message
xsd:base64Binary short message
content in binary format. This is
not a GSMA-Standard parameter.
exactly one
outboundSMSFlashMessage.flashMessage
Short message content. Will be
send as flash SMS.
exactly one
"outboundSMSFlashMessage": { "flashMessage": "Hello World" }
receiptRequest.notifyURL
URL to which you would like a
notification of delivery sent. The
format of this notification is shown
below.
false
receiptRequest.callbackData
String will be passed back in this
notification, so you can use it to
identify the message the receipt
relates to.
false
senderAddress
String is the address to whom a
responding SMS may be sent
true
senderName
The URL-escaped name of the
sender to appear on the terminal is
the address to whom a responding
SMS may be sent.
exactly one
account
Used for accounting, your
subaccount id from Developer
Garden portal
false
outboundEncoding
Allowed values are "7bitGSM" and
"16bitUCS2", if parameter is not
supplied standard GSM 7bit is
used.
false
Example request
POST https://gateway.developer.telekom.com/plone/sms/rest/premium/smsmessaging/v1/outbound/tel%3A%2B12345678/r
Host: example.com:80
Content-Type: application/json
Accept: application/json
{"outboundSMSMessageRequest":{
"address":["tel:+13500000991",
"tel:+13500000992"],
Generated on Mon Aug 11 2014 10:01:21 for Developer Garden REST API by Doxygen
46
Service: Global SMS
"senderAddress":"tel:12345678",
"outboundSMSTextMessage":
{"message":"Hello World"},
"outboundEncoding":"7bitGSM",
"clientCorrelator":"123456",
"receiptRequest":
{"notifyURL":"http://application.example.com/notifications/DeliveryInfoNotification",
"callbackData":"some-data-useful-to-the-requester"},
"senderName":"ACME Inc."}
}
Return values
Field
address
deliveryInfoList
Meaning
Recipient phone numbers as JSON array, each
number has format "tel:+1630000001" where "+16" is
your country code.
Delivery information.
address
Array with information related to each number the
SMS was sent to.
The address the SMS was sent to.
deliveryStatus
Current delivery status of the SMS.
deliveryInfo
resourceURL
senderAddress
outboundSMS{TextMessage,
FlashMessage or BinaryMessage}
message
clientCorrelator
receiptRequest
notifyURL
callbackData
senderName
resourceURL
URL where you may retrieve your delivery
informations.
String is the address to whom a responding SMS may
be sent
Message object.
Message content.
String uniquely identifies this create SMS request. If
there is a communication failure during the request,
using the same clientCorrelator when retrying the
request allows the operator to avoid sending the same
SMS twice.
Your receipt.
URL to which you would like a notification of delivery
sent. The format of this notification is shown below.
String will be passed back in this notification, so you
can use it to identify the message the receipt relates
to.
The URL-escaped name of the sender to appear on
the terminal is the address to whom a responding
SMS may be sent.
Your resource URL.
Example response
HTTP/1.1 201 Created
Content-Type: application/json
Location: https://gateway.developer.telekom.com/plone/sms/rest/premium/smsmessaging/v1/outbound/tel%3A%2B12345
Content-Length: 12345
Generated on Mon Aug 11 2014 10:01:21 for Developer Garden REST API by Doxygen
9.7 REST Methods
47
Date: Thu, 04 Jun 2009 02:51:59 GMT
{"outboundSMSMessageRequest":{
"address":["tel:+13500000991",
"tel:+13500000992"],
"deliveryInfoList" : {
"deliveryInfo" : [
{ "address" : "tel:+13500000991",
"deliveryStatus" : "MessageWaiting" },
{ "address" : "tel:+13500000992",
"deliveryStatus" : "MessageWaiting" },
],
"resourceURL": "http://example.com/smsmessaging/v1/outbound/
tel%3A%2B12345678/requests/abc123/deliveryInfos"
},
"senderAddress":"tel:12345678",
"outboundSMSTextMessage":{"message":"Hello World"},
"outboundEncoding":"7bitGSM",
"clientCorrelator":"123456",
"receiptRequest": {"notifyURL":"http://application.example.com/notifications/DeliveryInfoNotification",
"callbackData":"some-data-useful-to-the-requester"},
"senderName":"ACME Inc.",
"resourceURL": "http://example.com/smsmessaging/v1/outbound/
tel%3A%2B12345678/requests/abc123"}
9.7.2
sendSMS - query the delivery report
REST resource information
HTTP Method
REST URI
GET
/{senderAddress}/requests/{requestID}/deliveryInfos
Parameters
Parameter
requestID
senderAddress
Meaning
As returned from an SMS send
request
Mandatory
The URL-escaped name of the
sender to appear on the terminal is
the address to whom a responding
SMS may be sent.
true
true
Example request
GET https://gateway.developer.telekom.com/plone/sms/rest/premium/smsmessaging/v1/outbound/tel%3A%2B12345678/re
Accept: application/json
Return values
Field
deliveryInfoList
Meaning
Delivery information.
Generated on Mon Aug 11 2014 10:01:21 for Developer Garden REST API by Doxygen
48
Service: Global SMS
address
Array with information related to each number the
SMS was sent to.
The address the SMS was sent to.
deliveryStatus
Current delivery status of the SMS.
deliveryInfo
resourceURL
Your resource URL.
Example response
HTTP/1.1 200 OK
Content-Type: application/json
Date: Thu, 04 Jun 2009 02:51:59 GMT
{"deliveryInfoList" : {
"deliveryInfo" : [
{ "address" : "tel:+13500000991",
"deliveryStatus" : "MessageWaiting" },
{ "address" : "tel:+13500000992",
"deliveryStatus" : "MessageWaiting" },
],
"resourceURL": "http://example.com/smsmessaging/v1/outbound/
tel%3A%2B12345678/requests/abc123/deliveryInfos"
}}
9.7.3
sendSMS - Subscribe to SMS delivery notifications
REST resource information
HTTP Method
REST URI
POST
/{senderAddress}/subscriptions
Parameters
Parameter
callbackData
clientCorrelator
Meaning
String will be passed back in this
notification, so you can use it to
identify the message the receipt
relates to.
Mandatory
String uniquely identifies this
create SMS request. If there is a
communication failure during the
request, using the same
clientCorrelator when retrying the
request allows the operator to
avoid sending the same SMS
twice.
false
false
Generated on Mon Aug 11 2014 10:01:21 for Developer Garden REST API by Doxygen
9.7 REST Methods
49
notifyURL
URL to which you would like a
notification of delivery sent. The
format of this notification is shown
below.
true
senderName
The URL-escaped name of the
sender to appear on the terminal is
the address to whom a responding
SMS may be sent.
exactly one
filterCriteria
Service provider specific filter
criteria that are used in routing the
message to your application. The
matching shall be case-insensitive.
Currently this parameter is ignored
by the API.
n/a
Example request
POST https://gateway.developer.telekom.com/plone/sms/rest/premium/smsmessaging/v1/outbound/tel%3A%2B12345678/s
Host: example.com:80
Content-Type: application/json
Accept: application/json
{"deliveryReceiptSubscription": {
"callbackReference": {
"callbackData": "12345",
"notifyURL": "http://application.example.com/notifications/DeliveryInfoNotification"
},
"filterCriteria": "GIGPICS"
}}
Return values
Field
deliveryReceiptSubscription
callbackReference
callbackData
notifyURL
resourceURL
Meaning
Delivery subscription information.
Callback reference.
String will be passed back in this notification, so you
can use it to identify the message the receipt relates
to.
URL to which you would like a notification of delivery
sent. The format of this notification is shown below.
Your resource URL.
Example response
HTTP/1.1 201 Created
Content-Type: application/json
Location: http://example.com/smsmessaging/v1/outbound/
subscriptions/sub789
Date: Thu, 04 Jun 2009 02:51:59 GMT
{"deliveryReceiptSubscription": {
"callbackReference": {
"callbackData": "12345",
Generated on Mon Aug 11 2014 10:01:21 for Developer Garden REST API by Doxygen
50
Service: Global SMS
"notifyURL": "http://application.example.com/notifications/DeliveryInfoNotification"},
"resourceURL": "http://example.com/smsmessaging/v1/
outbound/subscriptions/sub789 "}}
9.7.4
"filterCrite
sendSMS - Stop the subscription to SMS delivery notifications
REST resource information
HTTP Method
REST URI
DELETE
/subscriptions/{subscriptionID}
Parameters
Parameter
subscriptionID
Meaning
String as created when the
delivery receipt subscription was
created
Mandatory
true
Example request
DELETE https://gateway.developer.telekom.com/plone/smsrest/premium/smsmessaging/v1/outbound/subscriptions/sub7
Accept: application/json
Host: example.com:80
Return values
Field
Meaning
-
-
Example response
HTTP/1.1 204 No Content
Date: Thu, 04 Jun 2009 02:51:59 GMT
9.7.5
Receive SMS sent to your app
REST resource information
HTTP Method
REST URI
GET
https://gateway.developer.telekom.com/plone/sms/rest/{environment}/smsmessaging/v1/
Id}/messages
Parameters
Generated on Mon Aug 11 2014 10:01:21 for Developer Garden REST API by Doxygen
9.7 REST Methods
Parameter
51
Meaning
Allowed values are premium,
production and mock. The
environment defines the features
and restrictions of the service.
Mandatory
registrationId
Is typically a short-code or "virtual"
MSISDN agreed with the mobile
operator for receipt of SMS
messages
true
maxBatchSize
Is the maximum number of
messages to retrieve in this
request
false
account
This is not a GSMA-Standard
Parameter. It is used for the
accounting with the Platform One
Contingent Billing Service.
false
environment
true
Example request
GET https://gateway.developer.telekom.com/plone/sms/rest/premium/smsmessaging/v1/inbound/registrations/tel%3A%
Host: example.com:80
Accept: application/json
Return values
Field
inboundSMSMessageList
Meaning
Container Holding the complete response
inboundSMSMessage
Container Holding the messages received
numberOfMessagesInThisBatch
Number of messages contained in
inboundSMSMessage
totalNumberOfPendingMessages
Total numbers that are hold by the server
dateTime
Date the message was received
destinationAddress
Address the message was sent to
messageId
Id of the message
message
Message text
resourceURL
As part of inboundSMSMessage: URL to get the
message
As part of inboundSMSMessageList: URL the
service can be called on
Generated on Mon Aug 11 2014 10:01:21 for Developer Garden REST API by Doxygen
52
Service: Global SMS
senderAddress
Address of the originator of the message
Example response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 12345
Date: Thu, 04 Jun 2009 02:51:59 GMT
{"inboundSMSMessageList": {
"inboundSMSMessage": [
{
"dateTime": "2009-11-19T12:00:00",
"destinationAddress": "tel:+12345678",
"messageId": "msg1",
"message": "Come on Barca!",
"resourceURL": "
http://example.com/smsmessaging/v1/inbound/registrations/tel%3A%2B12345678/messages/msg1",
"senderAddress": "+447825123456"},
{
"dateTime": "2009-11-19T12:00:00",
"destinationAddress": "tel:+12345678",
"messageId": "msg2",
"message": "Great goal by Messi",
"resourceURL": "
http://example.com/smsmessaging/v1/inbound/registrations/tel%3A%2B12345678/messages/msg2",
"senderAddress": "+447825789123"}
],
"numberOfMessagesInThisBatch": "2",
"resourceURL": "http://example.com/smsmessaging/v1/inbound/registrations/tel%3A%2B12345678/messages",
"totalNumberOfPendingMessages": "20"}}
9.7.6
Subscribe to notifications of messages sent to your application
REST resource information
HTTP Method
REST URI
POST
https://gateway.developer.telekom.com/plone/sms/rest/{environment}/smsmessaging/v1/
Generated on Mon Aug 11 2014 10:01:21 for Developer Garden REST API by Doxygen
9.7 REST Methods
53
Parameters
Parameter
Meaning
Allowed values are premium,
production and mock. The
environment defines the features
and restrictions of the service.
Mandatory
callbackData
(string) is a function name or other
data that you would like included
when the POST is sent to your
application.
true
clientCorrelator
(string) uniquely identifies this
create subscription request. If
there is a communication failure
during the request, using the same
clientCorrelator when retrying the
request allows the operator to
avoid creating a duplicate
subscription.
false
criteria
(string) is case-insensitve text to
match against the first word of the
message, ignoring any leading
whitespace. This allows you to
reuse a short code among various
applications, each of which can
register their own subscription with
different criteria.
false
destinationAddress
(string) is the MSISDN, or code
agreed with the operator, to which
people may send an SMS to your
application
true
notificationFormat
(string) is the content type that
notifications will be sent in - the
default format is JSON, values of
XML or JSON can be specified
false
notifyURL
(URI) is the URI of your application
to which notifications will be sent
true
account
(string) This is not a
GSMA-Standard Parameter. It is
used for the accounting with the
Platform One Contingent Billing
Service.
false
environment
true
Example request
POST https://gateway.developer.telekom.com/plone/sms/rest/premium/smsmessaging/v1/inbound/subscriptions HTTP/1
Host: example.com:80
Content-Type: application/json
Accept: application/json
Generated on Mon Aug 11 2014 10:01:21 for Developer Garden REST API by Doxygen
54
Service: Global SMS
{"subscription": {
"callbackReference": {
"callbackData": "doSomething()",
"notifyURL":
"http://www.yoururl.here/notifications/DeliveryInfoNotification"
},
"criteria": "Vote",
"destinationAddress": "tel:+12345678" ,
"notificationFormat" : "JSON",
"clientCorrelator" : "12345",
"account" : "12345"
}}
Return values
Field
subscription
Meaning
Container Holding the complete response
callbackReference
Container Holding the callback reference data
received
callbackData
Is a function name or other data that you would like
included when the POST is sent to your application.
notifyURL
Is the URI of your application to which notifications will
be sent
criteria
Is case-insensitve text to match against the first word
of the message, ignoring any leading whitespace.
This allows you to reuse a short code among various
applications, each of which can register their own
subscription with different criteria.
destinationAddress
Is the MSISDN, or code agreed with the operator, to
which people may send an SMS to your application
notificationFormat
Is the content type that notifications will be sent in the default format is JSON, values of XML or JSON
can be specified
notifyURL
Is the URI of your application to which notifications will
be sent
account
This is not a GSMA-Standard Parameter. It is used for
the accounting with the Platform One Contingent
Billing Service.
resourceURL
Endpoint URI where your subscription is stored. If you
want to unsubscribe the subscription use this URI as
parameter.
Example response
HTTP/1.1 201 Created
Content-Type: application/json
Location: https://gateway.developer.telekom.com/plone/sms/rest/premium/smsmessaging/v1/inbound/subscriptions/s
Content-Length: 254
Date: Thu, 04 Jun 2009 02:51:59 GMT
Generated on Mon Aug 11 2014 10:01:21 for Developer Garden REST API by Doxygen
9.8 Reference: Error Codes
55
{"subscription": {
"callbackReference": {
"callbackData": "doSomething()",
"notifyURL":
"http://www.yoururl.here/notifications/DeliveryInfoNotification"
},
"criteria": "Vote",
"destinationAddress": "tel:+12345678" ,
"notificationFormat" : "JSON",
"clientCorrelator" : "12345",
"account" : "12345",
"resourceURL": " http://host/sms/rest/premium/smsmessaging /v1/inbound/subscriptions/sub678"
}}
9.7.7
Stop the subscription to message notifications
REST resource information
HTTP Method
REST URI
DELETE
https://gateway.developer.telekom.com/plone/sms/rest/{environment}/smsmessaging/v1/
ID}
Parameters
Parameter
environment
subscriptionID
Meaning
Allowed values are premium,
production and mock. The
environment defines the features
and restrictions of the service.
Mandatory
As created when the SMS receipt
subscription was created
true
true
Example request
DELETE https://gateway.developer.telekom.com/plone/sms/rest/premium/smsmessaging/v1/inbound/subscriptions/sub1
Accept: application/json
Host: example.com:80
Return values
Field
Meaning
Example response
HTTP/1.1 204 No content
Accept: application/json
Date: Thu, 04 Jun 2009 02:51:59 GMT
9.8
Reference: Error Codes
Generated on Mon Aug 11 2014 10:01:21 for Developer Garden REST API by Doxygen
56
Service: Global SMS
HTTP code
Message ID
Exception Text
Variables []
200
-
-
-
201
-
-
-
204
-
-
-
401
-
-
-
403
403
POL0001
Insufficient
Authorization
404
-
A policy
error
occured.
Error code is
%1
-
405
-
-
-
400
POL0001
A policy
error
occured.
Error code
%1
A policy
error
occured.
Error code
%1
A policy
error
occured.
Error code
%1
A policy
error
occured.
Error code
%1
A policy
error
occured.
Error code
%1
A policy
error
occured.
Error code
%1
Insufficient
credits
400
400
400
400
400
POL0001
POL0001
POL0001
POL0001
POL0001
-
Description
Successful GET
Request
Successful POST
Request
Successful
DELETE Request
Invalid access
token
Missing token
Insufficient
Authorization
Not found. Wrong
uri.
Method not
supported
Insufficient credits
to use service
is
is
Account does
not exists or
does not
belong to
user
Quotas
exceeded
Account does not
exists or does not
belong to user
SenderAddress
is not
allocated
The sender
address is not
validated or
allocated to a user
Address is
blacklisted
The address is
blacklisted via
dialplan
Subscription
to notifyurl
already
exists
Subscription to the
specified notifyurl
already exists
Quotas exceeded
is
is
is
is
Generated on Mon Aug 11 2014 10:01:21 for Developer Garden REST API by Doxygen
9.8 Reference: Error Codes
57
400
POL0001
A policy
error
occured.
Error code is
%1
400
POL0001
400
POL0003
400
POL0010
400
POL0013
A policy
error
occured.
Error code is
%1
To many
addresses
specified in
message part
%1
Request
information
unavailable
as the
retention
time interval
has expired
Duplicated
addresses
400
SVC0002
400
SVC0002
400
SVC0002
400
SVC0002
400
SVC0002
400
SVC0002
400
SVC0002
400
SVC0003
Invalid input
for message
part %1
Invalid input
for message
part %1
Invalid input
for message
part %1
Invalid input
for message
part %1
Invalid input
for message
part %1
Invalid input
for message
part %1
Invalid input
for message
part %1
Invalid input
for message
part %1,
valid values
are %2
Generated on Mon Aug 11 2014 10:01:21 for Developer Garden REST API by Doxygen
Number of
delivery
noftification
subscriptions
for
senderaddress
exceeded
Invalid
subscriptionid
The maximum
number of delivery
notification
subscriptions for
sender address is
reached
addresses[]
Insufficient credits
to use service
-
No delivery status
available
-
Duplicated
addresses in the
address-array
The format of the
sender name is
invalid
The format of the
clientCorrelator is
invalid
Message is missing
senderName
clientCorrelator
message
The subscription id
is not allocated to
user
notifyURL
The format of the
notify URL is invalid
callbackData
Callback data is
invalid.
account
account is invalid.
callbackReference
callbackReference
is invalid or missing
Accept
Accept header is
Header,
unknown.
application/json
Supported value is
’application/json’
58
Service: Global SMS
400
SVC0003
400
SVC0003
400
SVC0004
400
SVC0004
409
SVC0005
400
SVC0280
Invalid input
for message
part %1,
valid values
are %2
Invalid input
for message
part %1,
valid values
are %2
No valid
addresses
provided in
message part
%1
No valid
addresses
provided in
message part
%1
Correlator %1
specified in
message part
%2 is a
duplicate
Message too
long
Environment premium,
sandbox, mock
Outbound
encoding bitGSM,
16bitUCS2
Address
senderAddress
The environment is
invalid. Supported
values are:
’premium, sandbox
or mock’
The outbound
encoding ist invalid.
Supported values
are: ’bitGSM,
16bitUCS2’
The format of the
address is invalid.
The format of the
senderAddress is
invalid.
{correlator}, clientCorrelator has
clientcorrelator
already been used.
{maxLength}
Message is too
long (configurable
for each
environment)
See also Reference: Global Error Codes.
9.9
Related Information
Getting started:
• Getting started with .NET SDK
• Activating the API
Simple example:
• How to send SMS?
• via note.js
• Windows sidebar
• TYPO3 Extensions
• SMS for M2M Communication
What can you do with Global SMS API?
• Texting a Bubble Gun (SMS with Arduino)
• Global SMS - Sending SMSes in node.js
Generated on Mon Aug 11 2014 10:01:21 for Developer Garden REST API by Doxygen
Chapter 10
Service: Speech to Text
The Speech to Text service allows you to transcribe a raw audiofile into text form
For more information about this service please contact us at [email protected]
60
Service: Speech to Text
Generated on Mon Aug 11 2014 10:01:21 for Developer Garden REST API by Doxygen
Chapter 11
Contact and Support
We’d like to receive your feedback and hear your suggestions. If you should encounter a bug, please notify us as
well.
The following ways of getting into contact are currently maintained:
• Developer Garden forums - Share knowledge with other users and the Developer Garden team
• Contact form - Submit a support request directly to the Developer Garden team

Download Report