---
title: "Search WhatsApp messages"
method: POST
path: "/api/v1/tools/search_messages"
---

# Search WhatsApp messages

`POST /api/v1/tools/search_messages`

## Request

- Base URL: `https://whatsync.app`
- URL: `https://whatsync.app/api/v1/tools/search_messages`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-API-Key`

Search stored WhatsApp message text, attachment filenames, and contact names. Pass a known conversation_id as conversationId, and date filters when known. Searches default to 180 days and each requested date window is limited to 366 days.

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `query` string, required: Words or phrase to search for
  - `conversationId` string: A conversation_id returned by another WhatSync tool, to limit the search to one conversation
  - `direction` 'inbound' | 'outbound': Limit matches by message direction
  - `after` string, date-time: Search messages at or after this ISO timestamp
  - `before` string, date-time: Search messages before this ISO timestamp
  - `cursor` string: Opaque next_cursor returned by the previous page
  - `limit` integer: Number of matches to return; defaults to 20

## Response `200`

JSON result. Every response includes X-Request-Id.

- object

## Other responses

- `400`: API error
- `401`: API error
- `403`: API error
- `404`: API error
- `409`: API error
- `413`: API error
- `415`: API error
- `422`: API error
- `429`: API error
- `503`: API error

---

[API](https://skmtc.dev/whatsync/apis/whatsync-api.md) · [All operations](https://skmtc.dev/whatsync/apis/whatsync-api/llms.txt) · [OpenAPI document](https://skmtc.dev/whatsync/apis/whatsync-api/revisions/6fa5498b63b7?raw)