BiteAPI User's Guide for SMS service providers

This document details the functionality of BITE API from the SMS application developers’ point of view.

BITE API is a web-service accessible via Internet using SOAP over HTTP. BiteAPI allows third parties to:

• perform transactional or subscription billing
• provide SMS, MMS or WAP based services (see WAP developers’ guide for more WAP details)

The guide is written for developers writing applications using BiteAPI web services interface. For a complete functional specification please consult the reference.

The principal elements involved in building an SMS premium service from your perspective are:

• Receiving SMS requests (step 1, 2)
  • To your own short number (via SMPP or HTTP protocol)
  • To a shared short number (via http protocol)
• Processing the SMS request in your SMS application (step 3)
• Performing billing actions via Bite API (step 4)
• Sending out SMS via SMPP or BITE API (step 6)

Each content provider (i.e. a legal entity) has his own user name and password which must be used to autenthicate to the API system. They are called “Providers”.

Each Provider can operate many premium services, for example „Weather reports“ and „Astrology“. A service is something which is understood by the user as a single premium service, and has a human understandable description.

A service is supplied for a given market. Therefore, running the same service in Lithuania and Latvia still requires to set up 2 separate services to reflect currency and accounting differences.

Each service is delivered to the user via paid Actions, such as „Java File download“ or „Payment for WAP site access“, or „Sending SMS to the user“. Each action has one or more prices that the end-user can be charged, and may have an associated cost for the provider too (in case of sending SMS to the user).

All configuration of the API including partner account setup, service setup, price setup and other administrative activities are performed by a person responsible of managing the partners services, their actions and prices. His email: partner_support@bite.lt

Each email received to the partner support is answered in 2 days. Please, do not rush it, and make sure you have really understood the documentation before using it.

BiteAPI interface defines several web service ports:

• Billing and Subscription ports
• Provider port
• Messaging port

Each port groups several functions similar by their nature and context of use. WSDL files for all ports are provided at the following address: http://soap.bite.lt/biteapi/axisinfo

BiteAPI allows partners to perform billing transactions to bill their users (accounts) through the BillingPort.

Billing Port Service URL: http://soap.bite.lt/biteapi/services/BillingPort
Billing Port WSDL URL: http://soap.bite.lt/biteapi/services/BillingPort?wsdl

Billing Port Functions:

Transaction opening, committing, and roll backing is supported along with plain untransactional billing, which allows to perform single step billing in cases where transactions are not feasible.

To bill or open a billing transaction several input parameters have to be supplied:

• an account ID to bill,
• a service ID
• an account action to be used
• price and currency.

It is recommended to use billAccount function. This function makes one-step billing.

To open a two-step transaction openTransaction function is used. It returns an ID of transaction being opened. If an error occurred during operation a soap fault is generated providing error information. Having an opened transaction the partner can now operate within current transaction context and use a commit function in case of successful partner operation or rollback the transaction in case of failure. Both commit and rollback functions use the same transaction ID returned when transaction was opened.

Account actions are used to determine the type of action that the user is billed for. Currently there are three actions:

Each account action is associated with a list of allowed prices (with specified currencies). It's disallowed to perform billing operation with prices outside these values. Prices and actions are managed by system manager.

Important:

Please, catch and handle all billing errors, as they may indicate an empty prepaid account.

Subscriptions Port Service URL: http://soap.bite.lt/biteapi/services/SubscriptionsPort
Subscriptions Port WSDL URL: http://soap.bite.lt/biteapi/services/SubscriptionsPort?wsdl

Subscriptions Port functions:

BiteAPI contains functions to manage subscriptions of partners' services. These can be used to subscribe and unsubscribe account as well as to get a list of subscribers for a specific service and check subscription status.

Important:

According to the contract, Provider cannot provide a premium subscription service using his own subscription management, implemented via Billing port. Only services which operate using BITE API Subscription Port are allowed.

In the Subscription functions, billing subscriber on a regular basis (specified with renewal parameter) is performed automatically.

Therefore Bite API provides a convenient interface to manager subscriptions without taking care of routine billing. It also takes care of discontinued contracts with BITE customers, and Customer care.

Initial subscription billing is performed according to the subscription price. Subscription renewal billing is performed according to “renew” parameter.

Each service subscription renewal period (month, day, etc.) is assigned a price. This price is used to bill the account automatically. Subscriptions are renewed based on renewal policy defined in “subscribe” function which accepts subscription term and renewal period parameters.

Term parameter defines when subscription should be terminated after it was created. For example, after an hour, day, week or month.

Renewal parameter defines when subscription should be renewed, for example, after an hour, one day, week or month. It's possible to pass special UNDEF or NONE values to these parameters to indicated undefined term and/or non-renewable subscription. It's not allowed to pass UNDEF value to term parameter when renewal is not NONE ('N').

Please consult the reference guide for precise parameter values.

If subscription renewal is needed in several (“X”) days, use Subscriptions port 1.1 functions subscribeAccount or subscribeAndDefineFirstBill. For these functions you must pass such term and renewal parameters values: term „X“, renewal „X“, termUnit “D”.

To get a list of all subscribers for a specific service getSubscribers function should be used. To check subscription status a checkSubscription function should be used. It returns an integer value which corresponds to a specific status. Please consult the reference guide for more detailed information of these values.

Important:

(A) Any subscription service (lets, say, SMS news) can only have one pricing scheme (renewal period and price). If you want to provide several renewal pricing levels, you have to use several services.

(B) The scheme is activated for each user when the subscription command is issued, and terminated when the term period expires or only if the user is unsubscribed (if there is a renewal period).

(C) Each service contains one list of subscribers. If you need to differentiate the subscribers into groups for your SMS application purposes (let’s say, subscriber group “A” is expecting a “Taurus horoscope and subscriber group “B” is expecting an “Aries” horoscope), you have to create a separate subscription service for each group (i.e. Service “Taurus horoscope” and service “Aries horoscope”).

CASE A: User subscribes to the service (valid for next 24 hours). During that time, service sends SMS to the user which are free for the user.

Subscription price: 1 Lt
Term: DAY
Renewal price: -
Renewal period: N
SendSMS (or SendMMS) price to the user: 0 Lt

CASE B: User subscribes to SMS notification service (valid forever). Subscription is free, received SMS is 0.3 Lt

Subscription price: 0 Lt
Term: UNDEF
Renewal price: -
Renewal period: N
SendSMS (or SendMMS) price to the user: 0.3 Lt

CASE C: User subscribes to SMS notification service (renewed each month, costs 1 Lt). During that time, received SMS message price to the user is additional 0.1 Lt per message.

Subscription price: 1 Lt
Term: MONTH
Renewal price: 1 Lt
Renewal period: M
SendSMS (or SendMMS) price to the user: 0.1 Lt

SMS or MMS messages can be sent to the whole list of persons who have subscribed the service with a single API request. This is detailed below, in the messaging ports explanation.

Messaging Port Service URL: http://soap.bite.lt/biteapi/services/MessagingPort
Messaging Port WSDL URL: http://soap.bite.lt/biteapi/services/MessagingPort?wsdl

Messaging Port functions:

BiteAPI web services interface provides several useful functions to send SMS and WAP PUSH messages.

To send SMS message to 1 recipient or a group of recipients sendSMS function is used. Recipients are determined by an array of account Ids (which may also contain a single account id) and by an array of MSISDNs. Final list of message recipients contains both.

The estimated amount of possible recipients in a single SMS submission request is 18000. However, it’s recommended to use Subscription functionality for lists that contain more than 100 users. To make such a list using subscription functionality, you have to subscribe all the recipients to a service, and then send SMS to that list of Service Subscribers.

Passing null value to account ids array parameter will result message being sent to the subscribers of a current service. The default serviceID from SOAP headers is used to determine which service should be selected.

This subscription feature is common to all messaging functions.

The messaging port can send at least 180 SMS messages per second. However, Bite API solely accepts message for submission and the actual message transmission might occur later in time depending on infrastructural factors.

All messaging functions accept parameters for billing: bill amount and bill currency, which are used to charge the recipient. All billing operations performed by the function itself, you don’t have to do additional billing. Our operations are transactional, therefore any message sending failure will result billing operation to be roll-backed.

Important note!
If you send out 100 messages with a cost of 1 Lt to the recipient, the actual number of recipients who will be billed depends on 2 factors: (A) was the prepaid account with sufficient balance? (B) did the user receive the SMS message? Therefore, the statistics may show, for example, that only 70 messages were billed, the rest were discarded.

Billing amount and currency should be configured in a list of prices for the particular action (for example, for sendSMS function, the action is “sendSMS”). Provider is not allowed to bill the recipient for an amount/currency if such a price is not created for that provider, service and action.

Note:
Contact Bite staff for configuration of prices at partner_support@bite.lt

It's possible to specify when the message should be actually sent as well as when the message becomes obsolete. Use startDeliveryTime and endDeliveryTime parameters.

Long messages (over 160 symbols) are concatenated automatically and will be sent in sequence to the recipient, however the user will be billed only once.

For now, it’s not possible to send binary SMS messages. If have any interest in such functionality you may contact us at partner_support@bite.lt

MM7 Port Service URL: http://soap.bite.lt/biteapi/services/MM7Port
MM7 Port WSDL URL: http://soap.bite.lt/biteapi/services/MM7Port?wsdl

Bite API provides a simplified version of MM7 protocol interface for accepting MMS messages.

Note:
Please consult 3GPP website, for a specification of MM7 protocol at:
http://www.3gpp.org/ftp/Specs/archive/23_series/23.140/23140-550.zip

Currently Bite API supports version 5.3.0 of MM7 protocol and additionally requires users to submit Bite API specific information in the SOAP headers of MM7 request message. Bite API MM7 port will not provide any MMSC debug responses other than error messages specific to Bite API, such as invalid or insufficient service or billing information.

Bite API requires additional information not required by MM7 specification in a form of a special SOAP header. This is a sample of SOAP header from a MM7 request message:

<soapenv:Header>
<mm7:TransactionID soapenv:mustUnderstand="0" xsi:type="xsd:string" 
xmlns:mm7="http://www.3gpp.org/ftp/Specs/archive/23_series/23.140/schema/REL-5-MM7-
1-2">013A71AE3167C52F517E5D5D654159EB</mm7:TransactionID>
  <provider-service soapenv:mustUnderstand="0" xmlns="">
   <service-id>1055</service-id>
  </provider-service>
  <billing soapenv:mustUnderstand="0" xmlns="">
   <amount>0.1</amount>
   <currency>LTL</currency>
  </billing>
  <subscription soapenv:mustUnderstand="0" xmlns="">true</subscription>
 </soapenv:Header>

The provider-service header is common to all Bite API request messages and is documented elsewhere in this document. MMS recipient billing information is supplied in billing header. It includes an amount to bill the account for and currency.

The estimated amount of possible recipients in a single MMS submission request is 14000, but the actual number is limited by the size of the POST request (max 2mb). It’s recommended to use subscriptions for sending MMS to more than 100 users (see section 3.4.2).

The messaging port can send at least 80 MMS messages per second. However, Bite API solely accepts message for submission and the actual message transmission might occur later in time depending on infrastructural factors.

If you want to send the MMS message to service subscribers, subscription header element indicates if this message should be delivered to the subscribers of specified services or to the list of recipients specified in the body of MM7 request message. In case a text value of this header is „true“, the message will be sent to the subscribers of the service indicated in provider-service header and the recipient list in MM7 request message body will be ignored.

<soapenv:Header>
<mm7:TransactionID soapenv:mustUnderstand="0" xsi:type="xsd:string" 
xmlns:mm7="http://www.3gpp.org/ftp/Specs/archive/23_series/23.140/schema/REL-5-MM7-
1-2">013A71AE3167C52F517E5D5D654159EB</mm7:TransactionID>
  <provider-service soapenv:mustUnderstand="0" xmlns="">
   <service-id>1055</service-id>
  </provider-service>
  <billing soapenv:mustUnderstand="0" xmlns="">
   <amount>0.1</amount>
   <currency>LTL</currency>
  </billing>
 
  <subscription soapenv:mustUnderstand="0" xmlns="">true</subscription>
 
 </soapenv:Header>

To connect and use the service, you will need to go through the following steps:

1. Acquire provider ID code
2. Acquire provider login
3. Acquire provider password
4. Acquire your service ID code
5. Agree on a service price
6. Download a SOAP client for your programming language
7. Install it, and set up a basic test script
8. Make a first request
9. Test billing with all price levels
10. Send SMS or MMS

The following parameters are provided when you sign a contract:

• Provider ID code
• Provider login
• Provider password

The service ID and its’ allowed prices are setup when you fill in the service sheet. Only configured prices are allowed. By default, only price 0.0 is allowed.

• Your service ID code
• An agreed service price
• For subscription services, agreed subscription price
• For messaging, agreed message price to the user

Provider Port Service URL: http://soap.bite.lt/biteapi/services/ProviderPort
Provider Port WSDL URL: http://soap.bite.lt/biteapi/services/ProviderPort?wsdl

Provider Port functions:

Provider web services port contains functions to retrieve information for partners about their services and actions associated with concrete services which also includes prices information.

To get a list of their services partners should use getServices function. Function getFunctions returns a list of allowed chargeable actions (for a specified service) partner can use and strictly informational actions showing other charging information.

Each action returned by getFunctions contains a map with provider price, user price, currency and other properties containing appropriate values. Please consult the reference for a full list of properties returned by this function.

Provider authentication is done using basic HTTP authentication method.

Firstly, the interface expects properly encoded username and password within the HTTP headers. All major SOAP client APIs on different platforms and programming languages include the programmatic method to set the HTTP authentication headers within the SOAP request.

Secondly, all SOAP requests to BiteAPI web services interface require appropriate SOAP headers which include provider and service information. Each call must be associated with some service to be properly identified. The system will not allow any requests without this information.

<provider-service>
      <service-id>YOUR_SERVICE_ID</service-id>
</provider-service>

Finally, each SOAP call must be accompanied by a proper value of SOAPAction HTTP header which is empty by default on some platforms (e.g. PHP).

You can use these SOAPActions, each corresponding to appropriate operation:

Messaging Port
http://biteapi.metasite.net/messaging/sendSMS
http://biteapi.metasite.net/messaging/sendSMSDirect
http://biteapi.metasite.net/messaging/sendWAPPush

Provider Port
http://biteapi.metasite.net/provider/getServices
http://biteapi.metasite.net/provider/getFunctions
http://biteapi.metasite.net/provider/getAccountByIP
http://biteapi.metasite.net/provider/getMsisdn

Subscriptions Port 1.1
http://biteapi.metasite.net/subscriptions/getSubscribers
http://biteapi.metasite.net/subscriptions/checkSubscription
http://biteapi.metasite.net/subscriptions/unsubscribeAccount
http://biteapi.metasite.net/subscriptions/subscribeAccount
http://biteapi.metasite.net/subscriptions/subscribeAndDefineFirstBill

Subscriptions Port
http://biteapi.metasite.net/subscriptions/getSubscribers
http://biteapi.metasite.net/subscriptions/checkSubscription
http://biteapi.metasite.net/subscriptions/unsubscribeAccount
http://biteapi.metasite.net/subscriptions/subscribeAccount
http://biteapi.metasite.net/subscriptions/subscribeAndDefineFirstBill

Billing Port
http://biteapi.metasite.net/billing/billAccount
http://biteapi.metasite.net/billing/openTransaction
http://biteapi.metasite.net/billing/commitTransaction
http://biteapi.metasite.net/billing/rollbackTransaction

Billing Port 1.1
http://biteapi.metasite.net/billing/billAccount
http://biteapi.metasite.net/billing/openTransaction
http://biteapi.metasite.net/billing/commitTransaction
http://biteapi.metasite.net/billing/rollbackTransaction

MM7 Port
http://biteapi.metasite.net/messaging/sendMMS

Device Port 1.1
http://biteapi.metasite.net/device/1.1/getDeviceModelsList
http://biteapi.metasite.net/device/1.1/getDeviceInfo
http://biteapi.metasite.net/device/1.1/getDeviceProperty
http://biteapi.metasite.net/device/1.1/getDeviceModel
http://biteapi.metasite.net/device/1.1/getDeviceModelsProperty

Device Port
http://biteapi.metasite.net/device/getDeviceModelsList
http://biteapi.metasite.net/device/getDeviceInfo
http://biteapi.metasite.net/device/getDeviceProperty
http://biteapi.metasite.net/device/getDeviceModel
http://biteapi.metasite.net/device/getDeviceModelsProperty

More information: http://soap.bite.lt/biteapi/docs/biteapi_ref.pdf

Note:
SOAPAction header values are non-physical URI's which just describe the SOAP action itself. Many clients will be happy using port WSDL files which are located at http://soap.bite.lt/biteapi/axisinfo

All end users are identified by their unique Account ID. Account ID is never reused, it is unique to the very phone number and person using it.

When the user passes through the SMSC, the only the MSISDN becomes available. You have to use MSISDN instead of Account ID for SMS based functions, or you can resolve the AccountID from MSISDN.

Warning: Provider should never use the Account ID which was acquired outside Bite network. Only those which have been collected from the user request are allowed.

For testing purposes you should hardcode the following user ID

• Lithuanian account ID: 2219983
• Latvian account ID: 3164194

Partner will be constrained to access BiteAPI only from a specified fixed IP address provided.

This section concentrates on providing instructions to access BiteAPI web services interface using different platforms, in particular PHP and Python. It includes general information on how to properly format SOAP request messages and interpret SOAP responses. BiteAPI web services interfaces strives to support all major platforms.

Depending on which version of PHP is used different SOAP client libraries might be used.

In PHP version 4, nuSOAP client library can be used. Consult it's website (http://dietrich.ganx4.com/nusoap/index.php) for more reference information. To access BiteAPI web services interfaces proper HTTP authentication and custom SOAP headers must be constructed and included in a request. Here is a sample PHP 4 class working a facade to the web service interface and using nuSOAP:

class SOAPManager { 
 var $s; //SOAP client object 
 var $conf; //Configuration file object 
 
    function SOAPManager(){ 
        // READ CONFIGURATION 
        $this->conf = new ini_file(dirname(__FILE__).'/../../ini/admlt_ini.php');  
        $wsdl_url=$this->conf->read_var('soap', 'wsdl'); 
        $password=$this->conf->read_var('soap', 'password'); 
        $user=$this->conf->read_var('soap', 'user'); 
        $service_id=$this->conf->read_var('soap', 'service_id');
	        // NEW SOAP CLIENT INSTANCE 
        $this->s = new soapclient($wsdl_url);
	        // HTTP BASIC AUTHENTICATION 
        $this->s->setCredentials($user,$password); 
 // CUSTOM SOAP HEADER REQUIRED BY BiteAPI 
        $this->s->setHeaders("<provider-service><service-id>$service_id</service-id></provider-service>");  
    } 
    function getDeviceModelsList(&$err) { 
        // REQUEST PARAMETERS 
        $param = array();
	        // SOAP CALL. SOAP action is the last parameter. 
        $res = $this->s->call('getDeviceModelsList', $param, 
'http://biteapi.metasite.net/device','http://biteapi.metasite.net/device/getDeviceModelsList');  
        if (!$err = $this->s->getError()) {                      
            return $res['getDeviceModelsListReturn'];            
        } else {     
            return;                                             
        } 
    } 
}