MAPI Manual

NAME

VGATEWAY_SEND_SMS

FUNCTION

Send out SMS and receive replies with delivery notification enabled

SYNOPSIS

action, from, to, text, vgateway_id, customfield, login_name, login_passwd

DESCRIPTION

This function allows you to send out SMS to a recipient and receive replies. Delivery receipts notification is enabled. Notifications and incoming SMS can be pushed to your server via the URL you specified.

Required Parameters
* action: VGATEWAY_SEND_SMS.
* from: sender number that the message will appear from. We provide several available sender numbers and you can choose any of these numbers. Number format is country code + mobile number, e.g., +61412345678. Note: Use "+" before the country code. Must be URL encoded.
* to: mobile number of the recipient that the message will be sent to. Number format is country code + mobile number, e.g., +61412345678. Note: Use "+" before the country code. Must be URL encoded.
* text: message to be sent. This value must be URL encoded.
* vgateway_id: ID of the virtual gateway that the recipient will be added to.
* customfield: custom field which you can store an ID that will be returned to you with delivery notification or with any reply to this outgoing SMS.
* login_name: your login name.
* login_passwd: your password.
 

RETURN DATA

HTTP Response

The HTTP response contains the following:

* infotype: request status code. "0" means success; "1" means failure.
* msg: a string including the virtual gateway ID and the recipient ID which are concatenated with an underscore.


Delivery Notification of the SMS and Reply

Notifications will be returned to users based on different statuses. The notification will be pushed to your server via the URL you specified which includes the status parameter.

Below is a table of available status values:

 Parameter

 Value

Description

 

 

 status

 

DELIVERD

 

The message has been received by the handset.

 

INCOMING

 

This is an incoming message.


Incoming SMS HTTP Call Back

The incoming SMS will be pushed to your server via the URL you specified so that you can record these messages in your system and process them.

Below is a list of parameters that are added to the URL when the URL is called back:

* to: destination mobile number, where the message was sent to.
* from: originated mobile number, where the message was sent from.
* text: incoming message content.
* customfield: unique custom field passed in the original request.

ROLE PERMITTED

Manager

EXAMPLES

The following shows an example HTTP request and response.

Request:

http://app02.yvntech.com/MapIHttpS/MapIS?action=VGATEWAY_SEND_SMS&from=%2B61427575337&to=%2B61412345678&customfield=Msg1&text=Hi%20demo%20message&vgateway_id=3&login_name=user@example.com&login_passwd=1111

The values of the parameters are described as follows:

  • from: sender number after URL encoding. You can choose any of the sender numbers which are provided by us.
  • to: recipient number after URL encoding.
  • customfield: an unique identifier specified by you.
  • text: the message content after URL encoding,
  • vgateway_id: the virtual gateway ID which is provided by us. This ID can be changed.

Response:

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


The attributes are described as follows:

  • infotype: "0" means success.
  • msg: contains virtual gateway ID and recipient ID. Virtual gateway ID: 3 ; recipient ID: 54.




Example call back links:

In the following examples, the base URL of the call back links is www.yourdomain.com.


When the message has been received by the handset:

http://www.yourdomain.com?from=%2B61427575337&to=%2B61412345678&customfield=Msg1&status=DELIVERD

Below is a description of the parameters added to the link:

  • from: the sender's number.
  • to: the recipient's number
  • customfield: the custom field associated with the message.
  • status: "DELIVERD" means the message has been received by the recipient.


When got a reply:

http://www.yourdomain.com?from=%2B61412345678&to=%2B61427575337&customfield=Msg1&text=This%20is%20a%20reply&status=INCOMING


Below is a description of the parameters added to the link:

  • from: the sender's number of the incoming message.
  • to: the destination number of the incoming message.
  • customfield: the custom field that the incoming message is associated with.
  • text: the incoming message content.
  • status: "INCOMING" indicates this is an incoming message.

TIPS

We provide several sender numbers and you can choose any of these numbers to send SMS.

ENVIRONMENT

AUTHOR

YVN Tech

SEE ALSO

VGATEWAY_SEARCH_SMS

Mweb v2.0 YVNTECH 2014