# Step 4: Read and tag messages

This step is optional. You can browse what was collected and tag messages, for example to mark the ones relevant to the case. Tags can later limit an export (Step 5).

## Find conversations and messages

- `GET /conversation/search` lists the case's conversations. Filter by `case` and `devices` (the device id), and page through the results.
- `GET /conversation/search-entries` lists the messages in chosen conversations (`case` and `conversation`). You can filter by date, tags, untagged messages and attachments.
- `GET /conversation/search-fuzzy` finds messages whose text matches `searchText` (3 to 100 characters).
- `POST /conversation/search-advance` finds messages matching keyword conditions.

Every conversation and message row carries its `id` (`data.data[].id`). Keep the message ids you want to tag.

> warn
> Message dates are the phone's local clock time, even though they are labelled UTC. Do not convert them to another time zone.

## Manage the case's tags

Tags belong to a case. Create them before you apply them.

- `GET /case/tags/{caseId}` lists them, each with its `id`. Keep the tag ids if you plan to limit an export by tag.
- `POST /case/tags/{caseId}` creates one. `name` is required; `severity` (`info`, `warning`, `danger`), `backgroundColor` and `textColor` are optional.
- `PATCH /case/tags/{caseId}/{tagId}` renames it or changes its colors or severity.
- `DELETE /case/tags/{caseId}/{tagId}` deletes it.

## Apply and remove tags

The tagging calls take `tagNames`: a list of tag names or tag ids.

- **One message:** `POST /conversation/entries/tags/{caseId}/{messageId}` adds tags; `DELETE` on the same path removes them. Both take `tagNames` in the body.
- **Many messages:** `POST /conversation/entries/tags/{caseId}/bulk` tags many messages at once, with `messages` (the message ids) and `tagNames`. Prefer it over one call per message; it is faster and stays well under the rate limit.
- **A whole conversation:** `PATCH /case/conversations/{caseId}/{conversationId}/tags` **replaces** the conversation's tag list. Send `caseId` and the full `tags` list you want, not just the new tag. An empty list removes every tag.
- **Counts:** `POST /conversation/{caseId}/tags-count` returns how many messages carry each tag.


## Example
List the conversations on one phone:

```sh
curl "https://api.usehearsay.com/conversation/search?case=$CASE_ID&devices=$DEVICE_ID&page=1" \
  -H "Authorization: Bearer $TOKEN" \
  -H "organization: $ORG_ID"
```

Create a tag:

```sh
curl -X POST "https://api.usehearsay.com/case/tags/$CASE_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "organization: $ORG_ID" \
  -H "Content-Type: application/json" \
  -d '{"name": "Relevant", "severity": "info"}'
```

Tag many messages at once:

```sh
curl -X POST "https://api.usehearsay.com/conversation/entries/tags/$CASE_ID/bulk" \
  -H "Authorization: Bearer $TOKEN" \
  -H "organization: $ORG_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": ["507f1f77bcf86cd799439021", "507f1f77bcf86cd799439022"],
    "tagNames": ["Relevant"]
  }'
```