SMS v-Gateway Solution

SMS v-Gateway Solution


Introduction

SMS v-Gateway is a virtual gateway which offers an API SMS solution to send SMS, receive replied messages, check delivery status of outgoing SMS and search message histories. The diagram below provides an overview of the workflow for these functions.

manual_gateway_send_sms

Figure 1: Dialog map of SMS v-Gateway

Back to Top

How to Use SMS v-Gateway

To use SMS v-Gateway, first you need to set up the virtual gateway via Mweb. Once you’ve completed the set up process, you can send SMS using the HTTP API. There is an alternative which allows you to send texts via Mweb. To browse the message histories in detail, you can search the records using the HTTP API. Follow the steps below:



1. Set Up

The "Set Up" processes include two parts: set up from Administrator Side and Client Side:

  • Administrator Side:

    At the administrator side, multiple "Sender Mobile Numbers" such as "+61427575337" and "+61428158850" will be prepared for you. Through these sender numbers your SMS messages will be sent to the recipients. You can choose to use any of them according to your needs.


  • Client Side:

    At the client side, you need to finish the following settings before you can successfully access SMS v-Gateway:

    1) Claim authorized manager "Account Name" and "Password" from us then log in Mweb from this page to start the setup. (Please click here to choose a method to contact us for claiming your account)

    2) Create a "Contact Book" with the minimum needed columns shown in the following image to store the contact information of all your recipients. You can also create more columns for more complicated use of SMS v-Gateway, please see Advanced Features to know more extendable functions.( "Contact Book" in Mweb is designed as an electronic phone book which defines the specific attributes (named as "columns" in Mweb) such as "Name" and "Phone Numbers" that you want to store for your recipients. Please click here to know more details about how to create the "Contact Book" and define columns)

    manual_gateway_send_sms

    Table 1: Minimum needed columns for using SMS v-Gateway


    3) Create a "Contact Group" in the "Contact Book" that you created in last step to store the contacts (recipients) where the SMS will be sent to. ("Contact Group" is used to categorize contacts in the same "Contact Book" to different groups for better contact management and more convenient SMS sending in various scenarios. Please click here to see how to create a "Contact Group")

    4) Create broadcast - "Direct Gateway SMS" which is the user interface access for you to set up all the settings of SMS sending for SMS v-Gateway. (Please click here to see how to create this broadcast. To know more about "Broadcast", please click here)

    5) Start the broadcast you just created. (Please click here to see how to start a broadcast)

    Note: To know more details of the "Set Up" process, please see Example in this page


2. Send SMS

There are two options for you to send out SMS: Send SMS Through HTTP API or Send SMS Through Mweb.

2.1 Send SMS Through HTTP API

Once the set up process is done, you can call HTTP API to start sending SMS. The API function to be used is VGATEWAY_SEND_SMS. It allows you to send out SMS to a recipient and receive replies. Delivery receipts and notification of replies will be pushed to your server via the URL you specified.

Below is a list of parameters required to make the request:

SMS v-Gateway API Parameters

Table 2: Request Parameters

For more information about the response data and examples of VGATEWAY_SEND_SMS, please visit this page.


2.2 Send SMS Through Mweb

Another option to send out SMS through SMS v-Gateway is via Mweb. When finishing all the "Set Up" steps above, your broadcast will be ready to use. As long as you add contacts into your "Contact Group" now, the system will send out SMS for you automatically. (This happens because of the "Broadcast new added contact" option which is needed to set to "Yes" when you create the broadcast as described in this page.) Mweb offers two methods to add contacts. You can click here to see how to add contacts one by one. Or click here to see how to upload multiple contacts at one time.



3.2 Search SMS Histories Via Mweb

You can also search and view a record of your SMS sent and received in detail through Mweb. Please visit this page to know more details.


Back to Top

Examples

This section walks through a sample case that uses the SMS v-Gateway. The purpose is to show the required steps for set up and to demonstrate the invocation and subsequent handling of HTTP API calls. The steps are given below:


Step 1: Login to Mweb

Sign in to Mweb with your registered account on this page. In this example, the sample account is "example_account@gmail.com"; password is "ex@mple_@ccount".


Step 2: Create a Contact Book

Create a Contact Book with the required columns described before to store your contacts. Here, we create a Contact Book named "SMS v-Gateway sample Contact Book".

sms_vGateway_contact_book

Figure 2: "SMS v-Gateway sample Contact Book"


The following figure shows the settings of each column:

sms_vGateway_column_settings

Figure 3: Settings of each column


Step 3: Create a Contact Group

Create a Contact Group within your Contact Book to store the recipients that SMS will be sent to. Here, we create a Contact Group named "SMS v-Gateway sample Contact Group".

sms_vGateway_contact_group

Figure 4: "SMS v-Gateway sample Contact Group"


When creating the Contact Group, choose the "SMS v-Gateway sample Contact Book" to store it.

sms_vGateway_contact_group_in_CB

Figure 5: Choose "SMS v-Gateway sample Contact Book"


Once the contact group is created, go to this group page and you can find the ID of the contact group in the URL. Note: This ID is required for sending SMS via HTTP API.

Contact group ID

Figure 6: Retrieve the ID of the contact group


Step 4: Create a Broadcast

Create a "Direct Gateway SMS" broadcast to access SMS v-Gateway function. In this example, we create a broadcast named "SMS v-Gateway sample Broadcast".

sms_vGateway_broadcast

Figure 7: "SMS v-Gateway sample Broadcast"


On the broadcast creation page, enter the settings shown in the following figures:

sms_vGateway_broadcast_settings_1

Figure 8: "SMS v-Gateway sample Broadcast" Settings 1


Enter the call back links into corresponding fields for getting delivery and reply notifications:

  • Delivery notification: wget -O /dev/null "http://www.yourdomain.com?from=[%from%]&to=[%to%]&customfield=[%customfield%]&status=DELIVERD"
  • Reply notification: wget -O /dev/null "http://www.yourdomain.com?from=[%to%]&to=[%from%]&customfield=[%customfield%]&text=[%reply_content%]&status=INCOMING"

Note: The base URL of the sample call back link is http://www.yourdomain.com.

sms_vGateway_broadcast_settings_2

Figure 9: "SMS v-Gateway sample Broadcast" Settings 2


Step 5: Start the Broadcast

Start the "SMS v-Gateway sample Broadcast" to finish the set up process. A started broadcast will be listed in the "Running" section with the status - "start" shown on it.

sms_vGateway_running_broadcast

Figure 10: Start the "SMS v-Gateway sample Broadcast"


Step 6: Send SMS through HTTP API

Now you can start sending SMS via the API. The following shows an example VGATEWAY_SEND_SMS request and response.

Request:

The values of the parameters are described as follows:

  • from: +61427575337.
  • to: +61412345678.
  • customfield: Msg12.
  • text: Hello World.
  • vgateway_id: 117. This value is the ID of the contact group you’ve created in Step 3.

Response:

<result tftype='1' infotype='0'> <field name='msg'>G117_1</field> </result>

The attributes of the response are described as follows:

  • infotype: 0. This means send success.
  • msg: G117_1. The virtual gateway ID is 117 and the recipient ID is 1.

Example call back links:

In the following examples, the base URL of the call back link is http://www.yourdomain.com, which is the URL you’ve entered in Step 4.

  • When the SMS has been received by the handset (Delivery notification):
  • When got a reply (Reply notification):

Step 7: Search SMS Histories

As mentioned above, searching SMS histories can be achieved via HTTP API or Mweb.

1) Search SMS Histories Via HTTP API

To search and view a history of the messages sent and received, issue a VGATEWAY_SEARCH_SMS request.

Request:

The values of the parameters are described as follows:

  • vgateway_id: 117.
  • io_type: outbound.
  • to: +61412345678.
  • begin_dt: 2014-10-10 12:00:00. It means 10th Oct, 2014 at 12pm.
  • end_dt: 2014-12-30 12:00:00. It means 30th Dec, 2014 at 12pm.
  • search_limit: 5.

Response:

<result tftype='1' infotype='0'> <resultset name='mcp_butalk' search_found_rows='1'> <row> <field name='id'>38960</field> <field name='from'>+61427575337</field> <field name='to'>+61412345678</field> <field name='text'>48656c6c6f20576f726c64</field> <field name='io_type'>MCPTYPE_OUT</field> <field name='status'>delivered</field> <field name='time'>2014-10-11 11:29:44</field> <field name='note'>2014-10-11 11:32:00</field> </row> </resultset> </result>

2) Search SMS Histories Via Mweb

To search and view a history of the messages sent and received through Mweb, you need to access the "Activities" page of contacts first. The easiest way to access it is to click the icon on a contact group (here, we take the "sample group" as an example) to show an option panel, and then click the "Activities" button on it.

solution_contact_group_panel

Figure 11: Access the "Activities" page


In the "Activities" page (as shown below), you can see all the activities (maximum three months history) of current contacts are listed in time descending sequence here with the "Date", "Receiver", "Messages", "Status" and "Sender" details. All the outbound messages are in black words and marked with different icons to differentiate the SMS messages and Emails, while all the inbound messages are in blue words.

contact_group_history_page

Figure 12: the "Activities" page


Click the "Search" button on the right top corner (as shown in Figure 12), to access the "Search" panel. From the "Search" panel, you can easily search the SMS history based on "Sender", "Receiver", "Time" and "Range" methods.

solution_search_panel

Figure 13: the "Search" panel

(If you require more details about the "Time" search and "Range" search, please see the "Advanced Search" in this page.)


Back to Top

Advanced Features

There are many extendable functions we can provide in the SMS v-Gateway for you to send SMS in more complicated cases. For instance, we offer "Due Date" control function to let you send out SMS at any time; we still have "Opt Out" function for your customers to choose to stop or restart receiving SMS from you. All of our products are customizable, if you are interested please contact us without any hesitate through the ways in Support.


Back to Top


Back to Top

Support

If you have any questions or need help, please contact us by:

Email: support@yvntech.com

Skype: support.yvntech


Back to Top