Hello 👋🏼 How can we help?

Get all chats

Fetch a list of all chats or a bunch of chats
Written by Konstantine
Updated 6 days ago

You can get all of your chats or a bunch of chats with this method. If you want to get just one chat by its id, use Get a single chat method instead. To find chats by the value of their attributes, use Search for chats method.

➡️ Request

URL https://api.helpcrunch.com/v1/chats?sort=chats.closedAt&order=asc
Method GET
Headers Authorization: Bearer <your_api_key>


Sorting options

To sort chats in descending order, use order=desc parameter in the query string. For ascending order use order=asc

Sorting option Description
chats.createdAt by date of chat creation
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


✅ Successful Response

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

{
    "data": [
        {
            "id": 5217453,
            "closedBy": null,
            "lastCustomerMessageAt": 1593108626,
            "status": "on hold",
            "notes": null,
            "closedAt": null,
            "rating": null,
            "createdAt": 1593108596,
            "lastMessageAt": 1593151172,
            "snoozedUntil": null,
            "lastMessageText": "Hi Mateus. My name is Lisa.\nI have an offer for you. Can we hop on a quick call this week?",
            "lastMessageId": 7758491,
            "lastCommunicatedAgentId": 6691,
            "agents": [],
            "customer": {
                "id": 9740824,
                "name": "mateus",
                "email": "mateus@example.com",
                "userId": null
            },
            "assignee": {
                "id": 6691,
                "name": "Lisa Rodes",
                "email": "lisa.rodes@company.com",
                "role": "admin"
            },
            "department": null
        },
        {
            "id": 5215634,
            "closedBy": null,
            "lastCustomerMessageAt": 1593105452,
            "status": "on hold",
            "notes": null,
            "closedAt": null,
            "rating": null,
            "createdAt": 1593105452,
            "lastMessageAt": 1593117649,
            "snoozedUntil": null,
            "lastMessageText": "Correct. The number of items is not limited. The total amount is calculated for all the items added to the cart",
            "lastMessageId": 9576638,
            "lastCommunicatedAgentId": 6699,
            "agents": [],
            "customer": {
                "id": 8740805,
                "name": "Sonya",
                "email": "sonya@company.com",
                "userId": null
            },
            "assignee": {
                "id": 6698,
                "name": "Kurt Maslow",
                "email": "kurt.maslow@company.com",
                "role": "admin"
            },
            "department": null
        },
        {
            "id": 5215633,
            "closedBy": null,
            "lastCustomerMessageAt": 1593105192,
            "status": "on hold",
            "notes": null,
            "closedAt": null,
            "rating": null,
            "createdAt": 1593105192,
            "lastMessageAt": 1593154217,
            "snoozedUntil": null,
            "lastMessageText": "Hi Caroline. My name is Ana. How can I help?",
            "lastMessageId": 9576700,
            "lastCommunicatedAgentId": 6699,
            "agents": [],
            "customer": {
                "id": 7831713,
                "name": "Caroline",
                "email": "caroline45@somemail.com",
                "userId": null
            },
            "assignee": {
                "id": 6699,
                "name": "Kurt Maslow",
                "email": "kurt.maslow@company.com",
                "role": "admin"
            },
            "department": null
        }
    ],
    "meta": {
        "total": 23905
    }
}

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

How to get all chats

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 query string of the GET request.

Default limit is 100 and it can not be bigger than that. Default offset is 0

To page through all the available chats, first, use the meta section of the JSON response to get the total number of chats.

You can request .../chats/total to get just the total number of chats
Then send subsequent requests with increasing offsets and a fixed limit until you get all the data.
 
https://api.helpcrunch.com/chats?offset=100&limit=100
https://api.helpcrunch.com/chats?offset=200&limit=100
https://api.helpcrunch.com/chats?offset=300&limit=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": "validation_error",
            "message": "limit value is invalid"
        },
        {
            "code": "validation_error",
            "message": "sort value is invalid"
        },
        {
            "code": "validation_error",
            "message": "order value is invalid"
        }
    ]
}

401 Unauthorized

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

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?