YAP API Documentation

This document is for experienced users who wish to make their own SMS clients using the YAP protocol. One can design and implement a Perl, Visual Basic or a .NET client using YAP over TCP/IP connections.

Requirements

  • ViaNett SMS username and account. Please contact ViaNett Customer Service if you don't have one.
  • Destination host: yap.vianett.no
  • Destination port: 31337,31338 or 31339 (or 23001, 23002 and 23003 with TLS support)
  • Knowledge of socket programming and YAP commands.

Basic YAP

As part of your client application, you need to use some YAP commands in order to open a TCP connect with ViaNett's server, send or receive SMS messages. Each command shall be acknowledged with an ack command to guarantee its delivery.

The YAP commands

The YAP commands are in the form of:

command: param1=value1 param2=value2 param3=value3 paramN=valueN 
command_ack: param1=value1 

The above statements can be represented in the following example:

login_op: refno=1 username=myUserName password=myPassword 
login_op_ack: ack_code=200 refno=1 

YAP Commands
 Options With Examples
Login command:
login_op
 Initiated by the SMS client to login.
  • username: Login username from ViaNett.
  • password: Password from ViaNett.
  • encoding: If "UTF-8" specified, UTF-8 encoding used, otherwise ISO-8859-1.
  • refno: Reference ID (usually increases by 1 for each login attempt). Values should be between 1 and 2147483647.
  • version: Client version.

Example: login_op: refno=6 username=xxxx password=xxxx
Login acknowledge:
login_op_ack
 Initiated by the SMS server to acknowledge the login command.
  • If ack_code =200 means OK.
  • if ack_code=500 means not OK.

Example: login_op_ack: ack_code=200 refno=6
Logout command:
logout_op
 Initiated by the SMS client to log out.
  • refno: Reference ID (usually increases by 1 for each attempt). Values should be between 1 and 2147483647.

Example: logout_op: refno=1
Logout acknowledge:
logout_op_ack
 Initiated by the SMS server to acknowledge the logout command.
  • refno: Reference ID (same as the one provided in logout_op).
Example: logout_op_ack: refno=1
Sending SMS:
sms_to_op
 Initiated by the SMS client to send message .
  • refno: Unique reference for the message.
  • sno: Numeric sender address.
  • message: Message content.
  • header: Message header such as binary messages.
  • msn: Destination address.
  • fromalpha: Non-numeric sender address such as James or James123.
  • operator: Is 0 for default routing, otherwise gateway ID.
  • pricegroup: Check the billing page.
  • nrq: Notification request (delivery report).
  • referenceid: Provide the value from the incoming message, where applicable.
  • priority: Should normally be 0, a value > 0 will be a priority message, a value < 0 will be a non-priority message.
  • campaignid: The campaign ID.
  • activatereplypath: Set to 0 for non-replypath messages, or for the number of seconds the replypath should be valid for this message.
  • replypathid: The ID that will be returned for the incoming replypath message reply.
  • senddate: Optional, schedule the message at a later date in ViaNett's systems.
  • smscscheduledate: Optional, schedule the message at a later date at the SMSC (usually not supported).
  • mms: Optional, base64-encoded MMS ZIP file.

Example: sms_to_op: refno=7 sno=1963 msn=4791748750 pricegroup=0 msg=test srcoperator=0.

Please be aware that to encode a space, you should use %20, as + is not decoded as a space.
Sending SMS and acknowledge:
sms_to_op_ack
 Initiated by the SMS server.
  • ack_code: 200 OK, 500 error, 400 syntax error
  • refno: To reference the message.

Example: sms_to_op_ack: ack_code=200 refno=7
Receiving SMS:
sms_from_op
 Initiated by the SMS server.
  • msn: Source address.
  • msg: Message content.
  • Replypath: True/false, depending on whether replypath is active.
  • replypathid: The ID of the outgoing message to which this incoming message is a response, if replypath is activated.
  • accessnumber: The short code to which the message has been sent.
  • destnr: Destination address (usually the same as accessnumber, with some exceptions, e.g. replypath in Norway).
  • srcoperator: The teleop from which the incoming message originates.
  • campaignid: The campaignid of the incoming message.
  • referenceid: Reference value (needs to be specified on outgoing response messages in some cases).

Example: sms_from_op: msn=4791748750 msg=Test srcoperator=1 refno=230974
Receiving delivery reports:
delivery_from_op
 Initiated by the SMS server.
  • msgid: Every message has an ID.
  • msn:Destination address of message.
  • srcoperator: The operator via which the message was sent.
  • mcc: Mobile Country Code.
  • mnc: Mobile Network Code.
  • smscid: ViaNett's internal message ID.
  • campaignid: The ID of the campaign the message was sent on.
  • ok: True/false, depending on whether the message was successfully submitted.
  • sentdate: The date the message was sent.
  • deliverydate: The date the delivery report was received by us (for deliverytype 2 and 3).
  • sno: The numeric sender address.
  • fromalpha: The alphanumeric sender address.
  • errorcode: The errorcode of the message.
  • pricegroup: The pricegroup value the message was sent with.
  • consumerprice: The end-user price of the message incl VAT.
  • netprice: The operator payout excl VAT.
  • cparevenue: The ViaNett customer revenue excl VAT.
  • cut: Customer percentage of the revenue/cost (value 0-100).
  • deliverystatus: Status of the message.
  • deliverystatuscode: Status code of the message.
  • deliverystatusdescription: Description of the meaning of the status code.
    Example: delivery_from_op: msgid=7 ok=True srcoperator=1 sentdate=16.03.2004%2020%3A38%3A50 errorcode=200 refno=1234
Receiving delivery reports and acknowledge:
Delivery_from_op_ack
 Initiated by the SMS client.

Example: Delivery_from_op_ack: refno=1234
Receiving SMS and acknowledge:
sms_from_op_ack
 Initiated by the SMS client.

Example: sms_from_op_ack: refno=230974
Is alive:
is_alive
 Initiated by the SMS client. Should be sent by the client once every 30 second in order to ensure that the connection remains active.

  • seqno: A sequence number, incremented by 1 for each is_alive request. Values should be between 1 and 2147483647.
Example: is_alive: seqno=12345
Is alive acknowledgement:
is_alive_ack
 Initiated by the SMS server.

  • ack_code: 200 = OK, 0 = user is not logged in.
  • seqno: The same as the seqno in the is_alive request.
Example: is_alive_ack: ack_code=200 seqno=12345

PSEUDO CODE EXAMPLE

This is only a pseudo code example and not a working code. It follows C# and Java coding syntax.

EVENT - On application load: 
 
// Create a new socket. 
Socket myConnection = new Socket(); 
 
// Connect to yap.vianett.no through port 31337. 
myConnection.connect "yap.vianett.no", "31337"; 
 
EVENT - On myConnection.connected 
 
// Send login information. 
myConnection.Send "login_op: refno=1 username=xxxx password=xxxx"; 
 
EVENT - On myConnection.SendSMS 
 
// Send SMS, Sender(sno): 1963, Receiver(msn): 4790000000, Message(msg): test 
myConnection.Send "sms_to_op: refno=7 sno=1963 msn=4790000000 pricegroup=0 msg=test srcoperator=0"; 
 
EVENT - On myConnection.datareceived 
 
// Split all the data on space. In some code languages you have to convert split character to char type. 
string[] params = data.split(" "); 
// Check what data you have received, in this pseudo code example we do this by a for loop, and a switch statement. 
for (int i = 0; i < params.Length; i++) 
{ 
   // Switch on main param which is always the first. 
 switch(params[0]) 
 { 
// Check if login is successful. 
  case "login_op_ack": 
  // Check parameters. 
 switch(params[i]) 
  { 
 case "ack_code": 
   int ack_code = 0; 
       // Try parse result of ack_code. 
        int.tryParse(params[i].replace("ack_code=", ""), out ack_code); 
        if (ack_code == 200) 
      // Login successful. 
         } 
    break; 
    // Check if SMS was successfully sent. 
   case "sms_to_op_ack": 
    // Check parameters. 
      switch(params[i]) 
       { 
    case "ack_code": 
       int ack_code = 0; 
          // Try parse result of ack_code. 
      int.tryParse(params[i].replace("ack_code=", ""), out ack_code); 
    if (ack_code == 200) 
     // SMS sent successful. 
       } 
   break; 
               } 
} 

More information

For a free demo account, please register here.
To contact Sales or  Customer Service please click here.