---
updatedAt: 2026-10-29T22:20:50.000Z
agentTools:
  projectIndex: https://docs.whippy.ai/llms.txt
---

# Search Conversations

Search conversations in an organization.

Conversations with no last_message_date will be excluded as they're regarded as empty.

The default offset is 0 and the default limit is 50.
The max limit is 500.


# OpenAPI definition

```json
{
  "components": {
    "schemas": {
      "NotAuthenticatedErrorResponse": {
        "description": "Not Authenticated Error Response schema",
        "example": {
          "errors": [
            {
              "description": "Not authenticated"
            }
          ],
          "status": 401
        },
        "properties": {
          "errors": {
            "description": "Not authenticated error",
            "items": {
              "properties": {
                "description": {
                  "enum": [
                    "Not authenticated"
                  ],
                  "type": "string",
                  "x-struct": null,
                  "x-validate": null
                }
              },
              "type": "object",
              "x-struct": null,
              "x-validate": null
            },
            "type": "array",
            "x-struct": null,
            "x-validate": null
          },
          "status": {
            "enum": [
              401
            ],
            "type": "integer",
            "x-struct": null,
            "x-validate": null
          }
        },
        "title": "NotAuthenticatedErrorResponse",
        "type": "object",
        "x-struct": "Elixir.DashboardApiWeb.Public.V1.Documentation.Errors.NotAuthenticated",
        "x-validate": null
      },
      "ListConversationsResponse": {
        "description": "Response schema for listing conversations.",
        "example": {
          "data": [
            {
              "assigned_team_id": "0003c6fe-e469-4e59-8a73-be8ce58f6d53",
              "assigned_user_id": 1,
              "channel_id": "f09eada1-916f-4643-a729-fc1f6621b77b",
              "channel_type": "phone",
              "contact_id": "753757ac-4a73-4d42-9968-795c3704637c",
              "created_at": "2021-06-22T07:45:45",
              "id": "70c5c186-107e-4122-ba5c-24ac072f5898",
              "last_message_date": "2021-06-22T07:45:45",
              "status": "open",
              "unread_count": 3,
              "updated_at": "2021-06-22T07:45:45"
            },
            {
              "assigned_team_id": "0003c6fe-e469-4e59-8a73-be8ce58f6d53",
              "assigned_user_id": 1,
              "channel_id": "bf4e1079-31c0-4728-a4e1-2c761c400c2b",
              "channel_type": "phone",
              "contact_id": "8ba031d8-35c6-4bc2-a1fa-6d45b23b6956",
              "created_at": "2021-06-22T07:45:45",
              "id": "0ba4f325-6488-4d14-b926-49deb743881a",
              "last_message_date": "2021-06-22T07:45:45",
              "status": "open",
              "unread_count": 3,
              "updated_at": "2021-06-22T07:45:45"
            }
          ],
          "total": 2
        },
        "properties": {
          "data": {
            "description": "List of conversations",
            "items": {
              "description": "Single conversation data",
              "properties": {
                "assigned_team_id": {
                  "description": "ID of the team assigned to the conversation",
                  "format": "uuid",
                  "type": "string",
                  "x-struct": null,
                  "x-validate": null
                },
                "assigned_user_id": {
                  "description": "ID of the user assigned to the conversation",
                  "type": "integer",
                  "x-struct": null,
                  "x-validate": null
                },
                "channel_id": {
                  "description": "ID of the channel the conversation belongs to",
                  "format": "uuid",
                  "type": "string",
                  "x-struct": null,
                  "x-validate": null
                },
                "channel_type": {
                  "description": "Type of channel for the conversation",
                  "enum": [
                    "phone",
                    "email"
                  ],
                  "type": "string",
                  "x-struct": null,
                  "x-validate": null
                },
                "contact_id": {
                  "description": "ID of the contact in the conversation",
                  "format": "uuid",
                  "type": "string",
                  "x-struct": null,
                  "x-validate": null
                },
                "created_at": {
                  "description": "Date the conversation is created at in ISO 8601 format",
                  "format": "date-time",
                  "type": "string",
                  "x-struct": null,
                  "x-validate": null
                },
                "id": {
                  "description": "Conversation ID",
                  "format": "uuid",
                  "type": "string",
                  "x-struct": null,
                  "x-validate": null
                },
                "last_message_date": {
                  "description": "Date of the last message belonging to the conversation",
                  "format": "date-time",
                  "type": "string",
                  "x-struct": null,
                  "x-validate": null
                },
                "status": {
                  "description": "Status of the conversation",
                  "enum": [
                    "open",
                    "closed",
                    "automated",
                    "spam"
                  ],
                  "type": "string",
                  "x-struct": null,
                  "x-validate": null
                },
                "unread_count": {
                  "description": "Number of unread messages in the conversation",
                  "type": "integer",
                  "x-struct": null,
                  "x-validate": null
                },
                "updated_at": {
                  "description": "Date the conversation was last updated at",
                  "format": "date-time",
                  "type": "string",
                  "x-struct": null,
                  "x-validate": null
                }
              },
              "type": "object",
              "x-struct": null,
              "x-validate": null
            },
            "type": "array",
            "x-struct": null,
            "x-validate": null
          },
          "total": {
            "description": "Total count of conversations without limit and offset",
            "type": "integer",
            "x-struct": null,
            "x-validate": null
          }
        },
        "title": "ListConversationsResponse",
        "type": "object",
        "x-struct": null,
        "x-validate": null
      },
      "SearchConversationsParams": {
        "description": "Parameters for searching and filtering conversations.",
        "example": {
          "assigned_users": [
            "1",
            "7"
          ],
          "channels": [
            {
              "id": "05c192fe-001b-4b16-a1e7-e87641f552e8"
            },
            {
              "phone": "+14155552671"
            }
          ],
          "contacts": [
            {
              "id": "8e010c80-fe11-4e88-8b0b-ab952573449c"
            },
            {
              "phone": "+14155552681"
            },
            {
              "email": "brucewayne@example.com"
            },
            {
              "name": "Bruce Wayne"
            }
          ],
          "last_message_date": {
            "after": "2025-03-01T10:00:00Z",
            "before": "2025-02-27T10:00:00Z"
          },
          "limit": 50,
          "offset": 0,
          "sort": {
            "column": "waiting_since",
            "order": "desc"
          },
          "status": [
            "open",
            "automated"
          ],
          "type": [
            "phone"
          ]
        },
        "properties": {
          "assigned_users": {
            "description": "IDs of users that are assigned to conversations",
            "example": [
              "1",
              "7",
              "10"
            ],
            "items": {
              "description": "Assigned User ID",
              "example": "1",
              "type": "string",
              "x-struct": null,
              "x-validate": null
            },
            "type": "array",
            "x-struct": null,
            "x-validate": null
          },
          "channels": {
            "description": "Filter by channels",
            "example": [
              {
                "id": "273d9764-ce63-40b4-99a4-38647f3d3322"
              },
              {
                "phone": "+14155552672"
              }
            ],
            "items": {
              "properties": {
                "id": {
                  "description": "Channel ID",
                  "example": "7b9eff2b-4d60-480f-acb5-caa090779498",
                  "format": "uuid",
                  "type": "string",
                  "x-struct": null,
                  "x-validate": null
                },
                "phone": {
                  "description": "Channel phone",
                  "example": "+14155552671",
                  "type": "string",
                  "x-struct": null,
                  "x-validate": null
                }
              },
              "type": "object",
              "x-struct": null,
              "x-validate": null
            },
            "type": "array",
            "x-struct": null,
            "x-validate": null
          },
          "contacts": {
            "description": "Filter by contacts",
            "example": [
              {
                "id": "36792ca8-a076-43c3-a37a-c9a0a45b633e"
              },
              {
                "phone": "+14155552681"
              },
              {
                "email": "brucewayne@example.com"
              },
              {
                "name": "Bruce Wayne"
              }
            ],
            "items": {
              "properties": {
                "email": {
                  "description": "Contact email",
                  "example": "brucewayne@example.com",
                  "format": "email",
                  "type": "string",
                  "x-struct": null,
                  "x-validate": null
                },
                "id": {
                  "description": "Contact ID",
                  "example": "cf2029f0-96c5-4ff2-8bf6-fadf1227c876",
                  "format": "uuid",
                  "type": "string",
                  "x-struct": null,
                  "x-validate": null
                },
                "name": {
                  "description": "Contact name",
                  "example": "Bruce Wayne",
                  "type": "string",
                  "x-struct": null,
                  "x-validate": null
                },
                "phone": {
                  "description": "Contact phone",
                  "example": "+14155552681",
                  "type": "string",
                  "x-struct": null,
                  "x-validate": null
                }
              },
              "type": "object",
              "x-struct": null,
              "x-validate": null
            },
            "type": "array",
            "x-struct": null,
            "x-validate": null
          },
          "created_at": {
            "description": "Created At Date in ISO 8601",
            "example": {
              "after": "2025-03-01T10:00:00Z",
              "before": "2025-02-27T10:00:00Z"
            },
            "properties": {
              "after": {
                "example": "2025-03-01T10:00:00Z",
                "format": "date-time",
                "type": "string",
                "x-struct": null,
                "x-validate": null
              },
              "before": {
                "example": "2025-02-27T10:00:00Z",
                "format": "date-time",
                "type": "string",
                "x-struct": null,
                "x-validate": null
              }
            },
            "type": "object",
            "x-struct": null,
            "x-validate": null
          },
          "last_message_date": {
            "description": "Last Message Date in ISO 8601",
            "example": {
              "after": "2025-03-01T10:00:00Z",
              "before": "2025-02-27T10:00:00Z"
            },
            "properties": {
              "after": {
                "example": "2025-03-01T10:00:00Z",
                "format": "date-time",
                "type": "string",
                "x-struct": null,
                "x-validate": null
              },
              "before": {
                "example": "2025-02-27T10:00:00Z",
                "format": "date-time",
                "type": "string",
                "x-struct": null,
                "x-validate": null
              }
            },
            "type": "object",
            "x-struct": null,
            "x-validate": null
          },
          "limit": {
            "description": "Number of results to return",
            "example": 50,
            "type": "integer",
            "x-struct": null,
            "x-validate": null
          },
          "offset": {
            "description": "Number of results to skip",
            "example": 0,
            "type": "integer",
            "x-struct": null,
            "x-validate": null
          },
          "sort": {
            "description": "Sorting options",
            "example": {
              "column": "waiting_since",
              "order": "desc"
            },
            "properties": {
              "column": {
                "enum": [
                  "last_message_timestamp",
                  "waiting_since"
                ],
                "example": "waiting_since",
                "type": "string",
                "x-struct": null,
                "x-validate": null
              },
              "order": {
                "enum": [
                  "asc",
                  "desc"
                ],
                "example": "desc",
                "type": "string",
                "x-struct": null,
                "x-validate": null
              }
            },
            "type": "object",
            "x-struct": null,
            "x-validate": null
          },
          "status": {
            "description": "Statuses list",
            "example": [
              "open",
              "automated"
            ],
            "items": {
              "description": "Conversation status",
              "enum": [
                "open",
                "closed",
                "spam",
                "automated"
              ],
              "type": "string",
              "x-struct": null,
              "x-validate": null
            },
            "type": "array",
            "x-struct": null,
            "x-validate": null
          },
          "type": {
            "description": "Filter by conversation `channel_type`. Same as `type[]` on list conversations: pass one or more values in a list.",
            "example": [
              "phone"
            ],
            "items": {
              "enum": [
                "phone",
                "email",
                "fax"
              ],
              "type": "string",
              "x-struct": null,
              "x-validate": null
            },
            "type": "array",
            "x-struct": null,
            "x-validate": null
          },
          "unread_count": {
            "description": "Filter by unread count",
            "example": 10,
            "type": "integer",
            "x-struct": null,
            "x-validate": null
          },
          "updated_at": {
            "description": "Updated At Date in ISO 8601",
            "example": {
              "after": "2025-03-01T10:00:00Z",
              "before": "2025-02-27T10:00:00Z"
            },
            "properties": {
              "after": {
                "example": "2025-03-01T10:00:00Z",
                "format": "date-time",
                "type": "string",
                "x-struct": null,
                "x-validate": null
              },
              "before": {
                "example": "2025-02-27T10:00:00Z",
                "format": "date-time",
                "type": "string",
                "x-struct": null,
                "x-validate": null
              }
            },
            "type": "object",
            "x-struct": null,
            "x-validate": null
          }
        },
        "title": "SearchConversationsParams",
        "type": "object",
        "x-struct": null,
        "x-validate": null
      }
    },
    "securitySchemes": {
      "authorization": {
        "in": "header",
        "name": "X-WHIPPY-KEY",
        "type": "apiKey"
      },
      "bearer": {
        "description": "OAuth Access token",
        "scheme": "bearer",
        "type": "http"
      }
    }
  },
  "info": {
    "description": "Communication Platform endpoints in the Whippy public API.\n\n## Authentication\n\nThe Whippy Public API supports two authentication methods:\n\n**API Key** — Generate an organization API token and send it with every request as the `X-WHIPPY-KEY` header.\n\n**OAuth Bearer Token** — Obtain an access token via the OAuth authorization flow and send it as a Bearer token in the `Authorization` header (e.g. `Authorization: Bearer <access_token>`).\n\n## Rate Limiting\n\nThe Whippy API is rate limited. Different endpoints have different rate limits.\nEach request to the API will return the following headers, which can be used to keep track of your rate limit status:\n * `x-ratelimit-max`: The maximum number of requests that the consumer is permitted to make in the given time period.\n * `x-ratelimit-remaining`: The number of requests remaining in the current rate limit window.\n * `x-ratelimit-interval-milliseconds`: The rate limit window in milliseconds.\n * `x-ratelimit-remaining-interval-milliseconds`: The time in milliseconds until the rate limit window resets.\n",
    "title": "Communication Platform",
    "version": "1.0"
  },
  "openapi": "3.0.0",
  "paths": {
    "/v1/conversations/search": {
      "post": {
        "callbacks": {},
        "deprecated": false,
        "description": "Search conversations in an organization.\n\nConversations with no last_message_date will be excluded as they're regarded as empty.\n\nThe default offset is 0 and the default limit is 50.\nThe max limit is 500.\n",
        "operationId": "searchConversations",
        "parameters": [],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SearchConversationsParams"
              }
            }
          },
          "description": "Search Conversation Params",
          "required": false
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ListConversationsResponse"
                }
              }
            },
            "description": "Conversations"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NotAuthenticatedErrorResponse"
                }
              }
            },
            "description": "Not Authenticated"
          }
        },
        "security": [
          {},
          {
            "authorization": []
          },
          {
            "bearer": []
          }
        ],
        "summary": "Search Conversations",
        "tags": [
          "Conversations"
        ]
      }
    }
  },
  "security": [],
  "servers": [
    {
      "url": "https://api.whippy.co",
      "variables": {}
    }
  ],
  "tags": [
    {
      "name": "Conversations"
    }
  ],
  "x-readme": {
    "apply-endpoint-order": true,
    "apply-tag-changes": true
  }
}
```

# Sibling pages

* [List Conversations](https://docs.whippy.ai/reference/getconversations.md)
* [Import Conversations](https://docs.whippy.ai/reference/uploadconversation.md)
* [Show Conversation](https://docs.whippy.ai/reference/getconversation.md)
* [Update Conversation](https://docs.whippy.ai/reference/updateconversation.md)