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: yeastardocs.example.yeastarcloud.com

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
        }
    ]
}