Hello 👋🏼 How can we help?

Search for chats

Find chats by the value of their attributes
Written by Konstantine
Updated 1 month ago

You can search for multiple chats by the value of their attributes in order to fetch exactly the ones you want.

➡️ Request

URL https://api.helpcrunch.com/v1/chats/search
Method POST
Headers Authorization: Bearer <your_api_key>

Search filters should be placed to the body of your POST request. Check a couple of examples below.

Read more about authorization header here.


Example: Search with a single filter

{
    "filter": [
        {
            "field": "chats.status",
            "operator": "=",
            "value": "3"
        }
    ],
    "limit": 5,
    "offset": 0,
    "sort": "chats.createdAt",
    "order": "DESC"
}


Example: Search with multiple filters

If you want to get chats that match all the filters, use "comparison": "AND" attribute in the body of your POST request. To fetch chats matching any of the given filters, use OR value instead.

{
    "comparison": "OR",
    "filter": [
        {
            "field": "chats.status",
            "operator": "=",
            "value": "5"
        },
        {
            "field": "chats.customer.tagsData",
            "operator": "=",
            "value": [
                {
                    "name": "Paid"
                }
            ]
        }
    ],
    "limit": 10,
    "offset": 0,
    "sort": "lastCustomerMessageAt",
    "order": "ASC"
}


Accepted searchable fields

The value you search for has to match the type, otherwise the query will fail. For example, chats.createdAt accepts a date, so the value can't be a string such as "18 Jun 2020".
Field Type Description
chats.assignee Integer The id of the agent the chat is assigned to. How to get agent id
chats.agents Integer The id of the agent who sent at least one message to the chat. How to get agent id
chats.createdAt Date (UNIX timestamp) Date and time of chat creation
chats.updatedAt Date (UNIX timestamp) Date and time of the last chat update
chats.department Integer The id of the department the chat is assigned to. How to get department id
chats.status String

Current chat status:
New - 1 
Opened - 2
Pending - 3
On-hold - 4
Closed - 5
No communication - 6
Empty - 7

chats.closedAt Date (UNIX timestamp) Date and time the chat was closed
chats.rating String Chat rating specified by a customer after the chat closure: "great", "average" or "poor"
chats.customer Integer Unique id of the customer provided by HelpCrunch
chats.customer.email String Customer email
chats.customer.tagsData Array of Strings Tags assigned to the chat, e.g. [{"name": "Lead"}, {"name": "Paid"}]
chats.customer.userId String Unique id of the customer that you can pass to HelpCrunch with User Authentication


Accepted operators

The operator should be put in as a string, for example ">"
The operator has to be compatible with the field's data type. You can't search with "<" for a string value as it works for integers and dates only.
Operator Valid Field Data Types Description
= All data types Equals
!= All data types (except arrays) Doesn't Equal
> Integer or Date (UNIX Timestamp) Greater than
< Integer or Date (UNIX Timestamp) Lower than
>= Integer or Date (UNIX Timestamp) Greater than or equal
<= Integer or Date (UNIX Timestamp) Lower than or equal
~ String Contains
!~ String Doesn't Contain


Sorting options

To specify the sorting type, you should add sort and order attributes to the body of your POST request.

    "sort": "lastCustomerMessageAt",
    "order": "ASC"

You can sort chats by the following fields:

Field Description
chats.lastCustomerMessageAt by date of the last message from customer
chats.lastMessageAt by date of the last message from agent or customer
chats.closedAt by date chats were closed

To sort chats in descending order, use DESC value. For ascending order use ASC value.

✅ Successful Response

If your request has succeeded, you'll get a 200 OK success status code together with the following response body.

{
    "data": [
        {
            "id": 5215537,
            "closedBy": null,
            "lastCustomerMessageAt": 1592962537,
            "status": "pending",
            "notes": null,
            "closedAt": null,
            "rating": null,
            "createdAt": 1592962538,
            "lastMessageAt": 1592992577,
            "snoozedUntil": null,
            "lastMessageText": "May I know how crucial is this for you?",
            "lastMessageId": 9575496,
            "lastCommunicatedAgentId": 3129,
            "agents": [],
            "customer": {
                "id": 8740723,
                "name": "Michael",
                "email": "mike.nike@hellomail.com",
                "userId": null
            },
            "assignee": {
                "id": 3129,
                "name": "Kosta",
                "email": "kosta@company.com",
                "role": "admin"
            },
            "department": null
        },
        {
            "id": 5215503,
            "closedBy": null,
            "lastCustomerMessageAt": 1592945917,
            "status": "pending",
            "notes": null,
            "closedAt": null,
            "rating": null,
            "createdAt": 1592945918,
            "lastMessageAt": 1592989608,
            "snoozedUntil": null,
            "lastMessageText": "Can you bear with us for a while? :slightly_smiling_face:",
            "lastMessageId": 9575349,
            "lastCommunicatedAgentId": 3129,
            "agents": [],
            "customer": {
                "id": 8740719,
                "name": "Laura",
                "email": "laura@mybusiness.io",
                "userId": null
            },
            "assignee": {
                "id": 3129,
                "name": "Kosta",
                "email": "kosta@company.com",
                "role": "admin"
            },
            "department": null
        },
        {
            "id": 5215590,
            "closedBy": null,
            "lastCustomerMessageAt": 1593032899,
            "status": "pending",
            "notes": null,
            "closedAt": null,
            "rating": null,
            "createdAt": 1592941965,
            "lastMessageAt": 1593032899,
            "snoozedUntil": null,
            "lastMessageText": "That would be great, thanks!",
            "lastMessageId": 9575944,
            "lastCommunicatedAgentId": 3129,
            "agents": [],
            "customer": {
                "id": 8740715,
                "name": "Emanuel",
                "email": "emanuel.kushe@example.co.uk",
                "userId": null
            },
            "assignee": {
                "id": 3129,
                "name": "Kosta",
                "email": "kosta@company.com",
                "role": "admin"
            },
            "department": null
        },
        {
            "id": 5215447,
            "closedBy": null,
            "lastCustomerMessageAt": 1592875613,
            "status": "pending",
            "notes": null,
            "closedAt": null,
            "rating": null,
            "createdAt": 1592875613,
            "lastMessageAt": 1592912137,
            "snoozedUntil": null,
            "lastMessageText": "Hi Kevin,\nThank you for reaching out. That integration is one of the most requested features.",
            "lastMessageId": 9574226,
            "lastCommunicatedAgentId": 6668,
            "agents": [],
            "customer": {
                "id": 8740684,
                "name": "Kevin",
                "email": "kevin@homealone.io",
                "userId": null
            },
            "assignee": {
                "id": 6668,
                "name": "Donald",
                "email": "donald@blabla.co",
                "role": "admin"
            },
            "department": null
        },
        {
            "id": 5215446,
            "closedBy": null,
            "lastCustomerMessageAt": 1592874288,
            "status": "pending",
            "notes": null,
            "closedAt": null,
            "rating": null,
            "createdAt": 1592874289,
            "lastMessageAt": 1592912308,
            "snoozedUntil": null,
            "lastMessageText": "Hello Borat,\nThank you for reaching out.",
            "lastMessageId": 9574409,
            "lastCommunicatedAgentId": 6668,
            "agents": [],
            "customer": {
                "id": 7831592,
                "name": "Borat",
                "email": "borat@example.com",
                "userId": null
            },
            "assignee": {
                "id": 6668,
                "name": "Donald",
                "email": "donald@blabla.co",
                "role": "admin"
            },
            "department": null
        }
    ],
    "meta": {
        "total": 2244
    }
}

You can get details on every Chat Object field in the Chat model article.

Limits

By default, this method returns only the first 100 chats. To get a different set of chats, you should use the offset and limit parameters in the body of your POST request.

    "limit": 50,
    "offset": 100,

The overall requests limit is 120 per minute


🛑 Error Responses

You may get one of the following error status codes and responses. More info on the errors is available here.

400 Bad Request

{
    "errors": [
        {
            "code": "invalid_chat_value",
            "message": "comparison"
        }
        {
            "code": "invalid_chat_value",
            "message": "Invalid chat ID"
        }
        {
            "code": "invalid_chat_value",
            "message": "customer value is invalid"
        },
        {
            "code": "invalid_chat_value",
            "message": "assignee value is invalid"
        }
        {
            "code": "invalid_value",
            "message": "status is not a valid integer"
        }
       {
            "code": "invalid_field",
            "message": "Field chats.customer.tagsDataff is invalid"
        }
        {
            "code": "invalid_operator",
            "message": "Operator ~~~~ is invalid"
        }
    ]
}

401 Unauthorized

{
    "errors": [
        {
            "code": "invalid_token",
            "message": "Invalid token"
        }
    ]
}

404 Not Found

{
    "errors": [
        {
            "code": "chat_not_found",
            "message": "Chat is missing"
        }
    ]
}

429 Too Many Requests

{
    "errors": [
        {
            "code": "too_many_requests",
            "message": "You have exceeded your requests limit"
        }
    ]
}

If you have any questions regarding the REST API, feel free to chat us any time.

👩‍💻 Happy Coding! 👨‍💻

Did this answer your question?