FTP API [Bulk SMS] Documentation

ViaNett provides interfaces for customers who wish to send large number of SMS messages in one batch. Customers can store SMS messages in a text file and upload the file to the FTP interface on ViaNett's server. Then the messages are automatically handled/sent via ViaNett's system, and an email with the status of the transaction is sent to the customer. ViaNett can also provide customers with delivery reports for each SMS message through ViaNett's ordinary interfaces (Java, HTTP, Visual Basic etc).

Requirements

  • The sender has to have a ViaNett SMS account with available SMS credits. Please contact the customer service if you don’t have one.
  • The sender has to contact the customer service in order to get a ViaNett FTP account.
  • An editor like notepad or vim (Linux users). (Alternatively, the customer needs to write a program or a script that generates the FTP bulkinsert files).
  • An FTP client to upload the text file.
  • For the FTP domain name and location, please contact the customer service. 
  • FTPS is also available in addition to regular FTP, and recommended for GDPR compliance.

Types of messages you can send

There are different types of sending messages via FTP API interface, and each of them is used for different purposes.

Type 1:Used for sending premium messages. See below.
Type 2: This is used for sending bulk SMS messages. See below.
Type 3: It is mainly used for sending MMS messages, which is like type 2, but with MMSID. The MMS has to be stored one the server first before sending.
Type 4: Used for scheduling bulk messages. Same as type 2, but with different filename.

Syntax

Type 1
Content: #|#msgid#|#sno#|#operatorid#|#tel#|#msg#|#pricegroup#EOR#
File Name: 1_transactionNumber_username_password.txt
Type 2
Content: #|#msgid#|#fromnr#|#fromalpha#|#teleop#|#tel#|#msg#|#nrq#|#priority#EOR#
File Name: 2_transactionNumber_username_password.txt
Type 3
Content: #|#msgid#|#fromnr#|#fromalpha#|#teleop#|#tel#|#msg#|#nrq#|#priority#|#mmsid#EOR#
File Name: 3_transactionNumber_username_password.txt
Type 4
Content:#|#msgid#|#fromnr#|#fromalpha#|#teleop#|#tel#|#msg#|#nrq#|#priority#EOR#
File Name: 4_transactionNumber_username_password_timestamp_interval.txt

Description and field definitions

#|#
Is used to separate fields.
#EOR#
End of row
msgid
The customer is required to put a unique message id per message such as 1, 2 or any numeric value (this is used by the ViaNett internal system).
fromnr
The sender’s number in numeric format . This could be real number  such as 47xxxxx (including country code) or short-code such as 1963.
fromalpha
Source address, the sender number in alphanumeric format such as James or James123.
teleop
Use the value 0 by default (ViaNett will handle routing automatically), or provide a gateway no if you wish to use another operator.
tel The recipient phone number including the country code such as 47xxxxxxxx
msg
Your message (maximum number of characters is 1500 characters, Unicode characters are supported)
nrq Notification request. If you wish to receive delivery reports about the messages you sent. (0 is No or 1 is Yes)
priority
This is if you give priority to the message you are sending (0 is Low or 1 is High).
mmsid The default is 0, otherwise contact the customer service for more information.
#EOR#
End of row.
operatorid Use the value 0 by default, or provide a gateway no if you wish to use another operator.
sno
Sender's number.
pricegroup Please choose the right price-group for the relevant country found under this link.

How to send multiple messages to multiple recipients?

Let us assume that you wish to send a Bulk type 2 SMS.

  • Open a text file with your favorite text editor.
  • Write your text messages using the following formats (no spaces between them).

#|#1#|#1963#|#ViaNett#|#2#|#4791748750#|#This is a test with delivery and high priority#|#1#|#1#EOR##|#2#|#1963#|#ViaNett#|#2#|#4791748750#|#This is a test without delivery and with low priority#|#0#|#0#EOR#

What Name Shall I Give to the Text File?

The text file has to be saved in the form of bulkinserttype_transactionNumber_username_password.txt

bulkinserttype
The values are 1, 2, 3 and 4 (depends on what type have you chosen)
transactionNumber
This is unique to this file. For example if you choose 3 to be your unique number for one of your text files, you should not use 3 again for another file you upload. Choose a different unique number for each uploaded text file.
username
This is your ViaNett SMS username.
password
ViaNett SMS password.
timestamp
Timestamp is in CET in YYMMDDHHMM
interval
The delay between each sent message.

NB: Make sure that you don't use underscore for your username/password, Please contact the customer service for several usernames and passwords if you wish to have different statistics on different kind of traffics.

If you wish to schedule the messages to be sent another time

Please use the following format to schedule messages using bulkinsert (NB: Timestamp is in CET).

For example

4_1_username_password_0812241715_60.txt
This example will start the send out on December 24 2008 at 17:15 CET, with an interval of 60 seconds between messages.

Secure connection

To establish a secure connection you need to specify "TLS/SSL explicit encrytion" when connecting to the FTP server, the port remains the same.

Folder structure

There are four folders at the user root folder:

bulkinsert: This is where files should be uploaded, if a file is uploaded to any other folder it will be ignored.

processing: A file that was uploaded to the bulkinsert folder will be moved here during processing, it will then be moved to either the failed folder or success folder depending on the result.

success: All files that were successfully processed and sent will be found here, there will also be a duplicate file with _result appended to the file name that contains a readable report.

failed: All files that failed processing and were not sent will be found here, there will also be a duplicate file with _error appended to the file name that contains a description of what went wrong.


Information

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