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

# Persistent conversations

> Keep one ReyGrid conversation per user with userId or conversationId.

A chat request identifies its conversation in one of two ways.

| You send | Behavior |
| - | - |
| `userId` | Used as the **persistent conversation identifier**. `conversationId` is **ignored**. |
| `conversationId` | Continues that existing conversation. |

`userId` is meant to keep a stable conversation for a user across platforms such as WhatsApp, Discord, and Telegram.

```bash theme={"system"}
curl -X POST https://reygrid.com/api/v1/agents/{AgentId}/chat \
  -H "Authorization: Bearer $REYGRID_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message": "Check my current subscription", "userId": "user_42"}'
```

Where an endpoint takes `conversationRef` (list messages, delete conversation, delete message, cancel tool call), you can pass **either** a `conversationId` **or** a persistent `userId`.

## Per-user conversations in your app

If you need your own user and conversation management, build a thin wrapper around the API. As described in the API specification, the wrapper should:

* Manage and identify users.
* Store the mapping between your `userId` and the ReyGrid `conversationId` in your database.
* Reuse the stored `conversationId` when the same user continues.
* Verify a conversation ID belongs to the expected user before using it.

ReyGrid's `userId` can also serve as the stable identifier. If you need your own mapping, keep it in your own database.

<Warning>
  As the API specification recommends, verify in your wrapper that a stored conversation ID belongs to the expected user before using it.
</Warning>

## Managing history

<CardGroup cols={2}>
  <Card title="List conversations" href="/api-reference/list-agent-conversations">Paginated, per agent.</Card>
  <Card title="List messages" href="/api-reference/list-conversation-messages">By conversationId or userId.</Card>
  <Card title="Delete a conversation" href="/api-reference/delete-a-conversation">Removes all of its messages.</Card>
  <Card title="Delete a message" href="/api-reference/delete-a-message">Optionally with `cascade=true`.</Card>
</CardGroup>


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