Step 4: Read and tag messages

Add MCP server to your AI tool

Allow AI tools and LLMs to interact with the API documentation portal through MCP.

MCP server URL


        
          
            https://docs.usehearsay.com/mcp

Standard setup for AI tools providing an mcp.json file

{
  "Partner APIs MCP server": {
    "url": "https://docs.usehearsay.com/mcp"
  }
}

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.

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.

List the conversations on one phone:

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:

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:

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"]
  }'