Search Specific Message Sessions

Search specific message sessions of a specific entity, such as an extension user or a third-party message analytics platform.

Request URL

GET {base_url}/{api_path}/message_session/search?access_token={access_token}

Request parameters

Parameter	Required	Type	Description
page_size	Yes	Integer	Define how many records per page.
user_type	Yes	Integer	The type of the entity. Valid value: 1: Extension user. 9: Third-party message analytics platform.
user_no	No	String	The identifier of the entity. Valid value: If user_type is set to 1, this parameter is REQUIRED and is used to specify the specific extension number. If user_type is set to 9, set this parameter to api or leave it blank.
collection	No	String	The collection of the message session. Valid value: all: All sessions (both campaign and non-campaign message sessions). campaign: Only campaign sessions. Note: If omitted or left blank, only non-campaign message sessions will be returned.
first_msg_id	No	Integer	The ID of the first message to retrieve. Note: This parameter is used for pagination. To retrieve the next page, set this parameter to the last_msg_id of the last message session returned in the previous query response.
is_archived	No	Integer	Filter sessions by archive status. Valid value: 0: Only unarchived sessions. 1: Only archived sessions. 2: All sessions (both archived and unarchived).
is_closed	No	Integer	Filter sessions by closed status. Valid value: 0: Only open sessions. 1: Only closed sessions. 2: All sessions (both open and closed).
is_pickup	No	Integer	Filter sessions by pickup status. Valid value: 0: All sessions. 1: Only picked-up sessions. 2: Only not picked-up sessions.
search_value	No	String	Search keyword.

Response parameters

Parameter	Type	Description
errcode	Integer	Returned error code. 0: Succeed. Non-zero value: Failed. Note: You can check the error code and error message in Error Code and Error Message.
errmsg	String	Returned message. SUCCESS: Succeed. FAILURE: Failed.
list	Array<Session_Info>	The information of the message sessions.

Session_Info

Parameter	Type	Description
id	Integer	The unique ID of the message session.
type	String	The type of the message session. sms whatsapp facebook livechat
is_close	Integer	Whether the message session is closed. 0: Not closed. 1: Closed.
is_archived	Integer	Whether the message session is archived. 0: Unarchived. 1: Archived.
to	Object<Customer_Info>	The information about the external customer in the message session.
expire	Integer	The remaining time (in seconds) before the 24-hour timeout after receiving an external inbound message. Note: This parameter only returns value for WhatsApp and Facebook session. -1: Never expires. 0: Already expired. Any value greater than 0: The number of seconds remaining before expiration.
did_number	String	The DID number used in the message session.
origin	String	The origin of the message session. campaign: The session is initiated by a message campaign. Note: If returned empty, it indicates that the session is initiated by an extension user or a third-party message analytics platform (via API).
collection	String	The collection of the session. campaign: Campaign session. Note: If returned empty, it indicates that the session is not a campaign session.
last_msg_id	Integer	The ID of the last message for the message session.
queue_id	Integer	The ID of the message queue handling messages for this session.
pickup_member_id	Integer	The ID of the agent who picked up the session from the message queue. Note: If queue_id is present and this value returns 0, it indicates that the session is still in the queue and has not been picked up.

Customer_Info

Parameter	Type	Description
user_id	Integer	The ID of the internal user in the session. Note: This parameter always returns 0.
user_no	String	The ID or phone number of the external customer.
user_type	Integer	The type of the external customer. 2: SMS user. 3: WhatsApp user. 4: Facebook user. 5: Live Chat user. 8: Message Campaign recipient.
avatar	String	The ID of the customer's avatar.
username	String	User name of the customer.

Examples

Request example

Search a session of extension 59996 using the customer's Facebook ID.

GET /openapi/v1.0/message_session/search?access_token=6Un1hR5FL8L2sP5IlM43ynnemjseR7EO&page_size=10&user_type=1&user_no=59996&search_value=24982205021378108 HTTP/1.1
Host: 192.168.5.150:8088

Response example

HTTP/1.1 200 OK
{
    "errcode": 0,
    "errmsg": "SUCCESS",
    "list": [
        {
            "id": 3069,
            "type": "facebook",
            "is_close": 0,
            "is_archived": 0,
            "to": {
                "user_id": 0,
                "user_no": "24982205021378108",
                "user_type": 4,
                "avatar": "ICPiaN3BIrvKHTJkl1snmhh9H4ZcbQYTdz8OTBOVN_4",
                "username": "William Smith"
            },
            "expire": 19751,
            "did_number": "197745966764205",
            "origin": "",
            "collection": "",
            "last_msg_id": 10253,
            "queue_id": 0,
            "pickup_member_id": 0
        }
    ]
}