HTTP GET/POST API Documentation

Introduction
Requirements
Security
Formats and Standards
Incoming message (MO)
Outgoing message (MT)
Delivery message (MT)
Delivery report - Phone
Delivery report - Server
MMS messages

Introduction

This documentation provides a technical description of how to integrate an application for sending and receiving SMS and MMS through the ViaNett system and the HTTP API.

All messages are sent using HTTP GET or HTTP POST requests, and all responses are in XML format.

Outgoing Messages (MT)

Example - Send SMS

https://smsc.vianett.no/v3/send?
username=demot
&password=demo
&msgid=1234
&tel=4711111111
&msg=Hello+World
&pricegroup=300
&campaignid=12345

Positive response

If the message is successfully submitted to ViaNett's systems, a positive reponse in text format will be sent back to the original sender.

Negative response

A negative reponse will be sent back to the orginal sender if the message has an issue like wrong username or password. The format of the reponse is in text format.

Field definitions - Outgoing Messages (MT)

username	The username that is given by Vianett.
password	The password that is given by Vianett.
msgid	Message reference number. This number must be a unique ID
SenderAddress	Numeric or alphanumeric sender address
SenderAddressType	International MSISN=1, short code=2, alphanumeric=5
Tel	Recipient MSISDN on internationational format. Multiple receipient can be seperated by ; (note that querysting maxlength is 2048 bytes)
msgbinary	If set to true, message is considered a binary hex string
msgheader	Header of message as a hex string
ReplyPathValue	if > 0, replypath activated, denotes timeout in minutes for replypath functionality
ReplypathID	Will be returned on incoming reply to the sent message
ScheduledDate	Schedule time on our side
ScheduledSMSCDate	Schedule time on supplier's side.
ReferenceID	If message is response to an incoming message, provide the reference value on the outgoing message
CheckForDuplicates	Reject duplicate messages with a previously recently provided messageid
MMSdata	base64 encoded version of mms zip file.
mmsurl	URL which can be used to download ZIP file of MMS file from ViaNett (alternative to MMSdata)
msg	Message in UTF-8 format. For flash SMS, add flashsms: at the start of each message.
PriceGroup	The pricegroup, for billing end-users, specified in the local sub currency unit. Example: 100 is NOK 1 and 1500 is NOK 15.
CampaignID	The id value of the campaign
TeleOp	Operator Value
Nrq	Notification request
Priority	if greater than zero is high priority
HLRMCC/HLRMNC/HLRDate	Permission required. Contact SMS Support.

Delivery Report

If you wish to get a delivery reponse from ViaNett for the messages you have sent, you need to create a script that allows ViaNett to deliver the reports. The URL to your script should be provided under Connections.

Example of delivery report request

http://yourserver.com/yourscript.php
?requesttype=mtstatus
&refno=1234
&errorcode=0

Response:
This response is from your script to ViaNett's system.

Field definitions - Delivery Report

Refno	Message reference number. This will be the same as refno on your MT message.
requesttype	This field will have the value "mtstatus".
errorcode	This field will be 0 if the message was delivered to the user.

Delivery Report - Phone

Intermediate delivery report to phone

This is when the message is sent to the phone, but the phone may not have received the message yet, e.g. if the phone is turned off.

Example

http://yourServer/yourScript
?password=
&username=
&refno=1234
&Status=ACCEPTD
&requesttype=notificationstatus
&StatusDescription=Absent+subscriber
&StatusCode=107
&now=06%2E10%2E2005+11%3A24%3A07&

Status	ACCEPTD/BUFFERD - stored in SMSC, not yet delivered
requesttype	Type of the request you receive from ViaNett, for this type of delivery report it has the value notificationstatus
StatusDescription	A description of the meaning of the value specified in StatusCode (not all values have a description).
StatusCode	Code representing the status of the message
now	Current date/time in CET (specified to avoid proxy caching issues)

Reply

Final delivery report to phone

This delivery report tells you the status of the message in terms of whether it has been delivered to the handset of the recipient.

Example

http://yourServer/yourScript
?password=
&username=
&refno=1234
&Status=DELIVRD
&requesttype=notificationstatus
&StatusDescription=
&StatusCode=0
&now=05%2E10%2E2005+00%3A30%3A06&

Reply

Delivery report - Server

This is a delivery report indicating whether the message was successfully delivered to the operator.

Simple delivery report from operator

This is the delivery report from the operator. This contains information about whether the message was successfully sent.

Example

http://wwwyourServer/yourScript
?password=
&username=
&refno=1
&requesttype=mtstatus
&msgok=-1
&errorcode=0
&now=05%2E10%2E2005+03%3A04%3A57&

Reply

Advanced delivery report from operator

This is the same as Simple delivery report, but it contains more details about the message delivery.

Example

http://yourServer/yourScript
?password=
&username=
&refno=1234
&requesttype=mtstatus
&msgok=True
&ErrorDescription=OK
&ErrorCode=200
&Status=
&SentDate=05%2E10%2E2005+00%3A41%3A27
&OperatorID=1
&CountryID=1
&CampaignID=1234
&Cut=90&CPAContentCost=0
&CPACost=0
&CPARevenue=1%2C35
&NetPrice=1%2C5
&ConsumerPrice=3
&PriceGroup=300
&Msg=Your message is accepted%2E
&Tel=1234
&FromAlpha=vianett
&sno=1963
&now=05%2E10%2E2005+00%3A41%3A43&

msgok	Whether the message was successfully submitted. True for successful submission.
SentDate	The date and time the message was sent.
OperatorID	The operator/gateway through which the message was sent.
CountryID	The country ID of the message (1 = Norway, 2 = Sweden, 8 = Denmark, etc)
Cut	The percentage of the revenue from the operator paid out to customer or percentage of cost paid by customer.
CPACost	Cost of message to customer
CPARevenue	Revenue of message to customer
NetPrice	Operator payout
ConsumerPrice	Price for end-user incl VAT
PriceGroup	Pricegroup of message
Msg	Message contents
FromAlpha	Alphanumeric source address
sno	Numeric source address
now	Current date/time in CET (specified to avoid proxy issues)

Reply

Incoming Messages (MO)

In order to receive incoming messages via HTTP, you need to implement a script on your own web server. Whenever the script is called, it needs to respond with an ack, see below.

The URL to the script must be specified under "HTTP url" on the connection you want to use.

Example
http://yourserver.com/yourscript.php?sourceaddr=4748044407&destinationaddr=1963&prefix=demo&message=Hello%20world&refno=1234&retrycount=1&operator=1&requesttype=mo&username=&password=

Response

<?xml version="1.0"?>
<ack refno="1234" errorcode="0" />

Response with message to the user

Response with MMS message to the user

<?xml version="1.0" encoding="iso-8859-1"?>
<ack refno="1234" errorcode="0">
    <response_mmsdata>Base64-encoded MMS ZIP file</response_mmsdata>
</ack>

Field definitions - incoming messages (MO)

sourceaddr
The originator number.
destinationaddr
The destination number.
prefix
The first word in the message (keyword).
message
The last part of the message.
refno
ViaNett's message ID. Reference number.
retrycount
How many times the message has tried to be delivered.
operator
The operator ID. 1 is Telenor Mobile (Norway), 2 is NetCom (Norway), etc.
requesttype
This field will have the value "mo" on incoming messages.
username
Optional username.
password
Optional password.
replypathid
Only used for two-way dialogue, default 0.

MMS messages

An MMS consists of a ZIP-file containing one or more files of multimedia content (such as images, audio and/or video). It may also contain a file named mms.smil, written in a subset of the Synchronized Multimedia Integration Language (SMIL), which ties together the various files much like an HTML page would.

An example is available for download here.

MMS messages are transferred either by converting the ZIP-file into a URL-encoded Base64-encoded string (this string is then specified in the parameter mmsdata in the URL), or by providing a URL to an MMS ZIP-file.

Incoming MMS messages are stored on our server, and a link to the file representing the MMS message is also provided in the parameter mmsurl in the incoming HTTP request.

Incoming MMS

This is for MMS messages that you will receive on your server. Replace http://yourserver/yourscript with the correct address to your script.

Example

http://yourServer/yourScript
?password=
&username=
&requesttype=mo
&mmschecksum=1796011280
&mmsdata=UEsDBBQACAAIAAyzSjMAAAAAAAAAAA[....clip....]
AAAAEAAQA4wAAAAMSAQAAAA%3D%3D
&mmsurl=http%3A%2F%2Fsmsc%2Evianett%2Eno%2Factiveserver%2Fmo%2Fgetmms%2F%3F
mmsid%3D1234%26checksum%3D1234
&operator=1
&retrycount=0
&refno=1234
&message=1234%3A
&prefix=1234
&destinationaddr=1963
&sourceaddr=1234
&now=10%2E10%2E2005+22%3A24%3A28&

username/password	Usually left blank, please contact customer service if you want Vianett to provide a username and password to your script
requesttype	Has value MO (Mobile Originating) for incoming MMS and SMS messages.
mmschecksum	Checksum of the MMS
mmsdata	Base64-encoded ZIP file with MMS content
mmsurl	URL which can be used to download ZIP file of MMS file from ViaNett
retrycount	How many times ViaNett has tried to deliver message to customer
message	Message contents, apart from the prefix.
prefix	Prefix, i.e. first word of message
destinationaddr	Destination address
sourceaddr	Source address

Reply

Outgoing MMS

This is for MMS messages sent out by your server. These messages will go to ViaNett's server, and from here it will be sent to the mobile number specified in your MMS message.

Example using Base64

http://ams.smsc.vianett.no/v3/cpa/oldactiveserver/bridgemt.ashx
?username=demo
&password=demo
&message=1234
&refno=1234
&sourceaddr=1963
&destinationaddr=4748044407
&mmsdata=base64encodedmmsfile

Reply

Example using ZIP-file

http://ams.smsc.vianett.no/v3/cpa/oldactiveserver/bridgemt.ashx
?username=demo
&password=demo
&message=1234
&refno=1234
&sourceaddr=1963
&destinationaddr=4748044407
&mmsurl=http://oldsms.vianett.com/files/mms.zip

mmsurl

URL to MMS ZIP file (used as an alternative to submitting MMS ZIP file as base64-encoded string).

Reply