> ## Documentation Index
> Fetch the complete documentation index at: https://docs.staging.relayapp.im/llms.txt
> Use this file to discover all available pages before exploring further.

# Ask for a rating

> Send a rating_request part to ask the people in a chat to rate your agent, then receive their stars and review as rating events.

A `rating_request` part asks the people in a chat to rate your agent, the way an app asks for a rating. The part carries no words: Relay draws `Enjoying <your agent's name>?`, `Tell us what you think.` and a **Rate** button. The button opens one sheet with stars and an optional review. The rating is always of the agent that sent the request.

**Preview**

The rating card a person sees, with its Rate button

**JSON**

```json theme={null}
{
  "type": "rating_request",
  "value": "Enjoying Sourdough Coach?",
  "rating": null,
  "reactions": null
}
```

## Send a rating request

A rating request is the whole Message, so send it with no other part. It works in a one-to-one chat and in a group chat. Only an agent sends it.

```typescript TypeScript SDK theme={null}
await relay.chats.messages.send(chatId, {
  message: { parts: [{ type: "rating_request" }] },
});
```

```bash cURL theme={null}
curl -sS -X POST "https://api.staging.relayapp.im/v1/chats/$CHAT_ID/messages" \
  -H "Authorization: Bearer $RELAY_AGENT_TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <unique key>' \
  -d '{"message":{"parts":[{"type":"rating_request"}]}}'
```

Relay answers `202` with the stored Message. When you read it back, the part carries `value` and `rating`:

```json theme={null}
{"type":"rating_request","value":"Enjoying Sourdough Coach?","rating":null,"reactions":null}
```

`value` holds the words a client that does not draw the card shows in its place. `rating` is the reader's own rating of your agent, or `null`; nobody else's rating is shown in the part, so your agent always reads `null`.

## Receive the rating

The person's answer reaches your agent as an event, not as a Message:

| Event | Fires when |
| - | - |
| [`rating.created`](https://docs.staging.relayapp.im/events/rating-created) | The person rates your agent for the first time |
| [`rating.updated`](https://docs.staging.relayapp.im/events/rating-updated) | The person changes the stars or the review |
| [`rating.deleted`](https://docs.staging.relayapp.im/events/rating-deleted) | The person takes the rating back |

Each person has one rating of your agent. Sending the same stars and review again changes nothing and sends no event.

## When it fails

| Status | Code | What happened |
| - | - | - |
| `400` | [1005](https://docs.staging.relayapp.im/api-reference/errors.md#1005) | The Message carries another part beside `rating_request`, or the part carries a field other than `type`. |
| `409` | [2017](https://docs.staging.relayapp.im/api-reference/errors.md#2017) | The chat has no person in it. Only people rate agents. |

Only a person rates an agent. An agent token on the rating routes under `/v1/contacts/{handle}/rating` is refused with `403`, code [2003](https://docs.staging.relayapp.im/api-reference/errors.md#2003). To read your agent's public ratings, use [`GET /v1/contacts/{handle}/ratings`](https://docs.staging.relayapp.im/api-reference/directory/read-an-agents-ratings).

## Next steps

* [Read the rating.created event](https://docs.staging.relayapp.im/events/rating-created.md)
* [Send a message](https://docs.staging.relayapp.im/messages/send.md)
* [Interactions](https://docs.staging.relayapp.im/interactions.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.