Protocol

REST SOAP

Backoffice API

Send SMS

Receive SMS

End customer API

Send SMS

Receive SMS

Appendices

 
 

API White Label

What is the White Label and how to use

Skebby offers its customers a fully customizable platform for the marketing of SMS services in total anonymity with its own domain, logo and colors. The Wholesaler/Reseller buy SMS from Skebby at special prices, and establishes the rates for its customers gaining the difference in complete autonomy. Thanks to a multi-platform system allows the White Label Wholesaler to manage different types of customers (White Label o Resellers) manually via the Web interface or automatically via API.

The platform White Label can be used in two modes :

  1. Web interface SMS Messenger White Label + API Back Office White Label
    If you do not have your own Web interface for sending SMS, Skebby provides you with an integrated multilevel platform with the web interface SMS Messenger customizable with your own domain, logo, colors and graphics from which your customers can log in and use the services of Sending and Receiving SMS.
    You can manage your customers manually from the Web interface White Label or automatically via BackOffice API White Label.
    Send SMSs to your Customers >> SMS Messenger White Label
    Manage your customers >> API Back Office (automatic)
    >> Web Interface White Label (manual)
  2. Your web interface + proprietary API Send SMS API and Back office White Label
    If you have your own Web interface for sending SMS you can integrate directly with the SMS Gateway Skebby and then use all the White Label APIs within your platform for the creation and management of your customers and the billing of SMS services. Skebby provides extensive documentation of the functionality of the Software including examples of code for an immediate copy and paste, making it simple and a almost cost zero integration.
    Send SMSs to your Customers >> Your Web interface + API Final Customers / Send SMS
    Manage your customers >> Back Office API (automatic)
    >> Web interface White Label (manual)

Multilevel Structure White Label

the platform White Label Skebby allows to operate with a structure of 2 levels resale of SMS (Wholesaler - Reseller - Final Customer).  You can activate and manage both Final Customers both Customers Resellers reselling themselves SMS services to White Label on your channel. Infact, you will be able to assign to your customers Resellers a dedicated domain and allow them to fully customize the web interface of SMS Messenger with their logo, domain etc on which their Final Customers can access. Through the platform White Label you can also manage your customers (ResellersFinal Customers) and send SMS previously purchased.

Type API White Label

The White Label program provides developers with two types of API:

  • Backoffice API
  • End customer API

A user of the system must always make calls to the server of his supplier, both when he uses the Backoffice APIs and when he uses the End customer APIs. This is the only server on which he has an account.

Backoffice API

With this API the Wholesaler / Reseller can manage the customers is responsible for.

Restrictions on the service:

  • The Wholesaler has Final Customers and can have Resellers.
  • A Wholesaler can access all resources of costomers created by himself, in other words its own Resellers and own Final Customers but not the Final Customers of Resellers.
  • A Reseller can access exclusively at resourcesof its own Final Customers.
  • A Reseller has exclusively Final Customers and cannot create other Resellers.

N.B.Using this API is not possible to manage resources of your own account. In order to do so, you should use the Customers API.

End customer API

With these APIs Wholesalers, Resellers and Final Customers can manage services and related functionality to their account such as sending SMS going to Send SMS> Message or make queries about the latter.

Example of access to the domains

An user Wholesaler owner of the domain sms.api.distributore.it creates accounts of its customers using the Backoffice API on his provider's host at URL http://api.smsmessenger.it. Whereas the created customerswill use the Backoffice API and Final Customers through their Wholesaler's server at http://sms.api.distributore.it

Equally the Wholesaler manages data of it's own account through http://api.smsmessenger.it, this time by using the Customers API.

Stylistic notes on API documentation

To simplify the comprehension of the documentation, the following measures will be taken:

  • We will refer to Wholesalers and Resellers with cumulative name Wholesalers/Resellers (with first letter lower case), because in most cases thos two users have the same roles and administrative privileges.
  • When needed to distinguish we will refer explicitly with name Wholesalers and Resellers (both with first letter lower case).

Mandatory parameters are arked with an asterisk .

API Examples of use

This column contains examples of URL, requests and replies.

The prices that appear are only examples and do not correspond to actual commercial offers.

 

Authentication

HTTP Basic Authentication and HTTP Digest Authentication are supported. We recommend the use of Digest Authentication.

Basic Authentication

curl -D - -u username:password --basic \
http://api.smsmessenger.it/resources

Digest authentication

curl -D - -u username:password --digest \
http://api.smsmessenger.it/resources

In the examples, use will be made of Digest Authentication. Curl, when available on the server, defaults to Basic Authentication.

 

URL format

The URLs follow the REST conventions in which the HTTP verbs indicate the operations performed on the resources indicated by the URL.

The URLs of the Backoffice APIs have the resellers prefix followed by the name of the resource. All the other URLs, which correspond to the End customer APIs, if they refer to a particular user, have the prefix customers before the name of the resource, while they have the /resource format if they return the same data for all customers.

List of objects in a resource
curl -D - -u username:password \
http://api.smsmessenger.it/resources

Details of an object
curl -D - -u username:password \
http://api.smsmessenger.it/resources/id_risorsa

Create an object
curl -D - -u username:password \
-d attributo1=valore \
-d attributo2=valore \
-X POST http://api.smsmessenger.it/resources

Modify an object
curl -D - -u username:password \
-d attributo1=nuovo_valore \
-d attributo2=nuovo_valore \
-X PUT http://api.smsmessenger.it/resources/id_risorsa

Delete an object
curl -D - -u username:password \
-X DELETE http://api.smsmessenger.it/resources/id_risorsa

 

Data format

The return values of the APIs are in JSON format and are illustrated with examples in the right-hand column beside the descriptions of the calls to the API.

Whole numbers are returned as numbers, for example {"id_mt_price":3}.

Decimal numbers are returned as strings to avoid approximation errors and to leave the client application maximum freedom to manipulate them, for example {"price":"0.100000"}. The decimal part is to be separated from the rest of the number by a full stop. The use of a comma is not supported.

Booleans are returned as whole numbers, 1 for true and 0 for false.

Dates are returned as strings in ISO 8601 yyyy-mm-ddTHH:MM:SS+oooo format, for example {"created_at": "2013-05-09T10:15:34+0200"}.

The same conventions are adopted for the values sent to the API.

The format of decimal numbers and the length of the strings in the specifications of the single APIs will be indicated. In general, money fields have a decimal (X, Y) format with Y digits after the full stop and X - Y digits before it. The exact format is indicated on the lists of the parameters of the single calls.

Non-initialized fields for which there is no default setting are returned as null, for example: {"note": null}.

The encoding used by the API is UTF-8 but some attributes of some resources may require data in ASCII 7 bit format (for example, the Customer username).

The values passed in the examples are urlencoded

 

Errors

The server uses the conventional http reply codes to indicate the success or failure of an API request. In general, the 2xx series codes indicate a success, the 4xx series codes indicate an error caused by information passed incorrectly (for example, a missing obligatory parameter, etc), the 5xx series codes indicate a server error.

For errors, the body of the reply is a JSON array called errors made up of a hash character with the keys

  • target: the name of the field in which the error occurred, for example, a missing attribute in a call to the API
  • errors: another array with target error messages structured as follows
    • code: the error code
    • reason: the error message

To write a personalized error message, simply extract target and code. In some cases the target could have error arrays with more than one element.

The possible code and reason values are:

  • alnuminvalid: Invalid type given. String, integer or float expected
  • alnumstringempty: The input is an empty string
  • callbackinvalid: The input is not valid
  • callbackvalue: An exception has been raised within the callback
  • datefalseformat: The input does not fit the date format <formato>
  • dateinvalid: Invalid type given. String, integer, array or DateTime expected
  • dateinvaliddate: The input does not appear to be a valid date
  • hostnamecannotdecodepunycode: The input appears to be a DNS hostname but the given punycode notation cannot be decoded
  • hostnamedashcharacter: The input appears to be a DNS hostname but contains a dash in an invalid position
  • hostnameinvalid: Invalid type given. String expected
  • hostnameinvalidhostname: The input does not match the expected structure for a DNS hostname
  • hostnameinvalidhostnameschema: The input appears to be a DNS hostname but cannot match against hostname schema for TLD <dominio>
  • hostnameinvalidlocalname: The input does not appear to be a valid local network name
  • hostnameinvaliduri: The input does not appear to be a valid URI hostname
  • hostnameipaddressnotallowed: The input appears to be an IP address, but IP addresses are not allowed
  • hostnamelocalnamenotallowed: The input appears to be a local network name but local network names are not allowed
  • hostnameundecipherabletld: The input appears to be a DNS hostname but cannot extract TLD part
  • hostnameunknowntld: The input appears to be a DNS hostname but cannot match TLD against known list
  • norecordfound: No record matching the input was found
  • notalnum: The input contains characters which are non alphabetic and no digits
  • notbetween: The input is not between <min> and <max>, inclusively
  • notbetweenstrict: The input is not strictly between <min> and <>
  • recordfound: A record matching the input was found
  • regexerrorous: There was an internal error while using the pattern <pattern>
  • regexinvalid: Invalid type given. String expected
  • skinvalid: generic validation error
  • skinvalidbody: Not valid
  • skinvalidcountry: Must be a string with length = <lunghezza>
  • skinvalidemail: Must be a valid email no longer than <lunghezza>
  • skinvalidid: Must be a valid id
  • skinvalidmoney: Must be greater than 0 and less than <max valuta>
  • skinvalidphone: Must be a valid phone number
  • skinvalidrecipient: Must specify from 1 to <max destinatari> recipients
  • skinvalidsender: Must specify a verified sender_number (max 11 digit) OR sender_string
  • skinvalidstring: Must be an alphanumeric string with max length
  • stringlengthtoolong: The input is more than <max> characters long
  • stringlengthtooshort: The input is less than <min> characters long

HTTP error codes

  • 200 OK
  • 400 Bad Request
  • 403 Forbidden
  • 404 Not Found
  • 405 Method Not Allowed
  • 500 Internal Server Error

Error JSON

These are the error messages obtained when a call is made to the API for creating customers, indicating the obligatory type parameter only.


{
"errors": [{
  "target":"username",
  "errors": [{
    "code":"isEmpty",
    "reason":"Value is required and can't be empty"
  }] }, {
  "target":"password",
  "errors": [{
    "code":"isEmpty",
    "reason":"Value is required and can't be empty"
  }] }, {
  "target":"email",
  "errors": [{
    "code":"isEmpty",
    "reason":"Value is required and can't be empty"
  }] }, {
  "target":"domain",
  "errors": [{
    "code":"isEmpty",
    "reason":"Value is required and can't be empty"
  }] }, {
  "target":"locale",
  "errors": [{
    "code":"isEmpty",
    "reason":"Value is required and can't be empty"
  }] }, {
  "target":"timezone",
  "errors": [{
    "code":"isEmpty",
    "reason":"Value is required and can't be empty"
  }] }, {
  "target":"international_prefix",
  "errors": [{
    "code":"isEmpty",
    "reason":"Value is required and can't be empty"
  }] }
]}
 

Call index

This section summarizes the Backoffice and End customer API calls, classifying them by the HTTP verb they use. According to the REST conventions, the GET verb is used to access the contents of a resource, POST to create a new element, PUT and DELETE to modify and delete an existing one, respectively.

As, according to the URL indicated, the GET verb is used both to list the elements of a resource and to return one of its elements given an ID, the tables distinguish between the two cases GET for the list and GET ID for the single element.

Calls that operate on nested resources are assigned special lines in the tables. For example the GET / for getting the Services of a Profile is contained on the Services in a Profile line.

Backoffice API

ResourceGET /GET /idPOSTPUTDELETE
Customer  
Service      
Customer profile
Services in a Profile        
Transmission – Tariff
Transmission – Prices  
Transmission – Top-up  
Alerts    
Reception – Tariff
Reception – Prices      
Reception – Flat-rate top-up  
Keywords sold  

End customer API

ResourceGET /GET /idPOSTPUTDELETE
Customer      
Check customer      
Service        
Customer profile        
Transmission – Tariff        
Transmission – Prices        
Transmission – Top-up        
Alerts    
Request for check        
Checked numbers    
Messages        
Notification      
Reception – Tariff      
Reception – Prices        
Reception – Flat-rate top-up        
Keywords sold    
Phone numbers  
 

Inoltro Servizi di Ricezione

The service "Receiving SMS" allows you to receive text messages on a dedicated number or a shared number with keyword, directly on your server via an HTTP call / Rest / Soap or by sending an email to the addresses specified

When you receive a text message will be triggered a server-to-server call (s2s) to the url or email.

For more information on the contact details, refer to section: Phone numbers

 

Backoffice API

In the examples of this section, a user, in the role of a Wholesaler, makes administrative calls to the White Label server, indicated here generically as server.

 

Customer

The resource comprises all the principal data of the account of a customer.
The Wholesaler/Reseller will be able to delete, modify, create and view the Customer resource for which he is directly responsible.
The values used by the API for the three types of Customer (type attribute) are:

  • Wholesaler: wholesaler.
  • Reseller: reseller.
  • Final Customer: customer.

Customers are always identified by username in the API calls and the username is case-insensitive in searches, but is saved as it is passed when created. domain and email are case-insensitive by definition.

It should be borne in mind that the API uses UTF-8 encoding for the data transferred. For some Customer attributes an ASCII 7-bit subset is used. They are the three listed below and their length limits and format are also specified:

  • The username can only contain capital and small letters, digits and the four special characters - . @ _ (hyphen, full stop, at and underscore). It has a minimum length of 3 characters and a maximum of 40.
  • The domain has a maximum length of 255 characters.
  • The email has a maximum length of 60 characters.
 

List of customers

Lists the Resellers / Final Customers of the user, according to the access level. The data are returned in an array.

The pagination is supported using the optional offset and limit parameters.

Searches using the combination of the optional parameters business_name, phone and email are supported. If the search string contains asterisks (*) a search is run for substrings with the method of the character % in the SQL LIKE statement. If there are no asterisks a search is run for the entire value of the attribute. The search is case-insensitive. A blank value passed as a search parameter matches the blank string and not a field containing a NULL value. The API does not provide methods for running searches on fields containing the NULL value.

The various search fields are combined by default in AND but they can be combined in ORindicating the andor parameter in the url.

Pagination and searches can be combined.

Syntax
GET /resellers/username-reseller/customers
with optional arguments
  • offset offset
  • limit limit
  • email e-mail
  • business-name name
  • phone telephone
  • fk-profileid profile
  • typetype
  • op and/or
URL arguments
username_reseller*
stringusername used to register on the service
offset
integer (positive)in combination with the limit parameter, it defines the subset of the customer array returned by the search: offset indicates the index of the first element to be returned.
limit
integer (positive, default 50, max 100)indicates the length of the array to be returned and is to be used in combination with offset; if the limit parameter is not present only 50 elements are returned even when the offset is not specified
email
string (max 60 characters)the text to be searched for in the e-mail attribute of the customers as explained in the introduction of this API call
username
string (max 100 characters)the text to be searched for in the username attribute of the customers as explained in the introduction of this API call
business_name
string (max 100 characters)the text to be searched for in the business_name attribute of the customers as explained in the introduction of this API call
phone
string (max 50 characters)the text to be searched for in the phone attribute of the customers as explained in the introduction of this API call
fk_profile
integerID of the user’s profile
type
string (max 50 characters)user type
Required parameters
User types
op
stringAND (default) or OR, indicates how the search fields (email, business_name, phone) are combined

EXAMPLES OF REQUESTS

curl -D - -u user:password --digest \
http://api.smsmessenger.it/resellers/user/customers

curl -D - -u user:password --digest \
http://api.smsmessenger.it/resellers/user/customers?offset=50&limit=50

EXAMPLES OF SEARCHES

curl -D - -u user:password --digest \
'http://api.smsmessenger.it/resellers/user/customers?business_name=*mario*rossi*'

curl -D - -u user:password --digest \
'http://api.smsmessenger.it/resellers/user/customers?email=*example*'

Return values
total
total number of Customers found, irrespective of the limit value
result
The array of Customers found, at most in a number equivalent to the limit value and starting from offset, if indicated.

result is an array of

domain
domain of the user that created this
business_name
first name, surname and/or company name
contact
contact information
created_at
time and date on which the user was created
admin_domain
the user’s domain
email
email associated with the account
id_default_new_profile
numerical ID of the default profile
id_profile
numerical ID of the profile
international_prefix
country code (it, gb ..)
locale
the user’s language (it_IT, en_US)
note
notes about the user
phone
phone number
status
current status of the account (active, disabled)
timezone
the user’s time zone
type
the various user types (wholesaler, reseller, customer)
username
the user’s username
currency
user's currency

EXAMPLE OF A REPLY

This is the reply to the second call in the example

Status Code: 200

{
"total":2,
result: [{
  "admin_domain":"example.com",
  "business_name":null,
  "contact":null,
  "created_at":"2013-04-30T12:44:06+0200",
  "domain":"server",
  "email":"mariorossi@example.com",
  "id_default_new_profile":15,
  "id_profile":4,
  "international_prefix":"it",
  "locale":"it_IT",
  "note":null,
  "phone":null,
  "status":"active",
  "timezone":"itrom",
  "type":"reseller",
  "username":"mariorossi",
  "currency":"EUR",
  },
  {
  "admin_domain":null,
  "business_name":null,
  "contact":null,
  "created_at":"2013-04-30T13:01:04+0200",
  "domain":"server",
  "email":"giorgiobianchi@example.org",
  "id_default_new_profile":null,
  "id_profile":4,
  "international_prefix":"it",
  "locale":"it_IT",
  "note":null,
  "phone":null,
  "status":"active",
  "timezone":"itrom",
  "type":"customer",
  "username":"giorgiobianchi",
  "currency":"USD"
  }]
}

 

View customer

Retrieves the information of a single Reseller / Final Customer according to the level of access.
Syntax
GET /resellers/username-reseller/customers/username
URL arguments
username_reseller*
string (40 characters)username used to register on the service
username*
string (40 characters)username used by your Reseller / Final Customer to register on the service and whose information is to be viewed

EXAMPLE OF A REQUEST

curl -D - -u user:password --digest \
http://api.smsmessenger.it/resellers/user/customers/mariorossi

Return values
domain
domain of the user that created this
business_name
first name and surname and/or company name
contact
contact information
created_at
time and date on which the user was created
admin_domain
the user’s domain
email
email associated with the account
id_profile
numerical ID of the profile
id_default_new_profile
numerical ID of the default profile
international_prefix
country code (it, gb ..)
locale
the user’s language (it_IT, en_US)
note
notes about the user
phone
phone number
status
current status of the account (active, disabled)
timezone
the user’s time zone
type
the various user types (wholesaler, reseller, customer)
username
the user’s username
currency
user's currency

EXAMPLE OF A REPLY

Status Code: 200

{
"admin_domain":"example.com",
"business_name":null,
"contact":null,
"created_at":"2013-04-30T12:44:06+0200",
"domain":"server",
"email":"mariorossi@example.com",
"id_default_new_profile":15,
"id_profile":4,
"international_prefix":"it",
"locale":"it_IT",
"note":null,
"phone":null,
"status":"active",
"timezone":"itrom",
"type":"reseller",
"username":"mariorossi",
"currency":"EUR",
}

the value of domain is "server" tehrefore mariorossi will make requests to the API "http://api.smsmessenger.it". mariorossi customers will make requests to the 'admin_domain, "http://example.com/api".

 

Create customer

Create new customer.

Syntax
POST /resellers/username-reseller/customers
BODY [Parameters ]
URL arguments
username_reseller*
string (40 characters)username used by the Wholesaler/Reseller to register on the service
BODY parameters
business_name*
string (100 characters)first name and surname and/or company name
contact
string (50 characters)contact information
admin_domain
depending on the context, string (255 characters)It is obligatory to create Resellers but it is not to be present when creating Final Customers. It is the domain to which the customers of the Reseller will connect.
email*
string (60 characters)email associated with the account
id_profile
integerThe id of the profile to be associated with the user created. If missing, the default profile of the user creating it is used.
international_prefix*
string (2 caratteri)country code (it, gb ..)
Required parameters
List of country codes
locale*
stringuser’s language
Required parameters
  • it_IT
  • en_US
password*
string (min 5, max 32 characters)password of the account must not be the same as the username, the maximum possible length should be used
phone
string (50 characters)phone number
note
string (255 characters)notes for Wholesaler/Reseller
type*
stringthe various user types
Required parameters
  • reseller
  • customer
timezone*
string (8 characters)the user’s time zone
Required parameters
List of abbreviations
username*
string (min 3, max 40 characters)the user’s username, only letters and digits are accepted
currency
stringuser's currency
Required parameters
  • EUR
  • GBP
  • USD

EXAMPLE OF A REQUEST

curl -D - -u user:password --digest \
-X POST \
http://api.smsmessenger.it/resellers/user/customers \
-d "business_name=Mario%20Rossi%20SpA" \
-d "domain=example.com" \
-d "email=mariorossi%40example.com" \
-d "international_prefix=it" \
-d "locale=it_IT" \
-d "password=password" \
-d "timezone=itrom" \
-d "type=reseller" \
-d "username=mariorossi" \
-d "currency=EUR"

Return values
admin_domain
domain administered by the user created
business_name
first name and surname and/or company name
contact
contact information
created_at
time and date on which the user was created
domain
domain to which the user created must log on to operate (that of his Wholesaler/Reseller)
email
email associated with the account
id_profile
numerical ID of the profile
id_default_new_profile
numerical ID of the profile that will be assigned by default to the customers of this Wholesaler/Reseller (not applicable to Final Customers); contains the services available to Wholesaler/Reseller
international_prefix
country code (it, gb ..)
locale
the user’s language (it_IT, en_US)
note
notes about the user
phone
the user’s surname
status
current status of the account (active, disabled)
timezone
the user’s time zone
type
the various user types (reseller, customer)
username
the user’s username
currency
user's currency

EXAMPLE OF A REPLY

Status Code: 200

{
"admin_domain": "example.com",
"business_name": "Mario Rossi SpA",
"contact": null,
"created_at": "2013-04-30T12:44:06+0200",
"credit": null,
"domain": "server",
"email": "mariorossi@example.com",
"id_default_new_profile": 15,
"id_profile": 4,
"international_prefix": "it",
"locale": "it_IT",
"note": null,
"phone": null,
"status": "active",
"timezone": "itrom",
"type": "reseller",
"username": "mariorossi",
"currency": "EUR"
}

 

Modify customer

Modifies the Resellers / Final Customers according to your access level.

Syntax
PUT /resellers/username-reseller/customers/username-customer
BODY [Parameters ]
URL arguments
username_reseller*
string (40 characters)username used by the Wholesaler/Reseller to register on the service
username_customer*
string (40 characters)username used by your Reseller / Final Customer to register on the service and whose information is to be viewed
BODY parameters
business_name
string (100 characters)first name and surname and/or company name
contact
string (50 characters)contact information
admin_domain
depending on the context, string (255 characters)It is obligatory to create Resellers but it is not to be present when creating Final Customers. It is the domain to which the customers of the Reseller will connect.
email
string (60 characters)email associated with the account
id_profile
integerThe id of the profile to be associated with the user created. If missing, the default profile of the user creating it is used.
international_prefix
string (2 characters)country code (it, gb ..)
Required parameters
List of country codes
locale
stringuser’s language
Required parameters
  • it_IT
  • en_US
password
string (min 5, max 32 characters)password of the account must not be the same as the username, the maximum possible length should be used
phone
string (50 characters)phone number
note
string (255 characters)notes for Wholesaler/Reseller
status
stringthe user status
Required parameters
  • active
  • disable
type
stringthe various user types
Required parameters
  • reseller
  • customer
timezone
string (8 characters)the user’s time zone
Required parameters
List of abbreviations
username
string (min 3, max 40 characters)the user’s username, only letters and digits are accepted
currency
stringuser's currency
Required parameters
  • EUR
  • GBP
  • USD

EXAMPLE OF A REQUEST

curl -D - -u user:password --digest \
-X PUT \
http://api.smsmessenger.it/resellers/user/customers/giorgiobianchi \
-d "contact=Informazioni di contatto"

Return values
domain
domain of the user that created this customer
business_name
first name and surname and/or company name
contact
contact information
created_at
time and date on which the user was created
admin_domain
domain of this customer, only if it is not a Final Customer
email
email associated with the account
id_profile
numerical ID of the profile
id_default_new_profile
numerical ID of the default profile
international_prefix
country code (it, gb ..)
locale
the user’s language (it_IT, en_US)
note
notes about the user
phone
phone number
status
current status of the account (active, disabled)
timezone
the user’s time zone
type
the various user types (reseller, customer)
username
the user’s username
currency
user's currency

EXAMPLE OF A REPLY

Status Code: 200

{
"admin_domain":null,
"business_name":null,
"contact":"Informazioni di contatto",
"created_at":"2013-04-30T13:01:04+0200",
"domain":"server",
"email":"giorgiobianchi@example.org",
"id_default_new_profile":null,
"id_profile":4,
"international_prefix":"",
"locale":"it_IT",
"note":null,
"phone":null,
"status":"active",
"timezone":"",
"type":"customer",
"username":"giorgiobianchi",
"currency":"EUR"
}

 

Service

This resource manages the names with which the Wholesalers/Resellers rename the services at their disposal.
Restrictions:

  • The Service is created automatically when creating Wholesaler/Reseller and cannot be created individually with an API call.
  • A Wholesaler has the names of the services assigned by his supplier by default.
  • A Reseller has the name of the services assigned by his Wholesaler by default.
  • The Wholesalers/Resellers can change these name subsequently.

The services are identified by an alphabetical code (service-type) irrespective of the names assigned. Correspondence between these types and these services is guaranteed

  • F -> fixed: low quality
  • D -> dynamic no report: without notification
  • R -> dynamic with report: with notification

The services are grouped in Profiles, as explained later on.

 

List of services

Retrieves a list of the services created by the Wholesaler/Reseller.

Syntax
GET /resellers/username-reseller/services
URL arguments
username_reseller*
string (40 characters)username used to register on the service

EXAMPLE OF A REQUEST


curl -D - -u user:password --digest \
http://api.smsmessenger.it/resellers/user/services

Return values
id_service
id of the service
type
type of service
name
name of the service

EXAMPLE OF A REPLY

Status Code: 200

[{
"id_service":4,
"type":"R",
"name":"SMS Classic Plus",
},
{
"id_service":5,
"type":"D",
"name":"SMS Classic",
}]

 

Modify service

Used exclusively to change the name of a service.

Syntax
PUT /resellers/username-reseller/services/id-service
BODY [Parameters ]
URL arguments
username_reseller*
string (40 characters)username used to register on the service
id_service*
integerID of the service whose information is to be returned
BODY parameters
name
stringname of the service

EXAMPLE OF A REQUEST

In the previous example "Classic Plus SMS" had id_service = 4. This call renames it "SMS with notification"

curl -D - -u user:password --digest \
-X PUT \
http://api.smsmessenger.it/resellers/user/services/4 \
-d "name=SMS%20con%20notifica"

Return values
id_service
id of the service
type
type of service
name
name of the service

EXAMPLE OF A REPLY

Status Code: 200

{
"id_service":4,
"type":"R",
"name":"SMS con notifica",
}
 

Customer profile

The profile defines the types of Services that the Wholesaler makes available to his Resellers and Final Customers, or those made available by a Reseller to his Final Customers.
For example, the default profile could contain all types of SMS (Classic, Classic +, Basic) and the possibility of receiving SMSs.
Create and associate different profiles to customers means "hiding" – i.e. not making available – some of the services offered.
Restrictions:

  • A Wholesaler/Reseller may create more than one profile to be assigned to his direct customers.
  • Every customer created may only be assigned one profile.

The Resellers that are created are assigned an identical profile for Services to that of the Wholesaler that created them.

 

List of customer Profiles

Retrieves a list of the profiles created by the Wholesalers/Resellers.

Syntax
GET /resellers/username-reseller/profiles
URL arguments
username_reseller*
string (40 characters)username used to register on the service

EXAMPLE OF A REQUEST

curl -D - -u user:password --digest \
http://api.smsmessenger.it/resellers/user/profiles

Return values
id_profile
numerical ID of the customer profile
name
name chosen for the profile

EXAMPLE OF A REPLY

Status Code: 200

[{
"id_profile":5,
"name":"Invio SMS"
},
{
"id_profile":6,
"name":"Ricezione SMS"
}]

 

View customer Profile

Retrieves the information about the customer profile.
The number of customers with that particular profile is also returned with the following restrictions:

  • the count only considers the customers for whom the Wholesaler/Reseller is directly responsible.
Syntax
GET /resellers/username-reseller/profiles/id-profile
URL arguments
id_profile*
integernumerical ID of the profile whose information is to be returned

EXAMPLE OF A REQUEST

curl -D - -u user:password --digest \
http://api.smsmessenger.it/resellers/user/profiles/5

Return values
assigned_users
number of customers that are using this profile
id_profile
numerical ID of the customer profile
name
name chosen for the profile
services
array of the ids of the Services in the profile

EXAMPLE OF A REPLY

Status Code: 200

{
"assigned_users":0
"id_profile":5,
"name":"Invio SMS",
"services":[4, 5]
}

 

View Services in a Profile

Retrieves the information about the services contained in a Profile.

Syntax
GET /resellers/username-reseller/profiles/id-profile/services
URL arguments
username_reseller*
stringusername used to register on the service
id_profile*
integernumerical ID of the profile whose information is to be returned

EXAMPLE OF A REQUEST

curl -D - -u user:password --digest \
http://api.smsmessenger.it/resellers/user/profiles/5/services

Return values

An array of:

id_service
numerical ID of the service
type
code identifying the service
name
name chosen for the service

EXAMPLE OF A REPLY

Status Code: 200

[{
"id_service":4,
"type":"R",
"name":"SMS Classic Plus",
},
{
"id_service":5,
"type":"D",
"name":"SMS Classic",
}]

 

Create customer profile

Create new customer profile.

Syntax
POST /resellers/username-reseller/profiles
BODY [Parameters ]
URL arguments
username_reseller*
string (40 characters)username used to register on the service
BODY parameters
name*
string (50 characters)name of the profile.
For example
all inclusive (profile that enables users both to receive and to send SMS)
send (profile that only allows them to send SMSs)
receive (profile that only allows them to receive SMSs)
services*
array(integer)List of the Services to be associated with the list profile, expressed as an array in the form services[]=id1&services[]=id2&...

EXAMPLE OF A REQUEST

curl -D - -u user:password --digest \
-X POST http://api.smsmessenger.it/resellers/user/profiles \
-d "name=Tutto%20incluso" \
-d "services[]=4" \
-d "services[]=5"

The services with id_service = 4 and 5 must be included in those returned by ResellersServiceList()

Return values
id_profile
numerical ID of the customer profile
name
name chosen for the profile

EXAMPLE OF A REPLY

Status Code: 200

{
"id_profile":16,
"name":"Tutto incluso"
}

 

Modify customer profile


Modify existing customer profile.
Restrictions:
  • Profiles already sold to customers cannot be modified.


Syntax
PUT /resellers/username-reseller/profiles/id-profile
BODY [Parameters ]
URL arguments
username_reseller*
string (40 characters)username used to register on the service
id_profile*
integernumerical ID of the profile
name
stringname of the service
services
array(integer, integer)list of services to be associated with this profile

EXAMPLE OF A REQUEST

curl -D - -u user:password --digest \
-X PUT \
http://api.smsmessenger.it/resellers/user/profiles/16 \
-d "name=profilo%20modificato" \
-d "services[]=4"

The name of Profile 16 created previously has been changed. It now also consists of Service 4 only. Service 5 has been removed from the profile because it has not been included in the array services.

Return values
id_profile
numerical ID of the customer profile
name
name chosen for the profile

EXAMPLE OF A REPLY

Status Code: 200

{
"id_profile":16,
"name":"profilo modificato"
}

 

Assign Profile to customer

A profile is assigned and modified using the id-profile parameter of the Customer resource (see Modify customer). That API is therefore used and not the Profile API. The return value is the Customer to whom the profile has been assigned.

Of the update parameters, only the one necessary to assign a profile is indicated, but the profile can be assigned as part of a larger Modify customer operation.

Syntax
PUT /resellers/username-reseller/customers/username-customer
BODY [Parameters ]
URL arguments
username_reseller*
string (40 characters)username used to register on the service
username_customer*
string (40 characters)username used by your Reseller / Final Customer to register on the service and whose information is to be viewed
BODY parameters
id_profile*
integernumerical ID of the profile to be associated with the customer

EXAMPLE OF A REQUEST

curl -D - -u user:password --digest \
-X PUT http://api.smsmessenger.it/resellers/user/customers/mariorossi \
-d "id_profile=16"

Return values

For the list see the API Modify customer call

EXAMPLE OF A REPLY

For the example see the API Modify customer call

 

Delete customer profile

Delete existing customer profile. Profiles already sold to customers cannot be deleted (assignedUsers > 0).

Syntax
DELETE /resellers/username-reseller/profiles/id-profile
URL arguments
username_reseller*
string (40 characters)username used to register on the service
id_profile*
integernumerical ID of the profile whose information is to be returned

EXAMPLE OF A REQUEST

curl -D - -u user:password --digest \
-X DELETE \
http://api.smsmessenger.it/resellers/user/profiles/16

Return values
true or a hash with the error according to the outcome of the operation.

EXAMPLE OF A REPLY

Status Code: 200

{
"errors":[{
  "target":"services",
  "errors":[{
    "code":"skInvalid",
     "reason":"You can't delete a profile already assigned"
  }]
}]
}

It fails because in the previous example we had assigned this profile to a Customer

 

Tariff (for SMS sending)

The Tariff resource is accessible only by the entity that is directly responsible and is the container inside which are defined the Prices by nation and by Service, as shown in this table.

Service 1Service 2
Country 1PricePrice
Country 2PricePrice
DefaultPricePrice

The contents of the cells of the table are the prices requested for a given service for a given country and are to be defined with the API of the Transmission prices resource to which the Service and the country or geographical area that enable the cell to be set in the table will be passed. The countries and geographical areas are a fixed list from which you can choose and they are defined in the API of the Transmission prices.

If the resellable attribute (resellability) is set to false Top-ups cannot be created with this tariff. There are no impacts on the existing top-ups, with which the customers can continue to send messages.

Each Tariff is created with a default Price for each of the services included in it. It indicates the cost of the services when no Service/country or geographical area combination has been specified. The default prices are created with the maximum price possible for the corresponding Service and can be modified using the Price API but not deleted.

 

List of tariffs

Retrieves a list of the send Tariffs created by a Wholesaler/Reseller.

Syntax
GET /resellers/username-reseller/mtrates
URL arguments
username_reseller*
string (40 characters)username used to register on the service

EXAMPLE OF A REQUEST

curl -D - -u user:password --digest \
http://api.smsmessenger.it/resellers/user/mtrates

Return values
An array of:
created_at
date and time at which the tariff was created
id_mt_rate
numerical ID of the tariff
name
name of the tariff
note
notes about the tariff
resellable
specifies whether it is possible to create top-ups with the tariff (boolean)

EXAMPLE OF A REPLY

Status Code: 200

[{
"created_at":"2013-05-06T16:48:13+0200",
"id_mt_rate":1,
"name":"Estate",
"note":"rivenderla da giugno",
"resellable":0
},
{
"created_at":"2013-05-06T16:50:27+0200",
"id_mt_rate":2,
"name":"Autunno",
"note":"rivenderla da settembre",
"resellable":0
}]

 

View tariff

Retrieves the information about a single Tariff

Syntax
GET /resellers/username-reseller/mtrates/id-mt-rate
URL arguments
username_reseller*
string (40 characters)username used to register on the service
id_mt_rate*
integerid of the tariff on which indications are to be obtained

EXAMPLE OF A REQUEST

curl -D - -u user:password --digest \
http://api.smsmessenger.it/resellers/user/mtrates/1

Return values
created_at
date and time at which the tariff was created
id_mt_rate
numerical ID of the tariff
name
name of the tariff
note
notes about the tariff
resellable
boolean indicating whether top-ups can be created with the tariff

EXAMPLE OF A REPLY

Status Code: 200

{
"id_mt_rate":1,
"name":"Estate",
"note":"rivenderla da giugno",
"resellable":0,
"created_at":"2013-05-06T16:48:13+0200"
}

 

Create tariff

Create new send Tariff.

Syntax
POST /resellers/username-reseller/mtrates
BODY [Parameters ]
URL arguments
username_reseller*
string (40 characters)username used to register on the service
BODY parameters
name*
string (50 characters)name of the tariff
note
string (255 characters)notes about the tariff
resellable
booleanindicates whether the tariff can be sold or not

EXAMPLE OF A REQUEST

curl -D - -u user:password --digest \
-X POST \
http://api.smsmessenger.it/resellers/user/mtrates \
-d "name=Estate" \
-d "note=rivenderla%20da%20giugno" \
-d "resellable=0" \

Return values
created_at
date and time at which the tariff was created
id_mt_rate
numerical ID of the tariff
name
name of the tariff
note
notes about the tariff
resellable
indicates whether the tariff can be resold or not

EXAMPLE OF A REPLY

Status Code: 200

{
"id_mt_rate":1,
"name":"Estate",
"note":"rivenderla da giugno",
"resellable":0,
"created_at":"2013-05-06T16:48:13+0200"
}

 

Modify tariff

Modify Tariff.

Syntax
PUT /resellers/username-reseller/mtrates/id-mt-rate
BODY [Parameters ]
URL arguments
username_reseller*
string (40 characters)username used to register on the service
BODY parameters
name
string (50 characters)name of the tariff
note
string (255 characters)notes about the tariff
resellable
booleanindicates whether it is possible to create top-ups for the tariff

EXAMPLE OF A REQUEST

curl -D - -u user:password --digest \
-X PUT \
http://api.smsmessenger.it/resellers/user/mtrates/1 \
-d "note=Tariffa%20estate%202013" \
-d "resellable=1"

Return values
id_mt_rate
numerical ID of the tariff
name
name of the tariff
note
notes about the tariff
resellable
indicates the resellability of the tariff, 1 if it is, 0 if it is not
created_at
date and time at which the tariff was created

EXAMPLE OF A REPLY

Status Code: 200

{
"id_mt_rate":1,
"name":"Estate",
"note":"Tariffa estate 2013",
"resellable":1,
"created_at":"2013-05-06T16:48:13+0200"
}

 

Delete tariff

Delete existing Tariff. Tariffs with which top-ups have already been associated cannot be deleted. To do this the top-ups must be deleted first.

Syntax
DELETE /resellers/username-reseller/mtrates/id-mt-rate
URL arguments
username_reseller*
string (40 characters)username used to register on the service
id_mt_rate*
integerid of the tariff to be deleted

EXAMPLE OF A REQUEST

curl -D - -u user:password --digest \
-X DELETE \
http://api.smsmessenger.it/resellers/user/mtrates/1

Return values
true or false according to the result of the operation.

EXAMPLE OF A REPLY

Status Code: 200

{
"errors":[{
  "target":"mtrate",
  "errors":[{
    "code":"skCannotDelete",
     "reason":"To delete a mtrate, delete the associated mtprices first"
   }]
}]
}

Fist you must call the API to obtain the list of MtPrice related to this MtRate and delete them.

 

Price (for SMS sending)

The prices of a sending service are defined by the country or geographical area, and indicate, for example, how much it costs to send a 'Classic SMS' message (a service) in Italy (a country) or to other EU countries (a geographical area).

These are the steps that make up the procedure for determining the cost of a message:

  • You can trace the country from the destination telephone number.
  • The service can be traced from the type of message.
  • From the name of the sender you can trace his oldest Top-up associated with a Tariff that has prices for that Service.
  • From the tariff, service and country data a Price can be found. If one exists, that is the cost of the message.
  • If the Price does not exist, a search is run for the tariff, service and geographical area combination to which the country belongs (the list is here). If one exists, that is the cost of the message.
  • If no correspondence was found, the cost of the message will be determined by the default price for the tariff and service combination. Each Tariff is created with a default price for each service. These default prices can only be modified and not deleted so a price can always be found.

The prices for the countries contain the country attribute (ISO 3166 two-character code) while those for geographical areas contain the id-geographical-area attribute (a numerical code). The default prices have neither of these attributes.

Prices are always associated with a Tariff so sending with the same Service and country (or geographical area) combination can be offered at different prices providing they are in different tariffs. For example, with reference to the example Summer and Autumn tariffs used previously, the 'Classic SMS' service for sending to the EU could be offered at a lower price in the Summer tariff and a higher one in the Autumn tariff.

The Price has a position attribute that can be used to indicate the order in which the prices are presented. Its actual use and method adopted depend on the client.

Calls to the price API differ from those of the other resources in that they are transactional on a set of prices. The calls for the lists and the deletions apply to all prices with the same country, geographical area or default price (in the latter case, it cannot be deleted). Creation calls do not create a single price but all those with the country or geographical area, which are therefore all to be passed together. Similarly, the modification calls apply to all prices for a country, geographical area or default price.

To keep the documentation compact and avoid repetition in the syntax of the calls, all three variants will appear. On the lists of arguments and return values, it will be indicated that the country and id_geographical_area are only returned for some calls.

 

List of prices

The list may be requested on three levels of detail.

  • List of the prices of a country or a single geographical area.
  • List of the prices of all countries, all geographical areas or default prices
  • Global list on which the list of all Prices of a given Tariff are returned, by the country, geographical area and default price.
Syntax
GET /resellers/username-reseller/mtrates/id-mt-rate/mtprices/countries/country
GET /resellers/username-reseller/mtrates/id-mt-rate/mtprices/geoareas/id-geographical-area

GET /resellers/username-reseller/mtrates/id-mt-rate/mtprices/countries
GET /resellers/username-reseller/mtrates/id-mt-rate/mtprices/geoareas
GET /resellers/username-reseller/mtrates/id-mt-rate/mtprices/defaults

GET /resellers/username-reseller/mtrates/id-mt-rate/mtprices
URL arguments
username_reseller*
string (40 characters)username used to register on the service
id_mt_rate*
integerID of the tariff
country
string (2 characters)country code
id_geographical_area
integerid of the geographical area

EXAMPLE OF A REQUEST

curl -D - -u user:password --digest \
http://api.smsmessenger.it/resellers/user/mtrates/1/mtprices/countries/it

curl -D - -u user:password --digest \
http://api.smsmessenger.it/resellers/user/mtrates/1/mtprices/geoareas/3

curl -D - -u user:password --digest \
http://api.smsmessenger.it/resellers/user/mtrates/1/mtprices/countries

curl -D - -u user:password --digest \
http://api.smsmessenger.it/resellers/user/mtrates/1/mtprices/geoareas

curl -D - -u user:password --digest \
http://api.smsmessenger.it/resellers/user/mtrates/1/mtprices/defaults

curl -D - -u user:password --digest \
http://api.smsmessenger.it/resellers/user/mtrates/1/mtprices

Return values
Array di
id
country code or geographical area code, does not appear in the return values for defaults
mtprices
array of prices for the id indicated

The mtprices array is made up of elements with these attributes:

country
country code, only appears in the return values for countries
id_geographical_area
numerical ID of the geographical area, only in the return values for geoareas
id_mt_price
numerical ID of the price
id_mt_rate
numerical ID of the tariff
id_service
numerical ID of the service
position
order of presentation
price
price of the service

EXAMPLE OF A REPLY

Reply to the GET .../mtprices/defaults

Status Code: 200

[{
  "id":"it",
  "mtprices":[{
  "country":"it",
    "id_mt_price":3,
    "id_mt_rate":1,
    "id_service":1,
    "position":null,
    "price":"0.100000"
  }, {
    "country":"it",
    "id_mt_price":4,
    "id_mt_rate":1,
    "id_service":2,
    "position":null,
    "price":"0.190000"
  }]
}]

Reply to the GET .../mtprices/defaults

Status Code: 200

[{
  "id":3,
  "mtprices":[{
    "id_geographical_area":3,
    "id_mt_price":7,
    "id_mt_rate":1,
    "id_service":1,
    "position":null,
    "price":"0.150000"
   }, {
    "id_geographical_area":3,
    "id_mt_price":8,
    "id_mt_rate":1,
    "id_service":2,
    "position":null,
    "price":"0.250000"
   }]
}

Reply to the GET .../mtprices/defaults

The reply is divided into subarrays, one for each country. The country’s ID is present in the array and is repeated in the single Prices.

Status Code: 200

[{
  "id":"it",
  "mtprices":[{
  "country":"it",
    "id_mt_price":3,
    "id_mt_rate":1,
    "id_service":1,
    "position":null,
    "price":"0.100000"
  }, {
    "country":"it",
    "id_mt_price":4,
    "id_mt_rate":1,
    "id_service":2,
    "position":null,
    "price":"0.190000"
  }]
}, {
  "id":"fr",
  "mtprices":[{
  "country":"fr",
    "id_mt_price":5,
    "id_mt_rate":1,
    "id_service":1,
    "position":null,
    "price":"0.120000"
  }, {
    "country":"fr",
    "id_mt_price":6,
    "id_mt_rate":1,
    "id_service":2,
    "position":null,
    "price":"0.210000"
  }]
}]

Reply to the GET .../mtprices/defaults

The reply has a similar structure to the previous one and is divided by the id_geographical_area.

Status Code: 200

[{
  "id":3,
  "mtprices":[{
    "id_geographical_area":3,
    "id_mt_price":7,
    "id_mt_rate":1,
    "id_service":1,
    "position":null,
    "price":"0.150000"
   }, {
    "id_geographical_area":3,
    "id_mt_price":8,
    "id_mt_rate":1,
    "id_service":2,
    "position":null,
    "price":"0.250000"
   }]
}, {
  "id":6,
  "mtprices":[{
    "id_geographical_area":6,
    "id_mt_price":9,
    "id_mt_rate":1,
    "id_service":1,
    "position":null,
    "price":"0.200000"
   }, {
    "id_geographical_area":6,
    "id_mt_price":10,
    "id_mt_rate":1,
    "id_service":2,
    "position":null,
    "price":"0.290000"
   }]
}]

Reply to the GET .../mtprices/defaults

Note that the array of default prices is not divided into subarrays, in that there is no other hierarchical level.

Status Code: 200

[{
"id_mt_price":1,
"id_mt_rate":1,
"id_service":1,
"position":null,
"price":"0.064000"
},
{
"id_mt_price":2,
"id_mt_rate":1,
"id_service":2,
"position":null,
"price":"0.068000"
}]

Reply to GET .../mtprices

For the sake of brevity, only the general structure of the reply is given with the classes of the objects in the arrays. The array formats are identical to those of the previous three replies.

Status Code: 200

{
"countries":[
  {"id":"it", "mtprices":[ array degli MtPrice 3 e 4]}
  {"id":"fr", "mtprices":[ array degli MtPrice 5 e 6]}
],
"geoareas": [
  {"id":3, "mtprices":[ array degli MtPrice 7 e 8 ]},
  {"id":6, "mtprices":[ array degli MtPrice 9 e 10]}
],
"defaults": [ array degli MtPrice 1 e 2 ]
}

 

Create price

Creates all the prices for a given country or geographical area, one for each Service in the Tariff. The array comprising all the prices that will be created within a transaction and immediately available must be passed as an argument (except for the resellable attribute of the Tariff).

Default prices cannot be created as they are already created together with the Tariff.

The list of geographical areas with their numerical codes and the countries that make them up is here.

Syntax
POST /resellers/username-reseller/mtrates/id-mt-rate/mtprices/countries/country
POST /resellers/username-reseller/mtrates/id-mt-rate/mtprices/geoareas/id-geographical-area
BODY [Parameters ]
URL arguments
username_reseller*
string (40 characters)username used to register on the service
id_mt_rate*
integerID of the tariff
country
only for country calls, string (2 characters)ISO country code
Required parameters
List of country codes
id_geographical_area
only for geoarea calls, integernumerical ID of the geographical area
BODY parameters
id_service*
integernumerical ID of the service whose price is to be specified
price*
decimal(11, 6)price of the service, must be indicated with a decimal point and not a comma
position
integerorder of presentation

EXAMPLE OF A REQUEST

To create a country’s prices

curl -D - -u user:password --digest \
-X POST \
http://api.smsmessenger.it/resellers/user/mtrates/1/mtprices/countries/it \
-d "mtprices[0][id_service]=1" \
-d "mtprices[0][price]=0.10" \
-d "mtprices[1][id_service]=2" \
-d "mtprices[1][price]=0.19"

To create a geographical area’s prices

curl -D - -u user:password --digest \
-X POST \
http://api.smsmessenger.it/resellers/user/mtrates/1/mtprices/geoareas/3 \
-d "mtprices[0][id_service]=1" \
-d "mtprices[0][price]=0.15" \
-d "mtprices[1][id_service]=2" \
-d "mtprices[1][price]=0.25"

Return values
Un array di
id_mt_price
numerical ID of the price
id_mt_rate
numerical ID of the tariff
id_service
numerical ID of the service
position
Determines the line of the Prices table in which the GUI should show this price
price
price of the service

EXAMPLE OF A REPLY

Reply to the POST .../countries/it

Status Code: 200

[{
"id_mt_price":3,
"id_mt_rate":1,
"id_service":1,
"position":null,
"price":"0.100000"
}, {
"id_mt_price":4,
"id_mt_rate":1,
"id_service":2,
"position":null,
"price":"0.190000"
}]

Reply to the POST .../geoareas/3

Status Code: 200

[{
"id_mt_price":5,
"id_mt_rate":1,
"id_service":1,
"position":null,
"price":"0.120000"
}, {
"id_mt_price":6,
"id_mt_rate":1,
"id_service":2,
"position":null,
"price":"0.210000"
}]

 

Modify price

Price modification is transactional and is applied at the same time to all the Prices of a given country, geographical area or default price. All these Prices are to be passed as an argument, including those of the services that are not modified.

The list of geographical areas with their numerical codes and the countries that make them up is here.

Syntax
PUT /resellers/username-reseller/mtrates/id-mt-rate/mtprices/countries/country
PUT /resellers/username-reseller/mtrates/id-mt-rate/mtprices/geoareas/id-geographical-area
PUT /resellers/username-reseller/mtrates/id-mt-rate/mtprices/defaults
BODY [Parameters ]
URL arguments
username_reseller*
string (40 characters)username used to register on the service
id_mt_rate*
integerid of the tariff to be modified
country
only for country calls, string (2 characters)ISO country code
Required parameters
List of country codes
id_geographical_area
only for geoarea calls, integernumerical ID of the geographical area
BODY parameters
id_mt_price*
integerprice id
id_service*
integerid of the service
position
integerdisplay order
price*
decimal(11, 6)price of the service

EXAMPLE OF A REQUEST

To change a country’s prices

curl -D - -u user:password --digest \
-X PUT \
http://api.smsmessenger.it/resellers/user/mtrates/1/mtprices/countries/it \
-d "mtprices[0][id_mt_price]=3" \
-d "mtprices[0][id_service]=1" \
-d "mtprices[0][price]=0.10" \
-d "mtprices[1][id_mt_price]=4" \
-d "mtprices[1][id_service]=2" \
-d "mtprices[1][price]=0.20"

To change the default prices

curl -D - -u user:password --digest \
-X PUT \
http://api.smsmessenger.it/resellers/user/mtrates/1/mtprices/geoareas/3 \
-d "mtprices[0][id_mt_price]=5" \
-d "mtprices[0][id_service]=1" \
-d "mtprices[0][price]=0.15" \
-d "mtprices[1][id_mt_price]=6" \
-d "mtprices[1][id_service]=2" \
-d "mtprices[1][price]=0.26"

To change the default prices

curl -D - -u user:password --digest \
-X PUT \
http://api.smsmessenger.it/resellers/user/mtrates/1/mtprices/defaults \
-d "mtprices[0][id_mt_price]=1" \
-d "mtprices[0][id_service]=1" \
-d "mtprices[0][price]=0.30" \
-d "mtprices[1][id_mt_price]=2" \
-d "mtprices[1][id_service]=2" \
-d "mtprices[1][price]=0.40"

Return values

An array of Prices containing updated prices is returned. The elements of the array have the attributes

id_mt_price
numerical ID of the price
id_mt_rate
numerical ID of the tariff
id_service
numerical ID of the service
id_geographical_area
numerical ID of the geographical area, only for geoarea calls
country
country code, only for country calls
position
order of presentation
price
price of the service

EXAMPLE OF A REPLY

Status Code: 200

{
"country":"fr",
"id_geographical_area":null,
"id_mt_price":4,
"id_mt_rate":1,
"id_service":2,
"position":null,
"price":"0.032000"
}

 

Delete price

Deletions are transactional and occur at the same time on all the Prices of a given country or geographical area. Default prices cannot be deleted. These prices are created together with the Tariff and can only be modified.

The list of geographical areas with their numerical codes and the countries that make them up is here.

Syntax
DELETE /resellers/username-reseller/mtrates/id-mt-rate/mtprices/countries/country
DELETE /resellers/username-reseller/mtrates/id-mt-rate/mtprices/geoareas/id-geographical-area
URL arguments
username_reseller*
string (40 characters)username used to register on the service
id_mt_rate*
integerid of the tariff whose prices are to be deleted
country
only for country calls, string (2 characters)ISO country code
Required parameters
List of country codes
id_geographical_area
only for geoarea calls, integernumerical ID of the geographical area

EXAMPLE OF A REQUEST

To delete a country’s prices

curl -D - -u user:password --digest \
-X DELETE \
http://api.smsmessenger.it/resellers/user/mtrates/1/mtprices/countries/it

To delete a geographical area’s prices

curl -D - -u user:password --digest \
-X DELETE \
http://api.smsmessenger.it/resellers/user/mtrates/1/mtprices/geoareas/3

Return values
true or false according to the result of the operation.

EXAMPLE OF A REPLY

Status Code: 200

true

 

Top-up (for SMS sending)

Top-ups are created by the persons that sell them. For the customer there is only a call for listing them, in the End customers API.

 

List of top-ups

Retrieves a list of a customer’s Top-ups.

Syntax
GET /resellers/username-reseller/customers/username-customer/mtrecharges
URL arguments
username_reseller*
string (40 characters)username used to register on the service
username_customer*
string (40 characters)username del Reseller / Final Customer

EXAMPLE OF A REQUEST

curl -D - -u user:password --digest \
http://api.smsmessenger.it/resellers/user/customers/mariorossi/mtrecharges

Return values
An array of:
id_mt_recharge
ID number of the top-up
id_mt_rate
ID number of the tariff
money_purchased
credit purchased
money_available
credit available
status
status of the top-up
created_at
date and time at which the top-up was created

EXAMPLE OF A REPLY

Status Code: 200

[{
"id_mt_recharge":1,
"id_mt_rate":3,
"money_purchased":"50.00",
"money_available":"23.824700",
"status":"active",
"created_at":"2013-05-07T17:11:00+0200"
},
{
"id_mt_recharge":2,
"id_mt_rate":3,
"money_purchased":"50.00",
"money_available":"50.00",
"status":"active",
"created_at":"2012-05-12T13:23:00+0200"
}]

 

Create top-up

Create new Top-up.

Syntax
POST /resellers/username-reseller/customers/username-customer/mtrecharges
BODY [Parameters ]
URL arguments
username_reseller*
string (40 characters)username used to register on the service
username_customer*
string (40 characters)username of the Reseller / Final Customer with whom the top-up is to be associated
BODY parameters
id_mt_rate*
integernumerical ID of the tariff for this top-up
money_purchased*
decimal(11, 6)credit to be loaded

EXAMPLE OF A REQUEST

curl -D - -u user:password --digest \
-X POST \
http://api.smsmessenger.it/resellers/user/customers/mariorossi/mtrecharges \
-d "id_mt_rate=3" \
-d "money_purchased=50.00"

Return values
id_mt_recharge
ID number of the top-up
id_mt_rate
ID number of the tariff
money_purchased
credit purchased
money_available
credit available
status
status of the top-up
created_at
date and time at which the top-up was created

EXAMPLE OF A REPLY

Status Code: 200

{
"id_mt_recharge":7,
"id_mt_rate":3,
"money_purchased":"50.00",
"money_available":"50.00",
"status":"active",
"created_at":"2013-05-16T15:45:24+0200"
}

 

Modify top-up

Only the status can be modified. To modify money_available, the top-up must be blocked and a new one created with the desired value.

Syntax
PUT /resellers/username-reseller/customers/username-customer/mtrecharges/id-mt-recharge
BODY [Parameters ]
URL arguments
username_reseller*
string (40 characters)username used to register on the service
username_customer*
string (40 characters)username of the Reseller / Final Customer associated with the top-up
id_mt_recharge*
integerid of the top-up to be modified, it must be a top-up of username-customer
BODY parameters
status*
stringthe status of the top-up
Required parameters
  • active
  • blocked

EXAMPLE OF A REQUEST

curl -D - -u user:password --digest \
-X PUT \
http://api.smsmessenger.it/resellers/user/customers/mariorossi/mtrecharges/7 \
-d "status=blocked"

Return values
id_mt_recharge
ID number of the top-up
id_mt_rate
ID number of the tariff
money_purchased
credit purchased
money_available
credit available
status
status of the top-up
created_at
date and time at which the top-up was created

EXAMPLE OF A REPLY

Status Code: 200

{
"id_mt_recharge":7,
"id_mt_rate":3,
"money_purchased":"50.00",
"money_available":"50.00",
"status":"blocked",
"created_at":"2013-05-16T15:45:24+0200"
}

 

Delete top-up

Delete Top-up.

Syntax
DELETE /resellers/username-reseller/customers/username-customer/mtrecharges/id-mt-recharge
URL arguments
username_reseller*
stringusername used to register on the service
username_customer*
stringusername of the Reseller / Final Customer whose top-up is to be deleted
id_mt_recharge*
integerid of the top-up to be deleted

EXAMPLE OF A REQUEST

curl -D - -u user:password --digest \
-X DELETE \
http://api.smsmessenger.it/resellers/user/customers/mariorossi/mtrecharges/7

Return values
true or false according to the result of the operation.

EXAMPLE OF A REPLY

Status Code: 200

true

 

Alert (for SMS sending)

Used to manage the top-up alerts for your customers. The alerts are created together with the customer and cannot be deleted.

There are three alerts distinguished by a position and a money-threeshold. The purpose of the position is to identify an alert during its modification. It has no influence on the order in which the notifications are made, which is regulated exclusively by the money-threeshold values. This means that there is no difference between having a money-threeshold of 100, 50 or 10 in positions 1, 2 and 3 or in positions 3, 2 and 1.

 

List of alerts

Retrieves a list of the alerts of one of your customers. Always contains three MtAlerts in positions 1, 2 and 3.

Syntax
GET /reseller/username-reseller/customers/username-customer/mtalerts
URL arguments
username_reseller*
string (40 characters)username used to register on the service
username_customer*
stringusername of customer whose alerts are to be listed

EXAMPLE OF A REQUEST

curl -D - -u user:password --digest \
http://api.smsmessenger.it/reseller/user/customers/mariorossi/mtalerts

Return values
An array of:
position
position of the alert
username
username of the customer with whom the alert is associated
money_threshold
limit within which the alert is to be sent
email_address_1
first email address to which the alert is to be sent
email_address_2
second email address to which the alert is to be sent
email_address_3
third email address to which the alert is to be sent
sms_phone_1
first phone number to which the alert is to be sent
sms_phone_2
second phone number to which the alert is to be sent

EXAMPLE OF A REPLY

Status Code: 200

[{
"position":1,
"username":"mariorossi",
"money_threshold":"100.000000",
"email_address_1":"allarme1@example.com",
"email_address_2":null,
"email_address_3":null,
"sms_phone_1":"395556677888",
"sms_phone_2":null
},
{
"position":2,
"money_threshold":"50.000000",
"username":"mariorossi",
"email_address_1":"allarme1@example.com",
"email_address_2":"allarme2@example.com",
"email_address_3":null,
"sms_phone_1":"395556677888",
"sms_phone_2":null
},
{
"position":3,
"username":"mariorossi",
"money_threshold":"20.000000",
"email_address_1":"allarme1@example.com",
"email_address_2":"allarme2@example.com",
"email_address_3":null,
"sms_phone_1":"395556677888",
"sms_phone_2":null
}]

 

View alert

Retrieves the details of an alert of one of your customers.

Syntax
GET /reseller/username-reseller/customers/username-customer/mtalerts/position
URL arguments
username_reseller*
string (40 characters)username used to register on the service
username_customer*
stringusername of customer to whom the alert refers
position*
integerposition of the alert whose information is required

EXAMPLE OF A REQUEST

curl -D - -u mariorossi:password --digest \
http://server/resellers/user/customers/mariorossi/mtalerts/1

Return values
position
position of the alert
username
username of the customer with whom the alert is associated
money_threshold
limit within which the alert is to be sent
email_address_1
first email address to which the alert is to be sent
email_address_2
second email address to which the alert is to be sent
email_address_3
third email address to which the alert is to be sent
sms_phone_1
first phone number to which the alert is to be sent
sms_phone_2
second phone number to which the alert is to be sent

EXAMPLE OF A REPLY

Status Code: 200

{
"position":1,
"username":"mariorossi",
"money_threshold":"100.000000",
"email_address_1":"allarme1@example.com",
"email_address_2":null,
"email_address_3":null,
"sms_phone_1":"395556677888",
"sms_phone_2":null
}

 

Modify alert

Modifies an alert of one of your customers.

Syntax
PUT /reseller/username-reseller/customers/username-customer/mtalerts/position
BODY [Parameters ]
URL arguments
username_reseller*
string (40 characters)username used to register on the service
username_customer*
stringusername of customer to whom the alert refers
position*
integerposition of the alert whose information is required
BODY parameters
money_threshold
decimal(11, 6)limit within which the alert is to be sent
email_address_1
string (60 characters)first email address to which the alert is to be sent
email_address_2
string (60 characters)second email address to which the alert is to be sent
email_address_3
string (60 characters)third email address to which the alert is to be sent
sms_phone_1
string (20 characters, digits only)first phone number to which the alert is to be sent
sms_phone_2
string (20 characters, digits only, no +)second phone number to which the alert is to be sent


EXAMPLE OF A REQUEST

curl -D - -u mariorossi:password --digest \
-X PUT \
http://server/resellers/user/customers/mariorossi/mtalerts/3 \
-d "money_threshold=10.00" \
-d "email_address_1=test%40example.com" \
-d "email_address_2=ceo%40example.com" \
-d "email_address_3=info%40example.com" \
-d "sms_phone_1=39333728374" \
-d "sms_phone_2=338291283"

Return values
position
position of the alert
username
username of the customer with whom the alert is associated
money_threshold
limit within which the alert is to be sent
email_address_1
first email address to which the alert is to be sent
email_address_2
second email address to which the alert is to be sent
email_address_3
third email address to which the alert is to be sent
sms_phone_1
first phone number to which the alert is to be sent
sms_phone_2
second phone number to which the alert is to be sent

EXAMPLE OF A REPLY

Status Code: 200

{
"position":1,
"username":"mariorossi",
"money_threshold":"10.00",
"email_address_1":"test@example.com",
"email_address_2":"ceo@example.com",
"email_address_3":"info@example.com",
"sms_phone_1":"39333728374",
"sms_phone_2":"338291283"
}

 

Tariff (for SMS reception)

The Tariff resource is only accessible to the entity that is directly responsible for it and it is the container inside which the Prices are set by the country and by the Service, as shown by this table.

A Tariff resource defines the name of the tariff and its resellability status. The details on the price requested must be defined using the API of the Reception prices resource.

Resellability enables tariffs that cannot be resold immediately to your customers to be created and tariffs to be blocked after the end of the period planned for their sale.

Each Tariff is created with a default Price for each of the services included in it. It indicates the cost of the services when no Service/country or geographical area combination has been specified. The default prices are created with the maximum price possible for the corresponding Service and can be modified using the Price API but not deleted.

 

List of tariffs

Syntax
GET /resellers/username-reseller/morates
URL arguments
username_reseller*
string (40 caratteri)username used to register on the service

EXAMPLE OF A REQUEST

curl -D - -u user:password --digest \
http://api.smsmessenger.it/resellers/user/morates

Return values
An array of:
created_at
date and time at which the tariff was created
id_mo_rate
numerical ID of the tariff
name
name of the tariff
note
notes about the tariff
resellable
specifies whether the tariff can be resold or not (boolean)

EXAMPLE OF A REPLY

Status Code: 200

[{
"id_mo_rate":10,
"name":"Ricezione",
"note":null,
"resellable":1,
"created_at":"2013-05-16T15:22:48+0200"
}]

 

View tariff

Retrieves the information about a single Tariff

Syntax
GET /resellers/username-reseller/morates/id-mo-rate
URL arguments
username_reseller*
string (40 characters)username used to register on the service
id_mo_rate*
integerid of the tariff on which indications are to be obtained

EXAMPLE OF A REQUEST

curl -D - -u user:password --digest \
http://api.smsmessenger.it/resellers/user/morates/10

Return values
created_at
date and time at which the tariff was created
id_mo_rate
numerical ID of the tariff
name
name of the tariff
note
notes about the tariff
resellable
boolean indicating whether top-ups can be created for the tariff

EXAMPLE OF A REPLY

Status Code: 200

{
"id_mo_rate":10,
"name":"Ricezione",
"note":null,
"resellable":1,
"created_at":"2013-05-16T15:22:48+0200"
}

 

Create tariff

Create new send Tariff.

The tariff is created with its Prices, which may then be set using the Price modifying API.

Syntax
POST /resellers/username-reseller/morates
BODY [Parameters ]
URL arguments
username_reseller*
string (40 characters)username used to register on the service
BODY parameters
name*
string (50 characters)name of the tariff
note
string (255 characters)notes about the tariff
resellable
booleanindicates whether top-ups can be created for this tariff

EXAMPLE OF A REQUEST

curl -D - -u user:password --digest \
-X POST \
http://api.smsmessenger.it/resellers/user/morates \
-d "name=Ricezione" \
-d "resellable=1"
Return values
created_at
date and time at which the tariff was created
id_mo_rate
numerical ID of the tariff
name
name of the tariff
note
notes about the tariff
resellable
indicates whether top-ups can be created for this tariff

EXAMPLE OF A REPLY

Status Code: 200

{
"id_mo_rate":10,
"name":"Ricezione",
"note":null,
"resellable":1,
"created_at":"2013-05-16T15:22:48+0200"
}

 

Modify tariff

Modify Tariff.

Syntax
PUT /resellers/username-reseller/morates/id-mo-rate
BODY [Parameters ]
URL arguments
username_reseller*
string (40 characters)username used to register on the service
BODY parameters
name
string (50 characters)name of the tariff
note
string (255 characters)notes about the tariff
resellable
booleanindicates whether it is possible to create top-ups for the tariff


EXAMPLE OF A REQUEST

curl -D - -u user:password --digest \
-X PUT \
http://api.smsmessenger.it/resellers/user/morates/10 \
-d "name=Ricezione%20estate%202013" \
-d "note=vendere%20da%20giugno" \
-d "resellable=0"

Return values
id_mo_rate
numerical ID of the tariff
name
name of the tariff
note
notes about the tariff
resellable
indicates whether it is possible to create top-ups for the tariff, 1 if it is, 0 if it is not
created_at
date and time at which the tariff was created

EXAMPLE OF A REPLY

Status Code: 200

{
"id_mo_rate":10,
"name":"Ricezione estate 2013",
"note":"rivendere da giugno",
"resellable":0,
"created_at":"2013-05-16T15:22:48+0200"
}

 

Delete tariff

Delete existing Tariff. Tariffs with which top-ups have already been associated cannot be deleted. To do this the top-ups must be deleted first.

Deleting a Tariff also removes the prices associated with it. This is the only way of deleting a top-up Price.

Syntax
DELETE /resellers/username-reseller/morates/id-mo-rate
URL arguments
username_reseller*
string (40 characters)username used to register on the service
id_mo_rate*
integerid of the tariff to be deleted

EXAMPLE OF A REQUEST

curl -D - -u user:password --digest \
-X DELETE \
http://api.smsmessenger.it/resellers/user/morates/10

Return values
true or false according to the result of the operation.

EXAMPLE OF A REPLY

Status Code: 200

true

 

Price (for SMS reception)

Defines the cost of receiving a message at a dedicated or shared number. The Prices are created together with tariff and can be modified. The only way of deleting them is to remove the Tariff with which they are associated.

 

List of prices

Retrieves the list of Prices.

Syntax
GET /resellers/username-reseller/morates/id-mo-rate/moprices
URL arguments
username_reseller*
string (40 characters)username used to register on the service
id_mo_rate*
integerID of the tariff

EXAMPLE OF A REQUEST

curl -D - -u user:password --digest \
http://api.smsmessenger.it/resellers/user/morates/10/moprices

Return values
An array of:
id_mo_price
numerical ID of the price
id_mo_rate
numerical ID of the tariff
price
the cost of one month
type
dedicated if the price is for a dedicated number or shared if it is for a shared number

EXAMPLE OF A REPLY

Status Code: 200

[{
"id_mo_price":1,
"id_mo_rate":10,
"price":"30.00",
"type":"dedicated"
},
{
"id_mo_price":2,
"id_mo_rate":10,
"price":null,
"type":"shared"
}]

The price for receiving messages at a dedicated number was set while that for receiving them at a shared number is still to be set.

 

Modify price

Used to set the receive price value, which is the only modifiable attribute. The resource is created with null price together with the corresponding Tariff.

Syntax
PUT /resellers/username-reseller/mtrates/id-mo-rate/moprices/id-mo-price
BODY [Parameters ]
URL arguments
username_reseller*
string (40 characters)username used to register on the service
id_mo_rate*
integerID of the tariff
id_mt_price*
integerid of the price to be modified
BODY parameters
price*
decimal(11, 6)the cost of one month

EXAMPLE OF A REQUEST

curl -D - -u user:password --digest \
-X PUT \
http://api.smsmessenger.it/resellers/user/morates/10/moprices/2 \
-d "price=20.00"

Return values
id_mo_price
numerical ID of the price
id_mo_rate
numerical ID of the tariff
price
the cost of one month
type
dedicated if the price is for a dedicated number or shared if it is for a shared number

EXAMPLE OF A REPLY

Status Code: 200

{
"id_mo_price":2,
"id_mo_rate":10,
"price":"20.00",
"type":"shared"
}

 

Flat-rate top-up (for SMS reception)

Flat-rate top-ups indicate the number of months for which the customer has purchased a reception service on a shared or dedicated number, at the cost indicated by the Price associated with the Tariff.

The reference to the dedicated or shared number is given by the id-mo-sold-keyword attribute that indicates the List of Keywords call

Top-ups can be blocked using the modification call and changing their status to revoked or blocked.

 

List of top-ups

Retrieves a list of a customer’s Top-ups.

Syntax
GET /resellers/username-reseller/customers/username-customer/morechargesflat
URL arguments
username_reseller*
string (40 characters)username used to register on the service
username_customer*
string (40 characters)username of the Reseller / Final Customer

EXAMPLE OF A REQUEST

curl -D - -u user:password --digest \
http://api.smsmessenger.it/resellers/user/customers/mariorossi/morechargesflat

Return values
An array of:
created_at
date and time at which the top-up was created
id_mo_recharge_flat
ID number of the top-up
id_mo_rate
ID number of the tariff
id_mo_sold_keyword
id number of the keyword (for receiving at shared numbers)
months_purchased
number of months purchased at the price indicated by the Tariff
status
status of the top-up (active, revoked, blocked, expired)
username
the customer’s username

EXAMPLE OF A REPLY

Status Code: 200

[{
"created_at":"2013-05-17T11:50:01+0200",
"id_mo_recharge_flat":1,
"id_mo_rate":3,
"id_mo_sold_keyword":2,
"months_purchased":3,
"status":"active",
"username":"mariorossi",
},
{
"created_at":"2013-05-17T11:52:15+0200",
"id_mo_recharge_flat":1,
"id_mo_rate":3,
"id_mo_sold_keyword":3,
"months_purchased":2,
"status":"active",
"username":"mariorossi"
}]

 

Create top-up

Create new Top-up.

As it is a flat-rate top-up, the price applied is the one that among the prices returned by the tariff has type = dedicated or shared, according to whether the mo_soldkeyword associated with the top-up concerns a dedicated or shared number.

The price at which the top-up was purchased is copied in the top-up to maintain the reference even if the price has changed subsequently.

Syntax
POST /resellers/username-reseller/customers/username-customer/morechargesflat
BODY [Parameters ]
URL arguments
username_reseller*
string (40 characters)username used to register on the service
username_customer*
string (40 caratteri)username of the Reseller / Final Customer with whom the top-up is to be associated
BODY parameters
id_mo_rate*
integernumerical ID of the tariff for this top-up
id_mo_sold_keyword*
integernumerical ID of the keyword for which the top-up is purchased
months_purchased*
intnumber of months to be credited

EXAMPLE OF A REQUEST

curl -D - -u user:password --digest \
-X POST \
http://api.smsmessenger.it/resellers/user/customers/mariorossi/morechargesflat \
-d "id_mo_rate=10" \
-d "id_mo_sold_keyword=2" \
-d "months_purchased=3"

Return values
created_at
date and time at which the top-up was created
id_mo_recharge_flat
ID number of the top-up
id_mo_rate
ID number of the tariff
id_mo_sold_keyword
id number of the keyword (for receiving at shared numbers)
months_purchased
number of months purchased at the price indicated by the Tariff
single_month_price
copy of the price indicated by the Tariff when the Top-up was created
status
status of the top-up (active, revoked, blocked, expired)
username
the customer’s username

EXAMPLE OF A REPLY

Status Code: 200

{
"created_at":"2013-05-17T11:50:01+0200",
"id_mo_recharge_flat":1,
"id_mo_rate":10,
"id_mo_sold_keyword":2,
"months_purchased":3,
"single_month_price":"30.00",
"status":"active",
"username":"mariorossi",
}

 

Modify top-up

Only the status can be modified. To modify money_available, the top-up must be blocked and a new one created with the desired value.

Syntax
PUT /resellers/username-reseller/customers/username-customer/morechargesflat/id-mo-recharge-flat
BODY [Parameters ]
URL arguments
username_reseller*
string (40 characters)username used to register on the service
username_customer*
string (40 characters)username of the Reseller / Final Customer associated with the top-up
id_mo_recharge_flat*
integerid of the top-up to be modified, it must be a top-up of username-customer
BODY parameters
status*
stringthe status of the top-up
Required parameters
  • active
  • revoked
  • blocked
  • expired

EXAMPLE OF A REQUEST

curl -D - -u user:password --digest \
-X PUT \
http://api.smsmessenger.it/resellers/user/customers/mariorossi/morechargesflat/1 \
-d "status=blocked"

Return values
created_at
date and time at which the top-up was created
id_mo_recharge_flat
ID number of the top-up
id_mo_rate
ID number of the tariff
id_mo_sold_keyword
id number of the keyword (for receiving at shared numbers)
months_purchased
number of months purchased at the price indicated by the Tariff
single_month_price
copy of the price indicated by the Tariff when the Top-up was created
status
status of the top-up (active, revoked, blocked, expired)
username
the customer’s username

EXAMPLE OF A REPLY

Status Code: 200

{
"created_at":"2013-05-17T11:50:01+0200",
"id_mo_recharge_flat":1,
"id_mo_rate":10,
"id_mo_sold_keyword":2,
"months_purchased":3,
"single_month_price":"30.00",
"status":"blocked",
"username":"mariorossi",
}

 

Delete top-up

Delete Top-up.

Syntax
DELETE /resellers/username-reseller/customers/username-customer/morechargesflat/id-mo-recharge-flat
URL arguments
username_reseller*
stringusername used to register on the service
username_customer*
stringusername of the Reseller / Final Customer whose top-up is to be deleted
id_mo_recharge_flat*
integerid of the top-up to be deleted

EXAMPLE OF A REQUEST

curl -D - -u user:password --digest \
-X DELETE \
http://api.smsmessenger.it/resellers/user/customers/mariorossi/morechargesflat/1

Return values
true or false according to the result of the operation.

EXAMPLE OF A REPLY

Status Code: 200

true

 

Keywords sold (for SMS reception)

The keywords include both dedicated and shared numbers. They are distinguished by the value of the subkeyword field, which is null for dedicated numbers and is a character string for a Keyword on shared numbers.

Reception at a dedicated number (e.g. +39.1234) takes place when each message arriving at that number is sent to the phone numbers associated with the Keyword. The number is used exclusively by one user.

Reception at a shared number takes place when the first word of the message received is extracted (e.g. number +39.1234 and first word "SMS") and the Keyword with subkeyword corresponds to that word. The message is sent to the phone numbers associated with the Keyword, which will all belong to the same user.

Keywords are organized in a hierarchical structure that keeps track of the resale levels. A Wholesaler has a Keyword created automatically when he purchases it. One of his Reseller has a Keyword created by the Wholesaler when he resells it and the same applies to the Final Customer.

A dedicated number can be resold as such or subkeyword can be created and resold as a shared number. For a given number other subkeywords cannot be created at any level of the hierarchical structure. It is therefore possible to have the two keywords "1234 CIAO" and "1234 HELLO" but not "1234 CIAO HELLO" with more than one keyword in succession in the same message.

The connection between one level and another in the hierarchical structure is given by the id-parent-keyword attribute.

To create Keywords for yourself, use the receive customer API .

The Keyword expires at the end of the day indicated in expires-at.

 

List of sold Keywords

Retrieves a list of the sold Keywords.

Syntax
GET /resellers/username-reseller/customers/username-customer/mosoldkeywords
URL arguments
username_reseller*
string (40 characters)username used to register on the service
username_customer*
string (40 characters)username del Reseller / Final Customer

EXAMPLE OF A REQUEST

curl -D - -u user:password --digest \
http://api.smsmessenger.it/resellers/user/customers/mariorossi/mosoldkeywords

Return values
An array of:
alert_enabled
indicates the presence of an alert on the expiry of the keyword
created_at
date and time at which the keyword was created
expires_at
date and time at which the keyword expires
id_parent_keyword
numerical ID of the parent keyword, null if it is the first in the hierarchy
id_mo_sold_keyword
numerical ID of the keyword
number
number at which the messages are received
status
status of the keyword ('test', 'active', 'grace', 'expired', 'revoked', 'blocked')
subkeyword
the first word of the keyword or null for a keyword that represents a dedicated number
username
the customer’s username

EXAMPLE OF A REPLY

Status Code: 200

[{
"alert_enabled":0,
"created_at":"2013-05-20T14:37:34+0200",
"expires_at":"2013-08-20T23:59:59+0200",
"id_parent_keyword":1,
"id_mo_sold_keyword":2,
"number":"1234",
"status":"active",
"subkeyword":"SMS",
"username":"mariorossi"
}]

 

View the Keyword sold

Show the details of a Tariff.

Syntax
GET /resellers/username-reseller/customers/username-customer/mosoldkeywords/id-mo-sold-keyword
URL arguments
username_reseller*
string (40 characters)username used to register on the service
username_customer*
string (40 characters)username of the Reseller / Final Customer
id_mo_sold_keyword*
intnumerical ID of the keyword

EXAMPLE OF A REQUEST

curl -D - -u user:password --digest \
http://api.smsmessenger.it/resellers/user/customers/mariorossi/mosoldkeywords/2

Return values
alert_enabled
indicates the presence of an alert on the expiry of the keyword
created_at
date and time at which the keyword was created
expires_at
date and time at which the keyword expires
id_parent_keyword
numerical ID of the parent keyword, null if it is the first in the hierarchy
id_mo_sold_keyword
numerical ID of the keyword
number
number at which the messages are received
status
status of the keyword ('test', 'active', 'grace', 'expired', 'revoked', 'blocked')
subkeyword
the first word of the keyword or null for a keyword that represents a dedicated number
username
the customer’s username

EXAMPLE OF A REPLY

Status Code: 200

{
"alert_enabled":0,
"created_at":"2013-05-20T14:37:34+0200",
"expires_at":"2013-08-20T23:59:59+0200",
"id_parent_keyword":1,
"id_mo_sold_keyword":2,
"number":"1234",
"status":"active",
"subkeyword":"SMS",
"username":"mariorossi"
}

 

Create sold keywords

You must indicate the id-parent-keyword, equivalent to the 'id-mo-sold-keyword of one of your Keywords, the subkeyword, which is null to resell a dedicated number, and the expiry date of the Keyword. The Keyword will expire at the end of the day indicated.

The id-parent-keyword parameter must be one of your own keywords, which you can find with the call List of keywords

Syntax
POST /resellers/username-reseller/customers/username-customer/mosoldkeywords
URL arguments
username_reseller*
string (40 characters)username used to register on the service
username_customer*
string (40 caratteri)username of the Reseller / Final Customer
BODY parameters
id_parent_keyword*
intnumerical id of the parent keyword
subkeyword
string (50 characters)first word of the message, only when a subkeyword is created for a dedicated number

EXAMPLE OF A REQUEST

curl -D - -u user:password --digest \
-X POST \
http://api.smsmessenger.it/resellers/user/customers/mariorossi/mosoldkeywords
-d "id_parent_keyword=1"
-d "subkeyword=SMS"

Return values
created_at
date and time at which the keyword was created
id_parent_keyword
numerical ID of the parent keyword, null if it is the first in the hierarchy
id_mo_soldkeyword
numerical ID of the keyword
number
number at which the messages are received
subkeyword
the first word of the keyword or null for a keyword that represents a dedicated number
username
the customer’s username

EXAMPLE OF A REPLY

Status Code: 200

[{
"created_at":"2013-05-20T14:37:34+0200",
"expires_at":"2013-08-20T23:59:59+0200",
"id_parent_keyword":null,
"id_mo_soldkeyword":1,
"number":"1234",
"status":"active",
"subkeyword":"SMS",
"username":"mariorossi"
}]

 

modify-sold-keywords

To sell a keyword to another customer a new one must be created, with the same subkeyword and a different period of validity. We recommend setting a grace period so that the new user assigned the Keyword does not receive any messages sent to the previous user: the senders may not be aware of the end of the period of use of the Keyword and continue to send messages after its expiry date.

More than one Keyword with the same subkeyword cannot be active during the same period of time.

Syntax
PUT /resellers/username-reseller/customers/username-customer/mosoldkeywords/id-mo-sold-keyword
URL arguments
id_mo_sold_keyword*
intnumerical ID of the keyword
username_reseller*
string (40 characters)username used to register on the service
username_customer*
string (40 characters)username of the Reseller / Final Customer
BODY parameters

EXAMPLE OF A REQUEST

curl -D - -u user:password --digest \
-X PUT \
http://api.smsmessenger.it/resellers/user/customers/mariorossi/mosoldkeywords

Return values
created_at
date and time at which the keyword was created
id_parent_keyword
numerical ID of the parent keyword, null if it is the first in the hierarchy
id_mo_soldkeyword
numerical ID of the keyword
number
number at which the messages are received
subkeyword
the first word of the keyword or null for a keyword that represents a dedicated number
username
the customer’s username

EXAMPLE OF A REPLY

Status Code: 200

{
"alert_enabled":0,
"created_at":"2013-05-20T14:37:34+0200",
"expires_at":"2013-08-20T23:59:59+0200",
"full":1,
"id_parent_keyword":null,
"id_mo_soldkeyword":1,
"number":"1234",
"status":"blocked",
"subkeyword":"SMS",
"username":"mariorossi"
}

 

End customer API

to handle the data of your customers. In the following examples, you access the data of your account and you must do so using the End customers API in that for this type of access the role within the user hierarchy is not important. The URLs called byuser always refer to the same server, because the administrative and non-administrative operations of a user all take place on the same server with the same account. The examples also include calls made by one of the customers of user, which are made to the server in the admin-domain of user.

 

Customer

The resource allows access to the information about your own account.

 

View customer

A user can only use this API call to gain access to the information about his own account, so only the value of your own user name is accepted for the username_customer parameter.

Syntax
GET /customers/username-customer
URL arguments
username_customer*
string (40 characters)username used to register on the service

EXAMPLE OF A REQUEST

curl -D - -u mariorossi:password --digest \
http://server/customers/mariorossi

Return values
domain
domain to which the user makes the API calls
business_name
first name and surname and/or company name
contact
contact information
created_at
time and date on which the user was created
admin_domain
the user’s domain, null for the Final Customers
email
email associated with the account
id_profile
numerical ID of the profile
id_default_new_profile
numerical ID of the default profile
international_prefix
country code (it, gb ..)
locale
the user’s language (it_IT, en_US)
note
notes about the user
phone
phone number
status
current status of the account(active, disable)
timezone
the user’s time zone
type
the various user types (reseller, customer)
username
the user’s username
currency
user's currency

EXAMPLE OF A REPLY

Status Code: 200

{
"admin_domain":"example.com",
"business_name":null,
"contact":null,
"created_at":"2013-04-30T12:44:06+0200",
"domain":"server",
"email":"mariorossi@example.com",
"id_default_new_profile":15,
"id_profile":4,
"international_prefix":"it",
"locale":"it_IT",
"note":null,
"phone":null,
"status":"active",
"timezone":"itrom",
"type":"reseller",
"username":"mariorossi",
"currency":"EUR"
}

mariorossi is the reseller created by users in the previous examples.

The admin_domain = example.com attribute is the server managed by mariorossi, to which his customers make calls.
The domain = server attribute is the server of mariorossi’s supplier and the one to which mariorossi makes calls.
mariorossi’s supplier (who is a user) makes his own calls to api.smsmessenger.it, as shown in all the examples.

 

Modify customer


Modify data in profile.

Syntax
PUT /customers/username-customer
BODY [Parameters ]
URL arguments
username_customer*
stringusername used to register on the service
BODY parameters
business_name
stringfirst name and surname and/or company name
contact
stringcontact information
admin_domain
only for the Wholesalers/Resellers, stringthe user’s domain
email
stringemail associated with the account
locale
stringuser’s language
Required parameters
  • it_IT
  • en_US
id_default_new_profile
only for the Wholesalers/Resellers, integernumerical ID of the default profile
international_prefix
string (2 characters)country code (it, uk, ...)
Required parameters
List of country codes
phone
stringphone number
currency
stringuser's currency
Required parameters
  • EUR
  • GBP
  • USD


EXAMPLE OF A REQUEST

curl -D - -u user:password --digest \
-X PUT \
http://server/customers/user \
-d "business_name=Nuova%20Sample%20Company" \
-d "phone=%2B390212345678"

Note that the + at the start of the phone number is coded as %2B

Return values
domain
domain of the user that created this
business_name
first name and surname and/or company name
contact
contact information
created_at
time and date on which the user was created
admin_domain
the user’s domain
email
email associated with the account
id_default_new_profile
numerical ID of the default profile
international_prefix
country code (it, uk, ...)
locale
the user’s language (it_IT, en_US)
note
notes about the user
phone
phone number
timezone
the user’s time zone
status
current status of the account (active, disabled)
type
the various user types (wholesaler, reseller, customer)
username
the user’s username
currency
user's currency

EXAMPLE OF A REPLY

Status Code: 200

{
"admin_domain":"server",
"business_name":"Nuova Sample Company",
"contact":null,
"created_at":"2013-04-20T11:47:19+0200",
"domain":"example.net",
"email":"user@example.net",
"id_default_new_profile":2,
"id_profile":1,
"international_prefix":"it",
"locale":"it_IT",
"note":null,
"phone":"+390212345678",
"status":"active",
"timezone":"itrom",
"type":"wholesaler",
"username":"user",
"currency":"EUR"
 }

 

Service

The resource gives access to all the services that can be used by your user.

 

List of services

Retrieves a list of your services. Only those included in your Profile can be seen.

Syntax
GET /customers/username-customer/services
URL arguments
username_customer*
stringusername used to register on the service

EXAMPLE OF A REQUEST

curl -D - -u user:password --digest \
http://api.smsmessenger.it/customers/user/services

curl -D - -u mariorossi:password --digest \
http://server/customers/mariorossi/services

mariorossi is a user customer and therefore makes calls to the user server.

Return values
An array of:
id_service
id of the service
type
service type, with the same codes described here
name
name of the service

EXAMPLE OF A REPLY

This is the reply to mariorossi’s call

Status Code: 200

[{
"id_service":4,
"type":"R",
"name":"SMS con notifica",
},
{
"id_service":5,
"type":"D",
"name":"SMS Classic",
}]

The example assumes that these are the services included in the profile currently assigned to mariorossi.

 

Customer profile

Using the End customer API you can access the information about the profiles provided by the reseller to the customer. More information about the profiles is given in their part of the Backoffice API.

 

View customer Profile

Retrieves the detailed information about a profile.
Syntax
GET /customers/username-customer/profiles/id-profile
URL arguments
username_customer*
string (40 characters)username used to register on the service
id_profile*
integernumerical ID of the profile

EXAMPLE OF A REQUEST

curl -D - -u mariorossi:password --digest \
http://server/customer/mariorossi/profiles/5

Return values
id_profile
numerical ID of the profile
name
name of the profile

EXAMPLE OF A REPLY

Status Code: 200

{
"id_profile":5,
"name":"Invio SMS"
}

 

Tariff (for SMS sending)

Used to access the data of the Tariffs of your Wholesaler/Reseller.

 

View tariff

Shows the details of a Tariff.

Syntax
GET /customers/username-customer/mtrates/id-mt-rate
URL arguments
username_customer*
stringusername used to register on the service
id_mt_rate*
integerthe id of the Tariff to be viewed

EXAMPLE OF A REQUEST

curl -D - -u user:password --digest \
http://server/customers/mariorossi/mtrates/2

Return values
id_mt_rate
numerical ID of the tariff
name
name of the tariff
note
notes about the tariff
resellable
specifies whether the tariff can be resold or not (boolean)
created_at
date and time at which the tariff was created

EXAMPLE OF A REPLY

Status Code: 200

{
"id_mt_rate":2,
"name":"Autunno",
"note":"rivenderla da settembre",
"resellable":0,
"created_at":"2013-05-06T16:50:27+0200"
}

The mt_rate codes can be obtained using MtRechargeList()

 

Price (for SMS sending)

Used to access the prices paid by your user.

 

List of prices

Retrieves the list of all Prices of all countries, or all geographical areas or default prices. If the MtRate does not exist, it returns a blank list. The Prices are returned in an array.

Syntax
GET /customers/username-customer/mtrates/id-mt-rate/mtprices/countries
GET /customers/username-customer/mtrates/id-mt-rate/mtprices/geoareas
GET /customers/username-customer/mtrates/id-mt-rate/mtprices/defaults
GET /customers/username-customer/mtrates/id-mt-rate/mtprices
URL arguments
username_customer*
string (40 characters)username used to register on the service
id_mt_rate*
integernumerical ID of the tariff whose prices are to be returned

EXAMPLE OF A REQUEST

Request for the geographical areas’ prices

curl -D - -u mariorossi:password --digest \
http://server/customers/mariorossi/mtrates/3/mtprices/countries

Request for the geographical areas’ prices

curl -D - -u mariorossi:password --digest \
http://server/customers/mariorossi/mtrates/3/mtprices/geoareas

Request for the default prices

curl -D - -u mariorossi:password --digest \
http://server/customers/mariorossi/mtrates/3/mtprices/defaults

Request for all prices

curl -D - -u mariorossi:password --digest \
http://server/customers/mariorossi/mtrates/3/mtprices

Return values
Array di
id
country code or geographical area code, does not appear in the return values for defaults
mtprices
array of prices for the id indicated

The mtprices array is made up of elements with these attributes:

country
country code, only appears in the return values for countries
id_geographical_area
numerical ID of the geographical area, only in the return values for geoareas
id_mt_price
numerical ID of the price
id_mt_rate
numerical ID of the tariff
id_service
numerical ID of the service
position
order of presentation
price
price of the service

EXAMPLE OF A REPLY

Reply to GET .../countries

The reply is divided into subarrays, one for each country. The country’s ID is present in the array and is repeated in the single Prices.

Status Code: 200

[{
  "id":"it",
  "mtprices":[{
  "country":"it",
    "id_mt_price":23,
    "id_mt_rate":3,
    "id_service":1,
    "position":null,
    "price":"0.120000"
  }, {
    "country":"it",
    "id_mt_price":24,
    "id_mt_rate":3,
    "id_service":2,
    "position":null,
    "price":"0.210000"
  }]
}, {
  "id":"fr",
  "mtprices":[{
  "country":"fr",
    "id_mt_price":25,
    "id_mt_rate":3,
    "id_service":1,
    "position":null,
    "price":"0.140000"
  }, {
    "country":"fr",
    "id_mt_price":26,
    "id_mt_rate":3,
    "id_service":2,
    "position":null,
    "price":"0.230000"
  }]
}]

Reply to GET .../geoareas

The reply has a similar structure to the previous one and is divided by the id_geographical_area.

Status Code: 200

[{
  "id":3,
  "mtprices":[{
    "id_geographical_area":3,
    "id_mt_price":27,
    "id_mt_rate":3,
    "id_service":1,
    "position":null,
    "price":"0.170000"
   }, {
    "id_geographical_area":3,
    "id_mt_price":28,
    "id_mt_rate":3,
    "id_service":2,
    "position":null,
    "price":"0.270000"
   }]
}, {
  "id":6,
  "mtprices":[{
    "id_geographical_area":6,
    "id_mt_price":29,
    "id_mt_rate":3,
    "id_service":1,
    "position":null,
    "price":"0.220000"
   }, {
    "id_geographical_area":6,
    "id_mt_price":30,
    "id_mt_rate":3,
    "id_service":2,
    "position":null,
    "price":"0.310000"
   }]
}]

Reply to GET .../defaults

Note that the array of default prices is not divided into subarrays, in that there is no other hierarchical level.

Status Code: 200

[{
"id_mt_price":21,
"id_mt_rate":3,
"id_service":1,
"position":null,
"price":"0.064000"
},
{
"id_mt_price":22,
"id_mt_rate":3,
"id_service":2,
"position":null,
"price":"0.068000"
}]

Reply to GET .../mtprices

An object with the following 3 properties is returned: geoareas, countries and defaults. Each of these properties contains a data structure identical to the replies described above for geoareas, countries and default prices.

Status Code: 200

{
  "geoareas":[{
    "id":3,
    "mtprices":[{
      "id_geographical_area":3,
      "id_mt_price":27,
      "id_mt_rate":3,
      "id_service":1,
      "position":null,
      "price":"0.170000"
     }, {
      "id_geographical_area":3,
      "id_mt_price":28,
      "id_mt_rate":3,
      "id_service":2,
      "position":null,
      "price":"0.270000"
     }]
  }, {
    "id":6,
    "mtprices":[{
      "id_geographical_area":6,
      "id_mt_price":29,
      "id_mt_rate":3,
      "id_service":1,
      "position":null,
      "price":"0.220000"
     }, {
      "id_geographical_area":6,
      "id_mt_price":30,
      "id_mt_rate":3,
      "id_service":2,
      "position":null,
      "price":"0.310000"
     }]
  }],
  "countries":[{
    "id":"it",
    "mtprices":[{
    "country":"it",
      "id_mt_price":23,
      "id_mt_rate":3,
      "id_service":1,
      "position":null,
      "price":"0.120000"
    }, {
      "country":"it",
      "id_mt_price":24,
      "id_mt_rate":3,
      "id_service":2,
      "position":null,
      "price":"0.210000"
    }]
  }, {
    "id":"fr",
    "mtprices":[{
    "country":"fr",
      "id_mt_price":25,
      "id_mt_rate":3,
      "id_service":1,
      "position":null,
      "price":"0.140000"
    }, {
      "country":"fr",
      "id_mt_price":26,
      "id_mt_rate":3,
      "id_service":2,
      "position":null,
      "price":"0.230000"
    }]
  }],
  "defaults":[{
    "id_mt_price":21,
    "id_mt_rate":3,
    "id_service":1,
    "position":null,
    "price":"0.064000"
  }, {
    "id_mt_price":22,
    "id_mt_rate":3,
    "id_service":2,
    "position":null,
    "price":"0.068000"
  }]
}

 

Top-up (for SMS sending)

Used to access the Top-ups attributed to your user.

 

List of top-ups

Retrieves a list of a customer’s Top-ups.

The return values are identical to those that the %s would seeWholesaler/Reseller of the user with aGET.

Syntax
GET /customers/username-customer/mtrecharges
URL arguments
username_customer*
string (40 characters)username used to register on the service

EXAMPLE OF A REQUEST

curl -D - -u mariorossi:password --digest \
http://server/customers/mariorossi/mtrecharges

curl -D - -u user:password --digest \
http://api.smsmessenger.it/resellers/user/customers/mariorossi/mtrecharges

The two calls give the same result

Return values
An array of:
id_mt_recharge
ID number of the top-up
id_mt_rate
ID number of the tariff
money_purchased
credit purchased
money_available
credit available
status
status of the top-up
created_at
date and time at which the top-up was created

EXAMPLE OF A REPLY

Status Code: 200

[{
"id_mt_recharge":1,
"id_mt_rate":3,
"money_purchased":"50.00",
"money_available":"23.824700",
"status":"active",
"created_at":"2013-05-07T17:11:00+0200"
},
{
"id_mt_recharge":2,
"id_mt_rate":3,
"money_purchased":"50.00",
"money_available":"50.00",
"status":"active",
"created_at":"2012-05-12T13:23:00+0200"
}]

 

Alert (for SMS sending)

Used to manage the top-up alerts for your customers. The alerts are created together with the customer and cannot be deleted.

There are three alerts distinguished by a position and a money-threeshold. The purpose of the position is to identify an alert during its modification. It has no influence on the order in which the notifications are made, which is regulated exclusively by the money-threeshold values. This means that there is no difference between having a money-threeshold of 100, 50 or 10 in positions 1, 2 and 3 or in positions 3, 2 and 1.

 

List of alerts

Retrieves a list of the alerts of one of your customers. It always contains three MtAlerts in positions 1, 2 and 3.

Syntax
GET /customers/username-customer/mtalerts
URL arguments
username_customer*
string (40 characters)username used to register on the service

EXAMPLE OF A REQUEST

curl -D - -u user:password --digest \
http://api.smsmessenger.it/customers/mariorossi/mtalerts

Return values
An array of:
position
position of the alert
username
username of the customer with whom the alert is associated
money_threshold
limit within which the alert is to be sent
email_address_1
first email address to which the alert is to be sent
email_address_2
second email address to which the alert is to be sent
email_address_3
third email address to which the alert is to be sent
sms_phone_1
first phone number to which the alert is to be sent
sms_phone_2
second phone number to which the alert is to be sent

EXAMPLE OF A REPLY

Status Code: 200

[{
"position":1,
"username":"mariorossi",
"money_threshold":"100.000000",
"email_address_1":"allarme1@example.com",
"email_address_2":null,
"email_address_3":null,
"sms_phone_1":"395556677888",
"sms_phone_2":null
},
{
"position":2,
"money_threshold":"50.000000",
"username":"mariorossi",
"email_address_1":"allarme1@example.com",
"email_address_2":"allarme2@example.com",
"email_address_3":null,
"sms_phone_1":"395556677888",
"sms_phone_2":null
},
{
"position":3,
"username":"mariorossi",
"money_threshold":"20.000000",
"email_address_1":"allarme1@example.com",
"email_address_2":"allarme2@example.com",
"email_address_3":null,
"sms_phone_1":"395556677888",
"sms_phone_2":null
}]

 

View alert

Retrieves the details of an alert of one of your customers.

Syntax
GET /customers/username-customer/mtalerts/position
URL arguments
username_customer*
string (40 characters)username used to register on the service
position*
integerposition of the alert whose information is required

EXAMPLE OF A REQUEST

curl -D - -u mariorossi:password --digest \
http://server/customers/mariorossi/mtalerts/1

Return values
position
position of the alert
username
username of the customer with whom the alert is associated
money_threshold
limit within which the alert is to be sent
email_address_1
first email address to which the alert is to be sent
email_address_2
second email address to which the alert is to be sent
email_address_3
third email address to which the alert is to be sent
sms_phone_1
first phone number to which the alert is to be sent
sms_phone_2
second phone number to which the alert is to be sent

EXAMPLE OF A REPLY

Status Code: 200

{
"position":1,
"username":"mariorossi",
"money_threshold":"100.000000",
"email_address_1":"allarme1@example.com",
"email_address_2":null,
"email_address_3":null,
"sms_phone_1":"395556677888",
"sms_phone_2":null
}

 

Modify alert

Modify one of my alerts.

Syntax
PUT /customers/username-customer/mtalerts/position
BODY [Parameters ]
URL arguments
username_customer*
string (40 characters)username used to register on the service
position*
integerposition of the alert whose information is required
BODY parameters
money_threshold
decimal(11.6)limit within which the alert is to be sent
email_address_1
string (60 characters)first email address to which the alert is to be sent
email_address_2
string (60 characters)second email address to which the alert is to be sent
email_address_3
string (60 characters)third email address to which the alert is to be sent
sms_phone_1
string (20 characters, digits only)first phone number to which the alert is to be sent
sms_phone_2
string (20 characters, digits only, no +)second phone number to which the alert is to be sent


EXAMPLE OF A REQUEST

curl -D - -u mariorossi:password --digest \
-X PUT \
http://server/customers/mariorossi/mtalerts/3 \
-d "money_threshold=10.00" \
-d "email_address_1=test%40example.com" \
-d "email_address_2=ceo%40example.com" \
-d "email_address_3=info%40example.com" \
-d "sms_phone_1=39333728374" \
-d "sms_phone_2=338291283"

Return values
position
position of the alert
username
username of the customer with whom the alert is associated
money_threshold
limit within which the alert is to be sent
email_address_1
first email address to which the alert is to be sent
email_address_2
second email address to which the alert is to be sent
email_address_3
third email address to which the alert is to be sent
sms_phone_1
first phone number to which the alert is to be sent
sms_phone_2
second phone number to which the alert is to be sent

EXAMPLE OF A REPLY

Status Code: 200

{
"position":1,
"username":"mariorossi",
"money_threshold":"10.00",
"email_address_1":"test@example.com",
"email_address_2":"ceo@example.com",
"email_address_3":"info@example.com",
"sms_phone_1":"39333728374",
"sms_phone_2":"338291283"
}

 

Message (for SMS sending)

Used to send SMSs.

 

Write message

SMSs of the three types listed in the Services can be sent

  • F -> fixed
  • D -> dynamic no report
  • R -> dynamic with report

To be able to indicate a sender-string or a sender-number the user must have carried out the check procedure on at least one phone number.

Syntax
POST /mtmessages
BODY [Parameters ]
BODY parameters
sms_type*
stringtype of SMS to be sent, identified by a capital letter.
recipients*
array(string, string, ...)Contains the phone numbers of the recipients
The phone numbers must be in international format without the "+" or "00" prefix.
text*
stringText of the message br> The maximum length depends on the type of SMS.
f -> 1560 characters divided into 10 consecutive messages (1 of 10, 2 of 10, ...). The first message in the series is made up of 160 characters, the second of 152 and the following ones of 156.
d and r -> 1530 characters or 10 SMSs linked in a single message. For the counting method, see
sender_number
for D and R only, alternative to sender_string, integerUsed to specify any phone number as the sender.
The number is subject to agcom specifications.
Only checked sender numbers can be used.
sender_string
for D and R only, alternative to sender_number, string (11 characters)Used to specify an alphanumeric string to be used as the sender.
The string is subject to the translate("agcom") ?> specifications.
For it to be used the user must have had at least one number checked.
delivery_start
dates (ISO 8601)According to the format, the date and time are separated by the T character and the indication of the time zone as the difference in hours and minutes with respect to UTC time. For example, 2013-05-20t0730000200.
With this API sendings are not repeated, this feature is to be set expressly through the call of this API for each message to be sent.
encoding_scheme
for D and R only, stringEnables characters not belonging to the Latin alphabet (e.g. Arabic, Chinese, Korean, Cyrillic, Japanese and similar)
Accepted values:
  • normal-7-bit-default
  • ucs2
The use of "ucs2" and "normal" refers to the gsm-0338 standard and is not to be confused with UTF-8 and UTF-16. For example, the letter "à" is represented by 7 bits in GSM while it has 8 bits in UTF-8.
The conversion from the encoding of the text parameter (always UTF-8) to that indicated for sending messages takes place within the Send SMS method.
For F-type messages, the encoding is "normal".
validity_period
for D and R only, integerYou can specify the number of minutes (or hours) for which the operator is to attempt to send the SMS if the recipient is not reachable. It is expressed in minutes and is a whole number (minimum value 5 minutes). The default setting is 2 days = 2880 minutes (60*48).
user_reference
for R only, integerReference string of no more than 20 characters, personalizable, that will be returned together with the delivery report.
Characters supported: [a-zA-Z0-9-_+:;]
EXAMPLE OF A REQUEST
curl -D - -u mariorossi:password --digest \
-X POST http://server/mtmessages \
-d sms_type=R \
-d "recipients[]=393211234567&recipients[]=393212345678" \
-d "text=Testo%20del%20messaggio" \
-d "sender_string=Mario%20Rossi" \
-d "delivery_start=2013-05-20T07:30:00%2B0200" \
-d encoding_scheme=normal \
-d validity_period=2800 \
-d "user_reference=Esempio_uso_API"
 

In delivery_date the + character of the time zone has been coded as %2B.

Note the use of underscore in place of the space in user_reference.

Note: traditional long SMS counting method

The cost of the message will be counted every 153 characters, with the exception of the first SMS that will have 160, with a maximum of 1530 or 10 chained SMS.

Characters 	Number of Billed SMS
0-160 	        1
161-306 	2
307-459 	3
460-612 	4
613-765 	5
766-918		6
919-1071 	7
1072-1224 	8
1225-1377 	9
1378-1530 	10

Some characters count double:

[ 	        Open square bracket
\ 	        Backslash
] 	        Square bracket
^ 	        power
{ 	        Opening brace
| 	        Pipe
} 	        Closing Brace
~ 	        Tilde
€ 	        Euro symbol

For more details see http://en.wikipedia.org/wiki/GSM_03.38

sms-ucs2

The cost of the message will be counted every 67 characters, except for the first SMS, which will consist of 70, up to a maximum of 670 characters or 10 linked SMSs.

Characters  	Number of Billed SMS
0-70 	        1
71-134 	        2
135-201 	3
202-268 	4
269-335 	5
336-402 	6
403-469 	7
470-536 	8
537-603 	9
604-670 	10
Return values
id_dispatch
id of the sending operation
status
success or the message indicating why the SMS cannot be sent

EXAMPLE OF A REPLY

Status Code: 200

{
"id_dispatch":999999999
}

 

Destination of notifications

This resource manages the destination to which the notifications of the SMS messages sent will be delivered, for messages that include a notification.

If the destination number is not reachable, the server will try and redeliver the report every 30 minutes for a maximum of 6 attempts (maximum 3 hours after it was sent), after which it will be discarded.

Having modified the notification url, the setting will come into effect after 20 seconds.

The resource is created empty together with the Customer. It can be viewed and modified to change the destination. It cannot be deleted.

The parameters sent to the destination URL are

  • dispatch_idID number of the notification
  • message_idID number of the single SMS
  • recipientPhone number to which the SMS was sent
  • statusDelivery report code (see below for details)
  • error_codeDelivery report details (see below)
  • user_referenceReference string, it is returned if specified during the sending of a Classic SMS with a delivery report
  • server_date_timeDate of reception by our systems of the delivery report in format rfc-2822.
  • operator_date_timeDate of reception of the delivery report supplied by the provider in format rfc-2822.

All the parameters are sent as text strings.

The parameter status may be set to the following values

  • deliveredMessage delivered
  • expiredMessage expired (telephone turned off/not reachable)
  • deletedOperator network error
  • undeliverableMessage not sent (See error_code variable below)
  • unknownGeneric error
  • rejectdMessage rejected by the operator

The parameter error_code may be set to the following values

  • 101Generic operator fault
  • 201Network operator fault
  • 202Message rejected by the operator
  • 203Recipient cannot be reached (in roaming)
  • 301Invalid recipient (non-existent/in portability/not enabled)
  • 302Wrong number
  • 303SMS service not enabled
  • 304Text recognized as spam
  • 401Message expired (telephone turned off/not reachable)
  • 501Phone does not support the SMS
  • 502Phone memory full
  • 901Incorrect mapping of the fault
  • 902Service temporarily not available
  • 903No operator available
  • 904Message with no text
  • 905Invalid recipient
  • 906Duplicate recipients
  • 907Message written incorrectly
  • 909Incorrect User_reference
  • 910Excessively long text
 

View destination of notifications

Shows the current destination of the notifications.

Syntax
GET /customers/username-customer/forwardnotification
URL arguments
username_customer*
string (40 characters)the user’s username

EXAMPLE OF A REQUEST

curl -D - -u mariorossi:password --digest \
http://server/customers/mariorossi/forwardnotification

Return values
method
the notification method
version
the version of the notification system, normally set to 2
url
the URL to which the changes are to be sent

EXAMPLE OF A REPLY

Status Code: 200

{
  "method":"get",
  "url":"http://un.server/e/una/url",
  "version":2
}

 

Update notifications

Modifies the destination of the notifications.

Syntax
PUT /customers/username-customer/forwardnotification
BODY [Parameters ]
URL arguments
username_customer*
string (40 characters)the user’s username
BODY parameters
method
stringthe notification method
Required parameters
  • no
  • get
  • post
  • rest
  • soap
url
the URL to which the changes are to be sent

EXAMPLE OF A REQUEST

curl -D - -u mariorossi:password --digest \
-X PUT
http://server/customers/mariorossi/forwardnotification \
-d method=get \
-d url=http%3A%2F%2Fun.server%2Fe%2Funa%2Furl

Return values
method
the notification method
version
the version of the notification system, normally set to 2
url
the URL to which the changes are to be sent

EXAMPLE OF A REPLY

Status Code: 200

{
"method":"get",
"version":2,
"url":"http://un.server/e/una/url"
}

 

Check send numbers

Only customers with checked numbers can send messages. Once checked, a number can be associated with a registered customer. The procedure is made up of two calls.

The first is a POST that generates a token and sends it with an SMS to the number indicated as a parameter. The customer will read the token in the message and will use it in the second call, which is a POST through which he sends the token and his phone number to the server. If the combination coincides with that generated previously, the number is checked and authorized to send messages.

In addition to these two calls, the API shows another two, which serve to list the numbers and delete a number that has already been checked.

Note. As the check token is a separate object from the number check, it has been considered as a separate resource and, in fact, in Request for check you will note thatit has a URL different from the others.In any case, its API consists of the creation call only and the token is only used to check the send numbers. In order to simplify the orientation in the documentation it was therefore decided to include the call in this section and not to create a separate one.

 

Request for check

Generates a token and sends it in an SMS to the number indicated as a parameter.

Syntax
POST /customers/username-customer/numberverificationtoken
BODY [Parameters ]

Disapproved alternative form:
POST /customers/username-customer/verify/request
BODY [Parameters ]
URL arguments
username_customer*
string (40 characters)customer’s username to be checked
BODY parameters
number*
int (20 digits)the number to be checked, in international format with the prefix without + or 00

EXAMPLE OF A REQUEST

curl -D - -u mariorossi:password \
-X POST \
http://server/customers/mariorossi/numberverificationtoken \
-d number=3934567890

Return values
dispatch_id
the code identifying the SMS sent.

EXAMPLE OF A REPLY

Status Code: 200

{"dispatch_id":"999308731"}

 

Confirm check

Used to send the server the token and phone number of the customer that received the check message sent following the previous call.

Syntax
POST /customers/username-customer/verifiednumbers/confirm
BODY [Parameters ]

Disapproved alternative form:
POST /customers/username-customer/verify/check
BODY [Parameters ]
URL arguments
username_customer*
string (40 characters)customer’s username to be checked
BODY parameters
number*
int (20 digits)the number to be checked
token*
stringthe token sent to the customer and received in the check SMS

EXAMPLE OF A REQUEST

curl -D - -u mariorossi:password \
-X POST \
http://server/customers/mariorossi/verifiednumbers/confirm \
-d number=3934567890 \
-d token=73001922

Return values
number
the number checked

EXAMPLE OF A REPLY

Status Code: 200

[{
  "number": "3934567890"
}]

 

List of checked numbers

Returns the numbers that have been checked.

Syntax
GET /customers/username-customer/verifiednumbers

Disapproved alternative form:
POST /customers/username-customer/numbers
BODY [Parameters ]
URL arguments
username_customer*
string (40 characters)username used to register on the service

EXAMPLE OF A REQUEST

curl -D - -u mariorossi:password --digest \
http://server/customers/mariorossi/verifiednumbers

Return values
An array of
id_number
id of the checked number
number
checked number
validated_at
validation date

EXAMPLE OF A REPLY

Status Code: 200

[{
  "id_number": "10",
  "number": "3934567890",
  "validated_at": "2013-04-30T15:12:26+0200",
}]

 

Deletion of checked numbers

Deletes one of the checked numbers.

Syntax
DELETE /customers/username-customer/verifiednumbers/number

Disapproved alternative form:
DELETE /customers/username-customer/numbers/number
URL arguments
number*
stringthe number to be deleted

EXAMPLE OF A REQUEST

curl -D - -u mariorossi:password --digest \
-X DELETE \
http://server/customers/mariorossi/verifiednumbers/3934567890

Return values
number
the number deleted

EXAMPLE OF A REPLY

Status Code: 200

{
  "number": "3934567890"
}

 

Tariff (for SMS reception)

Used to access the data of the Tariffs of your Wholesaler/Reseller.

 

List of tariffs

Retrieves the list of Tariffs.

The url is identical for all users of the same server as the data returned are the same.

Syntax
GET /morates

EXAMPLE OF A REQUEST

curl -D - -u mariorossi:password --digest \
http://server/morates

Return values
An array of:
created_at
date and time at which the tariff was created
id_mo_rate
numerical ID of the tariff
name
name of the tariff
note
notes about the tariff
resellable
specifies whether the tariff can be resold or not (boolean)

EXAMPLE OF A REPLY

Status Code: 200

[{
"id_mo_rate":10,
"name":"Ricezione estate 2013",
"note":"vendere da giugno",
"resellable":0,
"created_at":"2013-05-16T15:22:48+0200"
}]

Tariffs returned by GET /resellers/user/morates

 

View tariff

Show the detail of a Tariff.

The url is identical for all users of the same server as the data returned are the same.

Syntax
GET /morates/id-mo-rate
URL arguments
id_mo_rate*
intnumerical ID of the Tariff

EXAMPLE OF A REQUEST

curl -D - -u mariorossi:password --digest \
http://server/morates/10

Return values
created_at
date and time at which the tariff was created
id_mo_rate
numerical ID of the tariff
name
name of the tariff
note
notes about the tariff
resellable
specifies whether the tariff can be resold or not (boolean)

EXAMPLE OF A REPLY

Status Code: 200

{
"id_mo_rate":10,
"name":"Ricezione estate 2013",
"note":"vendere da giugno",
"resellable":0,
"created_at":"2013-05-16T15:22:48+0200"
}

 

Price (for SMS reception)

Used to view the prices associated with the Tariffs of your Wholesaler/Reseller.
 

List of prices

Retrieves the list of Prices associated with a Tariff.

Syntax
GET /morates/id-mo-rate/moprices
URL arguments
id_mo_rate*
integernumerical ID of the tariff whose prices are to be returned

EXAMPLE OF A REQUEST

curl -D - -u mariorossi:password --digest \
http://server/api/morates/10/moprices

Return values
id_mo_price
numerical ID of the price
id_mo_rate
numerical ID of the tariff
price
the cost of one month
type
dedicated if the price is for a dedicated number or shared if it is for a shared number

EXAMPLE OF A REPLY

Status Code: 200

[{
"id_mo_price":1,
"id_mo_rate":10,
"price":"30.00",
"type":"dedicated"
},
{
"id_mo_price":2,
"id_mo_rate":10,
"price":"20.00",
"type":"shared"
}]

 

Flat-rate top-up (for SMS reception)

Used to access the Top-ups attributed to your user.

 

List of top-ups

Retrieves a list of a customer’s Top-ups.

The return values are identical to those that the %s would see Wholesaler/Reseller of the user with aGET .

Syntax
GET /customers/username-customer/morechargesflat
URL arguments
username_customer*
string (40 characters)username used to register on the service

EXAMPLE OF A REQUEST

curl -D - -u mariorossi:password --digest --digest \
http://server/customers/mariorossi/morechargesflat

curl -D - -u user:password --digest \
http://api.smsmessenger.it/resellers/user/customers/mariorossi/morechargesflat

The two calls give the same result

Return values
An array of:
id_mo_recharge
ID number of the top-up
id_mo_rate
ID number of the tariff
money_purchased
credit purchased
money_available
credit available
status
status of the top-up
created_at
date and time at which the top-up was created

EXAMPLE OF A REPLY

Status Code: 200

[{
"created_at":"2013-05-17T11:50:01+0200",
"id_mo_recharge_flat":1,
"id_mo_rate":3,
"id_mo_sold_keyword":2,
"months_purchased":3,
"status":"active",
"username":"mariorossi",
},
{
"created_at":"2013-05-17T11:52:15+0200",
"id_mo_recharge_flat":1,
"id_mo_rate":3,
"id_mo_sold_keyword":3,
"months_purchased":2,
"status":"active",
"username":"mariorossi"
}]

 

Keywords sold (for SMS reception)

Used to view the information about the Keywords available for your user.

 

List of keywords

Retrieve the list of Keyword bought from your Wholesalers/Resellers. Equivalent to the GET effettuata dal Wholesalers/Resellers.

Syntax
GET /customers/username-customer/mosoldkeywords
URL arguments
username_customer*
string (40 caratteri)username del Reseller / Final Customer

EXAMPLE OF A REQUEST

curl -D - -u mariorossi:password --digest \
http://server/customers/mariorossi/mosoldkeywords

Return values
An array of:
alert_enabled
indicates the presence of an alert on the expiry of the keyword
created_at
date and time at which the keyword was created
expires_at
date and time at which the keyword expires
id_parent_keyword
numerical ID of the parent keyword, null if it is the first in the hierarchy
id_mo_sold_keyword
numerical ID of the keyword
number
number at which the messages are received
status
status of the keyword ('test', 'active', 'grace', 'expired', 'revoked', 'blocked')
subkeyword
the first word of the keyword or null for a keyword that represents a dedicated number
username
the customer’s username

EXAMPLE OF A REPLY

Status Code: 200

[{
"alert_enabled":0,
"created_at":"2013-05-20T14:37:34+0200",
"expires_at":"2013-08-20T23:59:59+0200",
"id_parent_keyword":1,
"id_mo_sold_keyword":2,
"number":"1234",
"status":"active",
"subkeyword":"SMS",
"username":"mariorossi"
}]

 

View keyword

Show the details of a Tariff.

Syntax
GET /customers/username-customer/mosoldkeywords/id-mo-sold-keyword
URL arguments
username_customer*
string (40 caratteri)username del Reseller / Final Customer
id_mo_sold_keyword*
intnumerical ID of the keyword

EXAMPLE OF A REQUEST

curl -D - -u mariorossi:password --digest \
http://server/customers/mariorossi/mosoldkeywords/2

Return values
alert_enabled
indicates the presence of an alert on the expiry of the keyword
created_at
date and time at which the keyword was created
expires_at
date and time at which the keyword expires
id_parent_keyword
numerical ID of the parent keyword, null if it is the first in the hierarchy
id_mo_sold_keyword
numerical ID of the keyword
number
number at which the messages are received
status
status of the keyword ('test', 'active', 'grace', 'expired', 'revoked', 'blocked')
subkeyword
the first word of the keyword or null for a keyword that represents a dedicated number
username
the customer’s username

EXAMPLE OF A REPLY

Status Code: 200

{
"alert_enabled":0,
"created_at":"2013-05-20T14:37:34+0200",
"expires_at":"2013-08-20T23:59:59+0200",
"id_parent_keyword":1,
"id_mo_sold_keyword":2,
"number":"1234",
"status":"active",
"subkeyword":"SMS",
"username":"mariorossi"
}

 

Create sold keywords

This API is used to create a Keyword for yourself starting from one already in your possession.

Three arguments are to be indicated.

The first is the parent-keyword-id of the parent keyword. It must be one of your own keywords that has a subkeyword set to NULL, or be a dedicated number.

The second is the subkeyword, which is the first word of the message and is used to identify the person to whom it is to be delivered.

The third is the expiry date. Only the year, month and day is indicated as the keyword always expires at the end of a day. The view and list calls will show the complete time, with hour, minutes and seconds set to 23:59:59.

Syntax
POST /customers/username-customer/mosoldkeywords
URL arguments
username_customer*
string (40 characters)your own username, to create a keyword for yourself
BODY parameters
id_parent_keyword*
intnumerical id of the parent keyword
subkeyword*
string (50 characters)first word of the message

EXAMPLE OF A REQUEST

curl -D - -u user:password --digest \
-X POST \
http://api.smsmessenger.it/customers/mariorossi/mosoldkeywords
-d "id_parent_keyword=4"
-d "subkeyword=HELLO"

It is assumed that there is a mosoldkeyword with id_mo_sold_keyword == 4 and subkeyword == NULL

Return values
created_at
date and time at which the keyword was created
id_parent_keyword
numerical ID of the parent keyword, null if it is the first in the hierarchy
id_mo_soldkeyword
numerical ID of the keyword
number
number at which the messages are received
subkeyword
the first word of the keyword or null for a keyword that represents a dedicated number
username
the customer’s username

EXAMPLE OF A REPLY

Status Code: 200

[{
"created_at":"2013-05-21T14:02:17+0200",
"expires_at":"2013-08-21T23:59:59+0200",
"id_parent_keyword":4,
"id_mo_soldkeyword":5,
"number":"1234",
"status":"active",
"subkeyword":"HELLO",
"username":"mariorossi"
}]

 

Phone numbers (for SMS reception)

The Phone numbers indicate the address to which the messages received are to be sent. More than one Phone number can be created for a given Keyword. If there is more than one Phone number the message is delivered to all of them.

The messages are delivered as follows (the code corresponding to the service in brackets):

  • email-email
  • http-get-get
  • http-post-post
  • rest-legacy-rest
  • soap-soap

In detail

email

E-mail address to which the message is to be sent with the following parameters

  • string-userdatetime: the time at which the SMS arrived
  • string-sender: the SMS sender’s number in international format without + or 00, for example: 393334455666
  • string-text: text of the SMS

http-get

The server will call the URL specified in the info attribute passing the following parameters in GET:
  • string-sender: the SMS sender’s number in international format without + or 00, for example: 393334455666
  • string-receiver: the number at which the SMS arrived in international format without + or 00, for example: 393334455666
  • string-text: text of the SMS
  • string-encoding: the character set used for the text (ISO-8859-1)
  • string-date: the date on which the SMS arrived
  • string-time: the time at which the SMS arrived
  • string-timestamp: the SMS arrival timestamp; for programmers’ convenience, we pass three different date / time formats
  • string-smstype: the type of SMS received

Example of HTTP body for receiving SMS with GET parameters:

type=GET&sender=393471234567&receiver=393477654321&
text=Ciao+Mario+come+stai&encoding=ISO-8859-1&
date=2013-06-07&time=10%3A32%3A32&timestamp=1305880352&
smsType=standard

http-post

The server will call the URL specified in the info attribute by passing the following parameters in POST:

  • string-sender: the SMS sender’s number in international format without + or 00, for example: 393334455666
  • string-receiver: the number at which the SMS arrived in international format without + or 00, for example: 393334455666
  • string-text: text of the SMS
  • string-encoding: the character set used for the text (ISO-8859-1)
  • string-date: the date on which the SMS arrived
  • string-time: the time at which the SMS arrived
  • string-timestamp: the SMS arrival timestamp; for programmers’ convenience, we pass three different date / time formats
  • string-smstype: the type of SMS received

Example HTTP body for a SMS received using method POST:

type=POST&sender=393471234567&receiver=393477654321&
text=Ciao+Mario+come+stai&encoding=ISO-8859-1&
date=2013-06-07&time=10%3A32%3A32&timestamp=1305880352&
smsType=standard

rest-legacy

This is the legacy REST mode of the APIs. It is maintained for compatibility but it is not REST in the White Label API sense. It is equivalent to HTTP GET with the difference that it adds "restGet" and the following parameters to the URL specified in the info attribute:
  • string-sender: the SMS sender’s number in international format without + or 00, for example: 393334455666
  • string-receiver: the number at which the SMS arrived in international format without + or 00, for example: 393334455666
  • string-text: text of the SMS
  • string-encoding: the character set used for the text (ISO-8859-1)
  • string-date: the date on which the SMS arrived
  • string-time: the time at which the SMS arrived
  • string-timestamp: the SMS arrival timestamp; for programmers’ convenience, we pass three different date / time formats
  • string-smstype: the type of SMS received

Example HTTP body for a SMS received using method REST:

method=smsin&sender=393471234567&receiver=393477654321&
text=Ciao+Mario+come+stai&encoding=ISO-8859-1&
date=2013-06-07&time=10%3A32%3A32&timestamp=1305880352&
smsType=standard

soap

The server will call the URL specified in the info attribute by invoking the SOAP method "smsin" with the following parameters (in the order in which they are indicated here):

  • string-sender: the SMS sender’s number in international format without + or 00, for example: 393334455666
  • string-receiver: the number at which the SMS arrived in international format without + or 00, for example: 393334455666
  • string-text: text of the SMS
  • string-date: the date on which the SMS arrived
  • string-time: the time at which the SMS arrived
  • string-timestamp: the SMS arrival timestamp; for programmers’ convenience, we pass three different date / time formats
  • string-smstype: the type of SMS received

Example HTTP body for a SMS received using method SOAP:


<?xml version="1.0" encoding="UTF-8"?>
<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope" xmlns:ns1="url richiamata"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:enc="http://www.w3.org/2003/05/soap-encoding">
  <env:Body>
    <ns1:smsin env:encodingStyle="http://www.w3.org/2003/05/soap-encoding">
      <sender xsi:type="xsd:string">393471234567</sender>
      <receiver xsi:type="xsd:int">393477654321</receiver>
      <text xsi:type="xsd:string">Ciao Mario come stai</text>
      <date xsi:type="xsd:string">2013-06-07</date>
      <time xsi:type="xsd:string">10:32:32</time>
      <timestamp xsi:type="xsd:string">1305880352</timestamp>
      <smsType xsi:type="xsd:string">standard</smsType>
    </ns1:smsin>
  </env:Body>
</env:Envelope>
 

List of phone numbers

Shows the Phone numbers associated with a Keyword.

Syntax
GET /customers/username-customer/mosoldkeywords/id-mo-sold-keyword/forwardinfo
URL arguments
username_customer*
string (40 characters)username of the Reseller / Final Customer
id_mo_sold_keyword*
intnumerical ID of the keyword

EXAMPLE OF A REQUEST

curl -D - -u mariorossi:password --digest \
http://server/customers/mariorossi/mosoldkeywords/2/forwardinfo

Return values
Array di
enabled
boolean indicating whether delivery has been activated
encoding
desired encoding for delivery ('ISO-8859-1', 'UTF-8')
id_forward_info
numerical ID of the Phone number
id_mo_sold_keyword
numerical ID of the Keyword
info
address to which the message is to be sent (email, url)
type
indicates the type of delivery ('email', 'get', 'post', 'rest', 'soap', 'sms_dynamic_id', 'sms_fixed_id')

EXAMPLE OF A REPLY

Status Code: 200

[{
"enabled":1,
"encoding":"UTF-8",
"id_forward_info":1,
"id_mo_sold_keyword":2,
"info":"mariorossi@example.com",
"type":"email"
}]

 

View phone number

Shows the details of a Phone number.

Syntax
GET /customers/username-customer/mosoldkeywords/id-mo-sold-keyword/forwardinfo/id-forward-info
URL arguments
username_customer*
string (40 caratteri)username del Reseller / Final Customer
id_mo_sold_keyword*
intnumerical ID of the keyword
id_forward_info*
intnumerical ID of the phone number

EXAMPLE OF A REQUEST

curl -D - -u mariorossi:password --digest \
http://server/customers/mariorossi/mosoldkeywords/2/forwardinfo/1

Return values
enabled
boolean indicating whether delivery has been activated
encoding
desired encoding for delivery ('ISO-8859-1', 'UTF-8')
id_forward_info
numerical ID of the Phone number
id_mo_sold_keyword
numerical ID of the Keyword
info
address to which the message is to be sent (email, url)
type
indicates the type of delivery ('email', 'get', 'post', 'rest', 'soap', 'sms_dynamic_id', 'sms_fixed_id')

EXAMPLE OF A REPLY

Status Code: 200

{
"enabled":1,
"encoding":"UTF-8",
"id_forward_info":1,
"id_mo_sold_keyword":2,
"info":"mariorossi@example.com",
"type":"email"
}

 

Create phone number

Creates a Phone number for a Keyword.

Syntax
POST /customers/username-customer/mosoldkeywords/id-mo-sold-keyword/forwardinfo
BODY [Parameters ]
URL arguments
username_customer*
string (40 characters)username del Reseller / Final Customer
id_mo_sold_keyword*
intnumerical ID of the keyword
BODY parameters
enabled
booleanboolean indicating whether the delivery has been activated (set by default to true)
encoding
stringthe desired encoding for delivery
Required parameters
  • ISO-8859-1
  • UTF-8
info
string (255 characters)address to which the message is to be sent (email, url); if not indicated the Phone number will not be activated
type
stringindicates the type of delivery, it is email by default
Required parameters
  • email
  • get
  • post
  • rest
  • soap
  • sms_dynamic_id
  • sms_fixed_id

EXAMPLE OF A REQUEST

curl -D - -u mariorossi:password --digest \
-X POST
http://server/customers/mariorossi/mosoldkeywords/2/forwardinfo
-d enabled=1 \
-d encoding=UTF-8 \
-d info=mariorossi%40example.com \
-d type=email

Return values
enabled
boolean indicating whether delivery has been activated
encoding
desired encoding for delivery ('ISO-8859-1','UTF-8')
id_forward_info
numerical ID of the Phone number
info
address to which the message is to be sent (email, url)
type
indicates the type of delivery ('email', 'get', 'post', 'rest', 'soap', 'sms_dynamic_id', 'sms_fixed_id')

EXAMPLE OF A REPLY

Status Code: 200

{
"enabled":1,
"encoding":"UTF-8",
"id_forward_info":1,
"id_mo_sold_keyword":2,
"info":"mariorossi@example.com",
"type":"email"
}

 

Modify phone number

Modify Phone number for a Keyword.

Syntax
PUT /customers/username-customer/mosoldkeywords/id-mo-sold-keyword/forwardinfo/id-forward-info
BODY [Parameters ]
URL arguments
username_customer*
string (40 characters)username of the Reseller / Final Customer
id_mo_sold_keyword*
intnumerical ID of the keyword
id_forward_info*
intnumerical ID of the phone number
BODY parameters
enabled
booleanboolean indicating whether the delivery has been activated (set by default to true)
encoding
stringthe desired encoding for delivery
Required parameters
  • ISO-8859-1
  • UTF-8
info
string (255 characters)address to which the message is to be sent (email, url). If it is not indicated the phone number will not be activated. The type value must also be passed.
type
obligatory when info is present, stringindicates the type of delivery
Required parameters
  • email
  • get
  • post
  • rest
  • soap
  • sms_dynamic_id
  • sms_fixed_id

EXAMPLE OF A REQUEST

curl -D - -u mariorossi:password --digest \
-X PUT
http://server/customers/mariorossi/mosoldkeywords/2/forwardinfo/1
-d encoding=ISO-8859-1 \
-d info=sms-alerts%40example.com \
-d type=email

Return values
enabled
boolean indicating whether delivery has been activated
encoding
desired encoding for delivery ('ISO-8859-1','UTF-8')
id_forward_info
numerical ID of the Phone number
id_mo_sold_keyword
numerical ID of the Keyword
info
address to which the message is to be sent (email, url)
type
indicates the type of delivery ('email', 'get', 'post', 'rest', 'soap', 'sms_dynamic_id', 'sms_fixed_id')

EXAMPLE OF A REPLY

Status Code: 200

{
"enabled":1,
"encoding":"ISO-8859-1",
"id_forward_info":1,
"id_mo_sold_keyword":2,
"info":"sms-alerts@example.com",
"type":"email"
}

 

geographical areas and countries

The country codes are defined by the standard ISO 3166. The server uses the two-character version.

Codes for id_geographical_area

The server divides the nations in the following areas, of which gives the numerical code to be used in calls to the API and the list of nations.

Africa

The codes of the countries in the geographical area Africa are

  • AC Ascension Island
  • AO Angola
  • BF Burkina Faso
  • BI Burundi
  • BJ Benin
  • BW Botswana
  • CD Congo [DRC]
  • CF Central African Republic
  • CG Congo [Republic]
  • CI Ivory Coast
  • CM Cameroon
  • CV Cape Verde
  • DJ Djibouti
  • DZ Algeria
  • EG Egypt
  • ER Eritrea
  • ET Ethiopia
  • GA Gabon
  • GH Ghana
  • GM Gambia
  • GN Guinea
  • GQ Equatorial Guinea
  • GW Guinea-Bissau
  • IO British Indian Ocean Territory
  • KE Kenya
  • KM Comoros
  • LR Liberia
  • LS Lesotho
  • LY Libya
  • MA Morocco
  • MG Madagascar
  • ML Mali
  • MR Mauritania
  • MU Mauritius
  • MW Malawi
  • MZ Mozambique
  • NA Namibia
  • NE Niger
  • NG Nigeria
  • RW Rwanda
  • SC Seychelles
  • SD Sudan
  • SL Sierra Leone
  • SN Senegal
  • SO Somalia
  • SS South Sudan
  • ST São Tomé and Príncipe
  • SZ Swaziland
  • TD Chad
  • TF French Southern Territories
  • TG Togo
  • TN Tunisia
  • TZ Tanzania
  • UG Uganda
  • ZA South Africa
  • ZM Zambia
  • ZW Zimbabwe

Asia Pacific

The codes of the countries in the geographical area Asia Pacific are

  • AF Afghanistan
  • AS American Samoa
  • AU Australia
  • BD Bangladesh
  • BN Brunei
  • BT Bhutan
  • CK Cook Islands
  • CN China
  • FJ Fiji
  • FM Micronesia
  • GU Guam
  • HK Hong Kong
  • ID Indonesia
  • IN India
  • IR Iran
  • JP Japan
  • KG Kyrgyzstan
  • KH Cambodia
  • KI Kiribati
  • KP North Korea
  • KR South Korea
  • LA Laos
  • LK Sri Lanka
  • MH Marshall Islands
  • MM Myanmar [Burma]
  • MN Mongolia
  • MO Macau
  • MP Northern Mariana Islands
  • MV Maldives
  • MY Malaysia
  • NC New Caledonia
  • NF Norfolk Island
  • NP Nepal
  • NR Nauru
  • NU Niue
  • NZ New Zealand
  • PF French Polynesia
  • PG Papua New Guinea
  • PH Philippines
  • PK Pakistan
  • PW Palau
  • SB Solomon Islands
  • SG Singapore
  • TH Thailand
  • TJ Tajikistan
  • TK Tokelau
  • TL East Timor
  • TM Turkmenistan
  • TO Tonga
  • TV Tuvalu
  • TW Taiwan
  • UZ Uzbekistan
  • VN Vietnam
  • VU Vanuatu
  • WF Wallis and Futuna
  • WS Samoa

Europe

The codes of the countries in the geographical area Europe are

  • AD Andorra
  • AL Albania
  • AM Armenia
  • AT Austria
  • AZ Azerbaijan
  • BA Bosnia and Herzegovina
  • BE Belgium
  • BG Bulgaria
  • BY Belarus
  • CH Switzerland
  • CY Cyprus
  • CZ Czech Republic
  • DE Germany
  • DK Denmark
  • EE Estonia
  • ES Spain
  • FI Finland
  • FO Faroe Islands
  • FR France
  • GB U.K.
  • GE Georgia
  • GI Gibraltar
  • GL Greenland
  • GR Greece
  • HR Croatia
  • HU Hungary
  • IE Ireland
  • IS Iceland
  • IT Italy
  • LI Liechtenstein
  • LT Lithuania
  • LU Luxembourg
  • LV Latvia
  • MC Monaco
  • MD Moldova
  • ME Montenegro
  • MK Macedonia [FYROM]
  • MT Malta
  • NL Netherlands
  • NO Norway
  • PL Poland
  • PT Portugal
  • RO Romania
  • RS Serbia
  • RU Russia
  • SE Sweden
  • SI Slovenia
  • SK Slovakia
  • SM San Marino
  • TR Turkey
  • UA Ukraine

Latin America

The codes of the countries in the geographical area Latin America are

  • AG Antigua and Barbuda
  • AI Anguilla
  • AN Netherlands Antilles
  • AR Argentina
  • AW Aruba
  • BB Barbados
  • BM Bermuda
  • BO Bolivia
  • BR Brazil
  • BS Bahamas
  • BZ Belize
  • CL Chile
  • CO Colombia
  • CR Costa Rica
  • CU Cuba
  • DM Dominica
  • EC Ecuador
  • FK Falkland Islands [Islas Malvinas]
  • GD Grenada
  • GF French Guiana
  • GP Guadeloupe
  • GT Guatemala
  • GY Guyana
  • HN Honduras
  • HT Haiti
  • JM Jamaica
  • KN Saint Kitts and Nevis
  • KY Cayman Islands
  • LC Saint Lucia
  • MQ Martinique
  • MS Montserrat
  • MX Mexico
  • NI Nicaragua
  • PA Panama
  • PE Peru
  • PY Paraguay
  • SR Suriname
  • SV El Salvador
  • TC Turks and Caicos Islands
  • TT Trinidad and Tobago
  • UY Uruguay
  • VC Saint Vincent and the Grenadines
  • VE Venezuela
  • VG British Virgin Islands
  • VI U.S. Virgin Islands

Middle East

The codes of the countries in the geographical area Middle East are

  • AE United Arab Emirates
  • BH Bahrain
  • IL Israel
  • IQ Iraq
  • JO Jordan
  • KW Kuwait
  • LB Lebanon
  • OM Oman
  • QA Qatar
  • SA Saudi Arabia
  • SY Syria
  • YE Yemen

Northern America

The codes of the countries in the geographical area Northern America are

  • PM Saint Pierre and Miquelon
  • SH Saint Helena
  • US U.S.

Canada is included in the United States (US) since it has their own international code.

 

Time zones codes

  • ciabj Africa/Abidjan
  • ghacc Africa/Accra
  • etadd Africa/Addis_Ababa
  • dzalg Africa/Algiers
  • erasm Africa/Asmera
  • mlbko Africa/Bamako
  • cfbgf Africa/Bangui
  • gmbjl Africa/Banjul
  • gwoxb Africa/Bissau
  • mwblz Africa/Blantyre
  • cgbzv Africa/Brazzaville
  • bibjm Africa/Bujumbura
  • egcai Africa/Cairo
  • macas Africa/Casablanca
  • esceu Africa/Ceuta
  • gncky Africa/Conakry
  • sndkr Africa/Dakar
  • tzdar Africa/Dar_es_Salaam
  • djjib Africa/Djibouti
  • cmdla Africa/Douala
  • eheai Africa/El_Aaiun
  • slfna Africa/Freetown
  • bwgbe Africa/Gaborone
  • zwhre Africa/Harare
  • zajnb Africa/Johannesburg
  • ugkla Africa/Kampala
  • sdkrt Africa/Khartoum
  • rwkgl Africa/Kigali
  • cdfih Africa/Kinshasa
  • nglos Africa/Lagos
  • galbv Africa/Libreville
  • tglfw Africa/Lome
  • aolad Africa/Luanda
  • cdfbm Africa/Lubumbashi
  • zmlun Africa/Lusaka
  • gqssg Africa/Malabo
  • mzmpm Africa/Maputo
  • lsmsu Africa/Maseru
  • szqmn Africa/Mbabane
  • somgq Africa/Mogadishu
  • lrmlw Africa/Monrovia
  • kenbo Africa/Nairobi
  • tdndj Africa/Ndjamena
  • nenim Africa/Niamey
  • mrnkc Africa/Nouakchott
  • bfoua Africa/Ouagadougou
  • bjptn Africa/Porto-Novo
  • sttms Africa/Sao_Tome
  • lytip Africa/Tripoli
  • tntun Africa/Tunis
  • nawdh Africa/Windhoek
  • usadk America/Adak
  • usanc America/Anchorage
  • aiaxa America/Anguilla
  • aganu America/Antigua
  • braux America/Araguaina
  • arirj America/Argentina/La_Rioja
  • arrgl America/Argentina/Rio_Gallegos
  • arsla America/Argentina/Salta
  • aruaq America/Argentina/San_Juan
  • arluq America/Argentina/San_Luis
  • artuc America/Argentina/Tucuman
  • arush America/Argentina/Ushuaia
  • awaua America/Aruba
  • pyasu America/Asuncion
  • brssa America/Bahia
  • bbbgi America/Barbados
  • brbel America/Belem
  • bzbze America/Belize
  • caybx America/Blanc-Sablon
  • brbvb America/Boa_Vista
  • cobog America/Bogota
  • usboi America/Boise
  • arbue America/Buenos_Aires
  • caycb America/Cambridge_Bay
  • brcgr America/Campo_Grande
  • mxcun America/Cancun
  • veccs America/Caracas
  • arctc America/Catamarca
  • gfcay America/Cayenne
  • kygec America/Cayman
  • uschi America/Chicago
  • mxchi America/Chihuahua
  • cayzs America/Coral_Harbour
  • arcor America/Cordoba
  • crsjo America/Costa_Rica
  • brcgb America/Cuiaba
  • ancur America/Curacao
  • gldkshvn America/Danmarkshavn
  • cayda America/Dawson
  • caydq America/Dawson_Creek
  • usden America/Denver
  • usdet America/Detroit
  • dmdom America/Dominica
  • caedm America/Edmonton
  • brern America/Eirunepe
  • svsal America/El_Salvador
  • brfor America/Fortaleza
  • caglb America/Glace_Bay
  • glgoh America/Godthab
  • cagoo America/Goose_Bay
  • tcgdt America/Grand_Turk
  • gdgnd America/Grenada
  • gpbbr America/Guadeloupe
  • gtgua America/Guatemala
  • ecgye America/Guayaquil
  • gygeo America/Guyana
  • cahal America/Halifax
  • cuhav America/Havana
  • mxhmo America/Hermosillo
  • usknx America/Indiana/Knox
  • usaeg America/Indiana/Marengo
  • uswsq America/Indiana/Petersburg
  • ustel America/Indiana/Tell_City
  • usinvev America/Indiana/Vevay
  • usoea America/Indiana/Vincennes
  • uswlz America/Indiana/Winamac
  • usind America/Indianapolis
  • cayev America/Inuvik
  • caiql America/Iqaluit
  • jmkin America/Jamaica
  • arjuj America/Jujuy
  • usjnu America/Juneau
  • usmoc America/Kentucky/Monticello
  • bolpb America/La_Paz
  • pelim America/Lima
  • uslax America/Los_Angeles
  • uslui America/Louisville
  • brmcz America/Maceio
  • nimga America/Managua
  • brmao America/Manaus
  • gpmsb America/Marigot
  • mqfdf America/Martinique
  • mxmzt America/Mazatlan
  • armdz America/Mendoza
  • usmnm America/Menominee
  • mxmid America/Merida
  • mxmex America/Mexico_City
  • pmmqc America/Miquelon
  • camon America/Moncton
  • mxmty America/Monterrey
  • uymvd America/Montevideo
  • camtr America/Montreal
  • msmni America/Montserrat
  • bsnas America/Nassau
  • usnyc America/New_York
  • cathu America/Thunder_Bay
  • usome America/Nome
  • brfen America/Noronha
  • usndcnt America/North_Dakota/Center
  • usndnsl America/North_Dakota/New_Salem
  • papty America/Panama
  • capnt America/Pangnirtung
  • srpbm America/Paramaribo
  • usphx America/Phoenix
  • htpap America/Port-au-Prince
  • ttpos America/Port_of_Spain
  • brpvh America/Porto_Velho
  • prsju America/Puerto_Rico
  • caffs America/Rainy_River
  • cayek America/Rankin_Inlet
  • brrec America/Recife
  • careg America/Regina
  • careb America/Resolute
  • brrbr America/Rio_Branco
  • brstm America/Santarem
  • clscl America/Santiago
  • dosdq America/Santo_Domingo
  • brsao America/Sao_Paulo
  • globy America/Scoresbysund
  • usnavajo America/Shiprock
  • gpsbh America/St_Barthelemy
  • casjf America/St_Johns
  • knbas America/St_Kitts
  • lccas America/St_Lucia
  • vistt America/St_Thomas
  • vcsvd America/St_Vincent
  • cayyn America/Swift_Current
  • hntgu America/Tegucigalpa
  • glthu America/Thule
  • mxtij America/Tijuana
  • cator America/Toronto
  • vgtov America/Tortola
  • cavan America/Vancouver
  • cayxy America/Whitehorse
  • cawnp America/Winnipeg
  • usyak America/Yakutat
  • cayzf America/Yellowknife
  • aqcas Antarctica/Casey
  • aqdav Antarctica/Davis
  • aqddu Antarctica/DumontDUrville
  • aqmaw Antarctica/Mawson
  • aqmcm Antarctica/McMurdo
  • aqplm Antarctica/Palmer
  • aqrot Antarctica/Rothera
  • aqams Antarctica/South_Pole
  • aqsyw Antarctica/Syowa
  • aqvos Antarctica/Vostok
  • sjlyr Arctic/Longyearbyen
  • yeade Asia/Aden
  • kzala Asia/Almaty
  • joamm Asia/Amman
  • rudyr Asia/Anadyr
  • kzaau Asia/Aqtau
  • kzakx Asia/Aqtobe
  • tmasb Asia/Ashgabat
  • iqbgw Asia/Baghdad
  • bhbah Asia/Bahrain
  • azbak Asia/Baku
  • thbkk Asia/Bangkok
  • lbbey Asia/Beirut
  • kgfru Asia/Bishkek
  • bnbwn Asia/Brunei
  • inccu Asia/Calcutta
  • mncoq Asia/Choibalsan
  • cnckg Asia/Chongqing
  • lkcmb Asia/Colombo
  • sydam Asia/Damascus
  • bddac Asia/Dhaka
  • tldil Asia/Dili
  • aedxb Asia/Dubai
  • tjdyu Asia/Dushanbe
  • gaza Asia/Gaza
  • cnhrb Asia/Harbin
  • hkhkg Asia/Hong_Kong
  • mnhvd Asia/Hovd
  • ruikt Asia/Irkutsk
  • idjkt Asia/Jakarta
  • iddjj Asia/Jayapura
  • jeruslm Asia/Jerusalem
  • afkbl Asia/Kabul
  • rupkc Asia/Kamchatka
  • pkkhi Asia/Karachi
  • cnkhg Asia/Kashgar
  • npktm Asia/Katmandu
  • rukra Asia/Krasnoyarsk
  • mykul Asia/Kuala_Lumpur
  • mykch Asia/Kuching
  • kwkwi Asia/Kuwait
  • momfm Asia/Macau
  • rugdx Asia/Magadan
  • idmak Asia/Makassar
  • phmnl Asia/Manila
  • ommct Asia/Muscat
  • cynic Asia/Nicosia
  • ruovb Asia/Novosibirsk
  • ruoms Asia/Omsk
  • kzura Asia/Oral
  • khpnh Asia/Phnom_Penh
  • idpnk Asia/Pontianak
  • kpfnj Asia/Pyongyang
  • qadoh Asia/Qatar
  • kzkzo Asia/Qyzylorda
  • mmrgn Asia/Rangoon
  • saruh Asia/Riyadh
  • vnsgn Asia/Saigon
  • ruuus Asia/Sakhalin
  • uzskd Asia/Samarkand
  • krsel Asia/Seoul
  • cnsha Asia/Shanghai
  • sgsin Asia/Singapore
  • twtpe Asia/Taipei
  • uztas Asia/Tashkent
  • getbs Asia/Tbilisi
  • irthr Asia/Tehran
  • btthi Asia/Thimphu
  • jptyo Asia/Tokyo
  • mnuln Asia/Ulaanbaatar
  • cnurc Asia/Urumqi
  • lavte Asia/Vientiane
  • ruvvo Asia/Vladivostok
  • ruyks Asia/Yakutsk
  • ruyek Asia/Yekaterinburg
  • amevn Asia/Yerevan
  • ptpdl Atlantic/Azores
  • bmbda Atlantic/Bermuda
  • eslpa Atlantic/Canary
  • cvrai Atlantic/Cape_Verde
  • fotho Atlantic/Faeroe
  • ptfnc Atlantic/Madeira
  • isrey Atlantic/Reykjavik
  • gsgrv Atlantic/South_Georgia
  • shshn Atlantic/St_Helena
  • fkpsy Atlantic/Stanley
  • auadl Australia/Adelaide
  • aubne Australia/Brisbane
  • aubhq Australia/Broken_Hill
  • aukns Australia/Currie
  • audrw Australia/Darwin
  • aueuc Australia/Eucla
  • auhba Australia/Hobart
  • auldc Australia/Lindeman
  • auldh Australia/Lord_Howe
  • aumel Australia/Melbourne
  • auper Australia/Perth
  • ausyd Australia/Sydney
  • utc Etc/GMT
  • utcw01 Etc/GMT+1
  • utcw10 Etc/GMT+10
  • utcw11 Etc/GMT+11
  • utcw12 Etc/GMT+12
  • utcw02 Etc/GMT+2
  • utcw03 Etc/GMT+3
  • utcw04 Etc/GMT+4
  • utcw05 Etc/GMT+5
  • utcw06 Etc/GMT+6
  • utcw07 Etc/GMT+7
  • utcw08 Etc/GMT+8
  • utcw09 Etc/GMT+9
  • utce01 Etc/GMT-1
  • utce10 Etc/GMT-10
  • utce11 Etc/GMT-11
  • utce12 Etc/GMT-12
  • utce13 Etc/GMT-13
  • utce14 Etc/GMT-14
  • utce02 Etc/GMT-2
  • utce03 Etc/GMT-3
  • utce04 Etc/GMT-4
  • utce05 Etc/GMT-5
  • utce06 Etc/GMT-6
  • utce07 Etc/GMT-7
  • utce08 Etc/GMT-8
  • utce09 Etc/GMT-9
  • unk Etc/Unknown
  • nlams Europe/Amsterdam
  • adalv Europe/Andorra
  • grath Europe/Athens
  • rsbeg Europe/Belgrade
  • deber Europe/Berlin
  • skbts Europe/Bratislava
  • bebru Europe/Brussels
  • robuh Europe/Bucharest
  • hubud Europe/Budapest
  • mdkiv Europe/Chisinau
  • dkcph Europe/Copenhagen
  • iedub Europe/Dublin
  • gigib Europe/Gibraltar
  • gggci Europe/Guernsey
  • fihel Europe/Helsinki
  • imdgs Europe/Isle_of_Man
  • trist Europe/Istanbul
  • jesth Europe/Jersey
  • rukgd Europe/Kaliningrad
  • uaiev Europe/Kiev
  • ptlis Europe/Lisbon
  • silju Europe/Ljubljana
  • gblon Europe/London
  • lulux Europe/Luxembourg
  • esmad Europe/Madrid
  • mtmla Europe/Malta
  • fimhq Europe/Mariehamn
  • bymsq Europe/Minsk
  • mcmon Europe/Monaco
  • rumow Europe/Moscow
  • noosl Europe/Oslo
  • frpar Europe/Paris
  • metgd Europe/Podgorica
  • czprg Europe/Prague
  • lvrix Europe/Riga
  • itrom Europe/Rome
  • rukuf Europe/Samara
  • smsai Europe/San_Marino
  • basjj Europe/Sarajevo
  • uasip Europe/Simferopol
  • mkskp Europe/Skopje
  • bgsof Europe/Sofia
  • sesto Europe/Stockholm
  • eetll Europe/Tallinn
  • altia Europe/Tirane
  • uauzh Europe/Uzhgorod
  • livdz Europe/Vaduz
  • vavat Europe/Vatican
  • atvie Europe/Vienna
  • ltvno Europe/Vilnius
  • ruvog Europe/Volgograd
  • plwaw Europe/Warsaw
  • hrzag Europe/Zagreb
  • uaozh Europe/Zaporozhye
  • chzrh Europe/Zurich
  • mgtnr Indian/Antananarivo
  • iodga Indian/Chagos
  • cxxch Indian/Christmas
  • cccck Indian/Cocos
  • kmyva Indian/Comoro
  • tfpfr Indian/Kerguelen
  • scmaw Indian/Mahe
  • mvmle Indian/Maldives
  • muplu Indian/Mauritius
  • ytmam Indian/Mayotte
  • rereu Indian/Reunion
  • wsapw Pacific/Apia
  • nzakl Pacific/Auckland
  • nzcht Pacific/Chatham
  • clipc Pacific/Easter
  • vuvli Pacific/Efate
  • kipho Pacific/Enderbury
  • tkfko Pacific/Fakaofo
  • fjsuv Pacific/Fiji
  • tvfun Pacific/Funafuti
  • ecgps Pacific/Galapagos
  • pfgmr Pacific/Gambier
  • sbhir Pacific/Guadalcanal
  • gugum Pacific/Guam
  • ushnl Pacific/Honolulu
  • umjon Pacific/Johnston
  • kicxi Pacific/Kiritimati
  • fmksa Pacific/Kosrae
  • mhkwa Pacific/Kwajalein
  • mhmaj Pacific/Majuro
  • pfnhv Pacific/Marquesas
  • ummdy Pacific/Midway
  • nrinu Pacific/Nauru
  • nuiue Pacific/Niue
  • nfnlk Pacific/Norfolk
  • ncnou Pacific/Noumea
  • asppg Pacific/Pago_Pago
  • pwror Pacific/Palau
  • pnpcn Pacific/Pitcairn
  • fmpni Pacific/Ponape
  • pgpom Pacific/Port_Moresby
  • ckrar Pacific/Rarotonga
  • mpspn Pacific/Saipan
  • pfppt Pacific/Tahiti
  • kitrw Pacific/Tarawa
  • totbu Pacific/Tongatapu
  • fmtkk Pacific/Truk
  • umawk Pacific/Wake
  • wfmau Pacific/Walli
 

AGCOM Specifications

ALLEGATO A

SET DI CARATTERI AMMESSI PER LA COSTITUZIONE DEGLI ALIAS

Con riferimento al paragrafo 6.2.1 “GSM 7 bit Default Alphabet” dello standard tecnico “ Digital cellular telecommunications system (Phase 2+); Universal Mobile Telecommunications System (UMTS); LTE; Alphabets and language-specific information ”, 3GPP TS 23.038 version 11.0.0 (2012-10) Release 11, per la costituzione degli alias è ammissibile solo quanto segue.

  1. le lettere dell’alfabeto internazionale minuscole e maiuscole:
    • ABCDEFGHIJKLMNOPQRSTUVXYWZ (codici HEX rispettivamente da 41 a 5A)
    • abcdefghijklmnopqrstuvxywz (codici HEX rispettivamente da 61 a 6A)
  2. Le lettere minuscole accentate presenti nella tastiera italiana:
    • èéùìò (codici HEX rispettivamente da 04 a 08)
    • à (codice HEX 7F)
  3. Le cifre da 0 a 9
    • 0123456789 (codici HEX rispettivamente da 30 a 39)
  4. Comuni segni di punteggiatura:
    • SP (spazio: codice HEX 20 )
    • ! (punto esclamativo: codice HEX 21 )
    • ‘ (apostrofo: codice HEX 27 )
    • , (virgola: codice HEX 2C)
    • . (punto : codice HEX 2E)
    • : (due punti: codice HEX 3A)
    • ; (punto e virgola: codice HEX 3B)
    • ? (punto interrogativo: codice HEX 3F)
    • i precedenti caratteri non possono essere preceduti dal carattere spazio.
    • Non è consentito l’uso consecutivo di spazi
    • “ (virgolette, codice HEX 22 )
    • In un Alias, possono essere presenti esclusivamente due virgolette: una come apertura ed una come chiusura. La prima non può precedere un spazio e la seconda non può seguire uno spazio.
  5. Comuni simboli di valuta
    • € (euro: codice di due caratteri HEX 1B 65)
    • £ (lira: codice HEX 01 )
    • $ (dollaro: codice HEX 02 )
  6. Comuni simboli matematici
    • % (percentuale: codice HEX 25 )
    • ( (parentesi tonda aperta: codice HEX 28)
    • ) (parentesi tonda chiusa: codice HEX 29)
    • + (più: codice HEX 2B)
    • – (meno o anche trattino: codice HEX 2D)
    • = (uguale: codice HEX 3D)
  7. Simboli utilizzati in internet:
    • @ (chiocciolina o “ at ” : codice HEX 00)
    • _ ( sottolineato o “underscore” : codice HEX 11)
    • # (cancelletto o “ hash ” : codice HEX 23)
    • & (and: codice HEX 26 )
    • * (asterisco o “star” : codice HEX 2A)

In definitiva, la lista dei caratteri ammessi e le relative codifiche in esadecimale ETSI da utilizzare nella trasmissione degli SMS/MMS nonché le relative codifiche in esadecimale UTF-8 da utilizzare nella comunicazione verso la banca dati dell’Autorità sono:

Carattere

Codifica ETSI

Codifica UTF-8

Carattere

Codifica ETSI

Codifica UTF-8

Carattere

Codifica ETSI

Codifica UTF-8

@

00

40

8

38

38

Z

5A

5A

£

01

C2 A3

9

39

39

a

61

61

$

02

24

:

3A

3A

b

62

62

è

04

C3 A8

;

3B

3B

c

63

63

é

05

C3 A9

=

3D

3D

d

64

64

ù

06

C3 B9

?

3F

3F

e

65

65

ì

07

C3 AC

A

41

41

f

66

66

ò

08

C3 B2

B

42

42

g

67

67

_

11

5F

C

43

43

h

68

68

SP

20

20

D

44

44

i

69

69

!

21

21

E

45

45

j

6A

6A

'

22

22

F

46

46

k

6B

6B

#

23

23

G

47

47

l

6C

6C

%

25

25

H

48

48

m

6D

6D

&

26

26

I

49

49

n

6E

6E

'

27

27

J

4A

4A

o

6F

6F

(

28

28

K

4B

4B

p

70

70

)

29

29

L

4C

4C

q

71

71

*

2A

2A

M

4D

4D

r

72

72

+

2B

2B

N

4E

4E

s

73

73

,

2C

2C

O

4F

4F

t

74

74

-

2D

2D

P

50

50

u

75

75

.

2E

2E

Q

51

51

v

76

76

0

30

30

R

52

52

w

77

77

1

31

31

S

53

53

x

78

78

2

32

32

T

54

54

y

79

79

3

33

33

U

55

55

z

7A

7A

4

34

34

V

56

56

à

7F

C3 A0

5

35

35

W

57

57

1B 65

E2 82 AC

6

36

36

X

58

58

7

37

37

Y

59

59

Di conseguenza, la tabella dei caratteri utilizzabili organizzata secondo la codifica ETSI è la seguente.

b7

0

0

0

0

1

1

1

1

b6

0

0

1

1

0

0

1

1

b5

0

1

0

1

0

1

0

1

b4

b3

b2

b1

HEX

0

1

2

3

4

5

6

7

0

0

0

0

0

@
40

 

SP
20

0
30

 

P
50

 

p
70

0

0

0

1

1

£
C2 A3

_
5F

!
21

1
31

A
41

Q
51

a
61

q
71

0

0

1

0

2

$
24

 

'
22

2
32

B
42

R
52

b
62

r
72

0

0

1

1

3

 

 

#
23

3
33

C
43

S
53

c
63

s
73

0

1

0

0

4

è
C3 A8

 

 

4
34

D
44

T
54

d
64

t
74

0

1

0

1

5

è
C3 A9

 

%
25

5
35

E
45

U
55

e
65

u
75

0

1

1

0

6

ù
C3 B9

 

&
26

6
36

F
46

V
56

f
66

v
76

0

1

1

1

7

ì
C3 AC

 

'
27

7
37

G
47

W
57

g
67

w
77

1

0

0

0

8

ò
C3 B2

 

(
28

8
38

H
48

X
58

h
68

x
78

1

0

0

1

9

 

 

)
29

9
39

I
49

Y
59

i
69

y
79

1

0

1

0

A

 

 

*
2A

:
3A

J
4A

Z
5A

j
6A

z
7A

1

0

1

1

B

 

1)

+
2B

;
3B

K
4B

 

k
6B

 

1

1

0

0

C

 

 

,
2C

 

L
4C

 

l
6C

 

1

1

0

1

D

 

 

-
2D

=
3D

M
4D

     

m
6D

     

1

1

1

0

E

     

     

.
2E

     

N
4E

     

n
6E

     

1

1

1

1

F

     

     

     

?
3F

O
4F

     

o
6F

à
C3 A0

SP corrisponde al carattere spazio

1) non è un carattere ma indica il codice (HEX 1B) da anteporre per indicare i caratteri presenti nella Extension table . In particolare alla codifica HEX 1B 65 corrisponde il carattere €, la cui codifica UTF-8 è E2 82 AC. Il carattere € è l’unico carattere utilizzabile della Extension table .

In ciascuna cella è riportata in prima riga il carattere relativo alla codifica secondo lo standard 3GPP TS 23.038 version 11.0.0 (2012-10)

In seconda riga è riportata la relativa codifica UTF-8 da utilizzare nelle comunicazioni verso il DB dell' AGCOM