MAPI Manual

NAME

LIST_CONTACTGROUP_TALKS

FUNCTION

List talks of a contact group

SYNOPSIS

contactgroup_id, contact_id, bu_type, related_id, io_type, from, to,  time_from, time_to, order_type, search_limit

DESCRIPTION

This function allows users to list the talks of a contact group, which includes the inbound and outbound messages to/from this contact group. Multiple search criteria can be applied to filter your list results.

Required Parameters

* action: LIST_CONTACTGROUP_TALKS.

* contactgroup_id: ID of the contact group.


Optional Parameters

* contact_id: ID of the contact. It'll list talks only for this contact.

* bu_type: type of the business unit. Available types are given below:

  • MCPTYPE_BROADCAST,
  • MCPTYPE_SERVICE,
  • MCPTYPE_AGILE.

* related_id: ID of the business that is associated with the contact, which is the broadcast ID or service ID or agile ID.

* io_type: specifies the type of messages to be listed. Available values are given below:

  • MCPTYPE_IN: inbound messages.
  • MCPTYPE_OUT: outbound messages.

* from: sender number. It searches messages 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 messages 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.

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

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

* order_type: specifies the list order of the results. Value is either "DESC" or "ASC", which means in descending or ascending order respectively.

* 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 response contains the following attributes:

* mcp_talk_id: talk ID.

* mcp_channeltype_id: channel type.

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

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

* contactbook_id: ID of the contact book.

* contact_id: ID of the contact.

* contact_name: name of the contact.

* content: the message content encoded in hexadecimal text.

* task_io: 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 message has been received by the recipient,
  • "finish_success": the inbound message has been successfully received.

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

* note: a note about the message.

ROLE PERMITTED

Manager

EXAMPLES

The following example shows a successful HTTP GET request and response.

Request:

http://app02.yvntech.com/MapIHttpS/MapIS?action=LIST_CONTACTGROUP_TALKS&contactgroup_id=184&bu_type=MCPTYPE_BROADCAST&related_id=913&login_name=user@example.com&login_passwd=1111


Response:

<result tftype='1' infotype='0'>
    <resultset name='mcp_butalk' search_found_rows='2'>
        <row>
            <field name='mcp_talk_id'>38972</field>
            <field name='mcp_channeltype_id'>sms</field>
            <field name='sender'></field>
            <field name='recipient'>+61412345678</field>
            <field name='contactbook_id'>1</field>
            <field name='contact_id'>1168</field>
            <field name='contact_name'>steven</field>
            <field name='content'>5468616E6B7320666F7220726174696E6720322C332C342E</field>
            <field name='task_io'>MCPTYPE_OUT</field>
            <field name='status'>delivered</field>
            <field name='talk_dt'>2014-10-10 15:24:26</field>
            <field name='note'>2014-10-10 15:26:00</field>
        </row>
        <row>
            <field name='mcp_talk_id'>38966</field>
            <field name='mcp_channeltype_id'>sms</field>
            <field name='sender'></field>
            <field name='recipient'>+61412345678</field>
            <field name='contactbook_id'>1</field>
            <field name='contact_id'>1168</field>
            <field name='contact_name'>steven</field>
            <field name='content'>4869206A6F686E2C20706C656173652072617465206F757220736572766963652E</field>
            <field name='task_io'>MCPTYPE_OUT</field>
            <field name='status'>delivered</field>
            <field name='talk_dt'>2014-10-10 13:24:36</field>
            <field name='note'>2014-10-10 13:32:00</field>
        </row>
    </resultset>
</result>

TIPS

To list all the inbound and outbound messages of a contact group within a broadcast, provide the following parameters:

  • contactgroup_id,
  • bu_type,
  • related_id.

ENVIRONMENT

AUTHOR

YVN Tech

SEE ALSO

LIST_BROADCAST_TALKS, LIST_BROADCAST_LATESTTALKS_GROUPBYCONTACT

Mweb v2.0 YVNTECH 2014