MAPI Manual

NAME

VGATEWAY_SEARCH_SMS

FUNCTION

Search SMS histories with multiple filters enabled

SYNOPSIS

action, vgateway_id, from, to, begin_dt, end_dt, io_type, search_limit, login_name, login_passwd

DESCRIPTION

This function allows you to search outbound and inbound SMS via the virtual gateway. It searches through the entire SMS histories. Multiple search criteria can be applied to filter your search results.


Required Parameters

* action: VGATEWAY_SEARCH_SMS.

* vgateway_id: ID of the virtual gateway. It searches all the outbound and inbound SMS that are associated with this virtual gateway ID.

* login_name: your login name.
* login_passwd: your password.


Optional Parameters

* from: sender number. It searches the SMS sent from this number. 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. It searches the SMS that were sent to this destination number. Number format is country code + mobile number, e.g., +61412345678. Note: Use "+" before the country code. Must be URL encoded.

* begin_dt: the beginning of time interval. This field together with "end_dt" are used to filter search results based on the date and time the SMS was sent/received. SMS whose timestamp is greater than or equal to the begin_dt and less than the end_dt will be returned. The date and time format is YYYY-MM-DD HH:MM:SS. Must be URL encoded.

* end_dt: the end of time interval. This field together with "begin_dt" are used to filter results based on the date and time the SMS was sent/received. SMS whose timestamp is greater than or equal to the begin_dt and less than the end_dt will be returned. The date and time format is YYYY-MM-DD HH:MM:SS. Must be URL encoded.

* io_type: specifies whether SMS is inbound or outbound. Available types are listed as follows (case-insensitive), and default is returning both of these types.: 

  • "inbound" or "incoming",
  • "outbound" or "outgoing".

search_limit: constrains the number of search results that are returned. It can also be used for pagination of search results. Value is a number or two numbers split by a comma. With one number, the value specifies the maximum number of results to return from the beginning of the search results. With two numbers, the first number specifies the offset of the first result to return, and the second specifies the maximum number of results to return. Note: The offset of the first result is 0 (not 1).  E.g., if value is "5", the first five search results will be returned; if value is "20,5", it will return maximum five results starting from the 21st result. Default value is 100.

RETURN DATA

The HTTP response body is represented in XML. It contains the following attributes:

* infotype: request status code. "0" means success; "1" means failure.

* search_found_rows: the total number of results found.

* id: message ID.

* from: originated mobile number, where the message was sent from.

* to: destination mobile number, where the message was sent to.

* text: the SMS content encoded in hexadecimal text.

* io_type: specifies whether the message was inbound or outbound. Below is a list of the types:

  • "MCPTYPE_IN": inbound message,
  • "MCPTYPE_OUT": outbound message.

* status: specifies the status of the message. Below is a list of the statuses:

  • "delivered": the outbound SMS has been received by the recipient,
  • "received": the inbound SMS has been successfully received.

* time: the date and time the message was sent or received.

* note: a note about the message.

ROLE PERMITTED

Manager

EXAMPLES

Request:

http://app02.yvntech.com/MapIHttpS/MapIS?action=VGATEWAY_SEARCH_SMS&vgateway_id=184&io_type=outbound&begin_dt=2014-10-09%2012%3A00%3A00&end_dt=2014-10-11%2012%3A00%3A00&login_name=user@example.com&login_passwd=1111

This request searches outbound SMS which are associated with the virtual gateway ID "184" and sent between "2014-10-09 12:00:00" and "2014-10-11 12:00:00".


Response:

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




Request:

http://app02.yvntech.com/MapIHttpS/MapIS?action=VGATEWAY_SEARCH_SMS&vgateway_id=184&to=%2B61412345678&search_limit=2&login_name=user@example.com&login_passwd=1111

This request searches SMS which are associated with the virtual gateway ID "184" and sent to the mobile number "+61412345678". It returns 2 results found at maximum.

TIPS

ENVIRONMENT

AUTHOR

YVN Tech

SEE ALSO

VGATEWAY_SEND_SMS

Mweb v2.0 YVNTECH 2014