Rate chat

Rate closed chats using the API
Written by Konstantine
Updated 2 weeks ago

Chats can be rated not only by customers in the chat widget but also with help of rest API requests. Read more about chat rating

➡️ Request

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

Read more about authorization header here.

You should specify chat id (required) and rating (required) in the body of your PUT request.

{
    "id": 5208,
    "rating": "poor"
}
Chat rating can only be sent via the API if the chat status "Closed" and the rating has not yet been sent. Additionally, there must be at least one message from the agent in the chat. Otherwise, one of the following errors will be displayed: 1; 2; 3

id is the identifier for the chat as given by HelpCrunch.
rating
reflects the quality of the chat and can be one of the following: perfectgreat, average, poor or very poor.

These internal rating names correspond to these ratings in the chat:

  • 😃 Excellent
  • 🙂 Good
  • 😐 Average
  • 😕 Poor
  • 😔 Very poor

✅ Successful Response

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

{
  "id": 542335,
  "closedBy": "string",
  "lastCustomerMessageAt": "1603885746",
  "status": "new",
  "closedAt": "1603885746",
  "rating": "perfect",
  "createdAt": "1603885746",
  "lastMessageAt": "1603885746",
  "createdWith": "string",
  "snoozedUntil": "1603885746",
  "lastMessageText": "string",
  "lastMessageId": 542335,
  "applicationId": 542335,
  "lastCommunicatedAgentId": 542335,
  "agents": [
    {
      "id": 542335,
      "name": "string",
      "email": "string",
      "role": "string"
    }
  ],
  "customer": {
    "id": 542335,
    "name": "string",
    "email": "string",
    "userId": "string"
  },
  "assignee": {
    "id": 542335,
    "name": "string",
    "email": "string",
    "role": "string"
  },
  "department": {
    "id": 542335,
    "name": "string"
  }
}

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

This is an example of chat rating displayed in the HelpCrunch inbox:

🛑 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_request",
            "message": "Chat must me closed to rate"
        }
    ]
}

400 Bad Request

{
    "errors": [
        {
            "code": "invalid_rating_value",
            "message": "The value you selected is not a valid choice. Valid rating: 'perfect', 'great', 'average', 'poor', 'very poor'"
        }
    ]
}

401 Unauthorized

{
  "errors": [
    {
      "code": "invalid_request",
      "message": "Invalid request"
    },
    {
      "code": "unauthorized",
      "message": "Unauthorized"
    }
  ]
}

409 Conflict

{
  "errors": [
    {
      "code": "invalid_request",
      "message": "Invalid request"
    },
    {
      "code": "conflict",
      "message": "Chat is already rated"
    }
  ]
}

409 Conflict

{
  "errors": [
    {
      "code": "invalid_request",
      "message": "Invalid request"
    },
    {
      "code": "conflict",
      "message": "Cannot rate chat without agent communication"
    }
  ]
}

429 Too Many Requests

{
  "errors": [
    {
      "code": "invalid_request",
      "message": "Invalid request"
    },
    {
      "code": "too_many_requests",
      "message": "Too many requests"
    }
  ]
}

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

👩‍💻 Happy Coding! 👨‍💻

Did this answer your question?