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.
Figure 1: Dialog map of 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:
The "Set Up" processes include two parts: set up from Administrator Side and Client 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.
At the client side, you need to finish the following settings before you can successfully access SMS v-Gateway:
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)
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
There are two options for you to send out SMS: Send SMS Through HTTP API or Send SMS Through Mweb.
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:
Table 2: Request Parameters
For more information about the response data and examples of VGATEWAY_SEND_SMS, please visit this page.
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.
Just the same as "Send SMS", there are also two ways for you to search SMS histories: Search SMS Histories Via HTTP API or Search SMS Histories Via Mweb.
You can search and view a record of your SMS sent and received in detail via the HTTP API. The API function to be used is VGATEWAY_SEARCH_SMS. Multiple search criteria can be applied to filter your search results. If the search results have a large amount of entries, they will be split up into multiple pages. Note that detailed message history older than 2 months is automatically deleted from our servers on a continuous basis. If you need to keep your message history for longer than that period, please download and store it yourself on a regular basis.
Request parameters and their meaning:
Table 3: Request Parameters
From the search results, you'll see content of messages sent or received, mobile numbers to/from which messages were sent, status reports of messages sent, and date and time that messages were sent/received. Note: The content of messages are encoded in hexadecimal text.
For more information about the response data and examples of VGATEWAY_SEARCH_SMS, please visit this page.
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.
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:
Sign in to Mweb with your registered account on this page. In this example, the sample account is "email@example.com"; password is "ex@mple_@ccount".
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".
Figure 2: "SMS v-Gateway sample Contact Book"
The following figure shows the settings of each column:
Figure 3: Settings of each column
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".
Figure 4: "SMS v-Gateway sample Contact Group"
When creating the Contact Group, choose the "SMS v-Gateway sample Contact Book" to store it.
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.
Figure 6: Retrieve the ID of the contact group
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".
Figure 7: "SMS v-Gateway sample Broadcast"
On the broadcast creation page, enter the settings shown in the following figures:
Figure 8: "SMS v-Gateway sample Broadcast" Settings 1
Enter the call back links into corresponding fields for getting delivery and reply notifications:
Note: The base URL of the sample call back link is http://www.yourdomain.com.
Figure 9: "SMS v-Gateway sample Broadcast" Settings 2
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.
Figure 10: Start the "SMS v-Gateway sample Broadcast"
Now you can start sending SMS via the API. The following shows an example VGATEWAY_SEND_SMS request and response.
The values of the parameters are described as follows:
The attributes of the response are described as follows:
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.
As mentioned above, searching SMS histories can be achieved via HTTP API or Mweb.
To search and view a history of the messages sent and received, issue a VGATEWAY_SEARCH_SMS request.
The values of the parameters are described as follows:
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.
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.
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.
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.)
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.
If you have any questions or need help, please contact us by: