BiteAPI User's Guide for SMS service providers

1 Introduction

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

1.1 What is BiteAPI?

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.

1.2 Request Scheme

Request Scheme

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)

2 General concepts

2.1 Providers

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”.

2.2 Services

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.

2.3 Actions

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).

2.4 System support process

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.

3 What can the API do for me?

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

3.1 Transactional billing (BillingPort)

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:

Function SOAPAction
billAccount http://biteapi.metasite.net/billing/billAccount
openTransaction http://biteapi.metasite.net/billing/openTransaction
commitTransaction http://biteapi.metasite.net/billing/commitTransaction
rollbackTransaction http://biteapi.metasite.net/billing/rollbackTransaction

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:

Account action ID Description
sendContent 374 Send content to account, such as java games, mp3 files and other.
browse 380 Browse wap/web content.
billAccount 350 For other purposes (for example, to bill for SMS, which is sent through SMPP).

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.

3.2 Subscriptions (SubscriptionsPort) billing port

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:

Function SOAPAction
getSubscribers http://biteapi.metasite.net/subscriptions/getSubscribers
checkSubscription http://biteapi.metasite.net/subscriptions/checkSubscription
unsubscribeAccount http://biteapi.metasite.net/subscriptions/unsubscribeAccount
subscribeAccount http://biteapi.metasite.net/subscriptions/subscribeAccount
subscribeAndDefineFirstBill http://biteapi.metasite.net/subscriptions/subscribeAndDefineFirstBill

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.

3.2.1 Limitations

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”).

3.2.2 What you can do with subscription pricing

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.

3.3 SMS messaging (Messaging port)

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:

Function SOAPAction
sendSMS http://biteapi.metasite.net/messaging/sendSMS
sendWAPPush http://biteapi.metasite.net/messaging/sendWAPPush
sendSMSDirect http://biteapi.metasite.net/messaging/sendSMSDirect

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.

3.3.1 Sending SMS/PUSH to subscription 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.

3.3.2 Messaging throughput capacity

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.

3.3.3 Messaging billing (assigning an end-user price)

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

3.3.4 Scheduling

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.

3.3.5 Concatenation

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.

3.3.6 Binary SMS

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

3.4 MMS messaging (MM7 port)

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).

3.4.1 MMS Messaging throughput capacity

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.

3.4.2 Sending MMS to subscription service subscribers

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>

3.5 What are the steps I need to take to start using the API?

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

3.6 Provider selfcare (Provider port)

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:

Function SOAPAction
getServices http://biteapi.metasite.net/provider/getServices
getFunctions http://biteapi.metasite.net/provider/getFunctions
getMsisdn http://biteapi.metasite.net/provider/getMsisdn
getAccountByIP http://biteapi.metasite.net/provider/getAccountByIP

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.

4 Connecting and using the API

4.1 Provider authentication

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

4.2 End-user identification

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.

4.3 Testing user IDs

For testing purposes you should hardcode the following user ID

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

4.4 Security

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

4.5 Platform specific instructions

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.

4.5.1 PHP SOAP client

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;                                             
        } 
    } 
}
 
api_users_guide_sms.txt · Last modified: 2007/09/28 15:05 by admin