---
title: "Get conversation history by phone number"
description: "Fetches the conversation history for a contact identified by phone number.\nReturns messages in chronological order with sender labels and optional timestamps.\nInternal notes are always excluded.\n"
---

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

Path: Channel Automation API › Conversations

`GET /api/conversations/phone`

Fetches the conversation history for a contact identified by phone number.
Returns messages in chronological order with sender labels and optional timestamps.
Internal notes are always excluded.

## Authentication

Requires one of the following:

- `ApiKeyAuth`, apiKey, in header, header `X-API-Key`, format `API_KEY`
- `BearerAuth`, http, header `Authorization`, format `JWT`

## Query parameters

- `phone` (`get/api/conversations/phone.query.phone`; string, required) — Contact phone number in E.164 format
- `format` (`get/api/conversations/phone.query.format`; string, optional) — Response format: - `default`: Simple text strings prefixed with "Agent:" or "Contact:" - `detailed`: Full message objects with timestamp, direction, channel, and body
  - one of `"default"`, `"detailed"`; default `"default"`
- `include_agent` (`get/api/conversations/phone.query.include_agent`; boolean, optional) — Include messages sent by human agents
  - default `true`
- `include_bot` (`get/api/conversations/phone.query.include_bot`; boolean, optional) — Include messages sent by automations (flows, sequences, keywords)
  - default `true`
- `limit` (`get/api/conversations/phone.query.limit`; integer, optional) — Maximum number of messages to return
  - min 1; max 100; default `50`
- `offset` (`get/api/conversations/phone.query.offset`; integer, optional) — Number of messages to skip (for pagination)
  - min 0; default `0`

## Header parameters

- `X-Workspace-Id` (`get/api/conversations/phone.header.X-Workspace-Id`; string, required) — Workspace ID for data isolation

## Code samples

### cURL

```bash
curl --request GET \
  --url 'https://api.channelautomation.com/api/conversations/phone?phone=%2B15137734774' \
  --header 'X-API-Key: <X-API-Key>' \
  --header 'X-Workspace-Id: 15213'
```

### TypeScript

```typescript
const url = 'https://api.channelautomation.com/api/conversations/phone?phone=%2B15137734774';
const options = {method: 'GET', headers: {'X-Workspace-Id': '15213', 'X-API-Key': '<X-API-Key>'}};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error(err));
```

### Python

```python
import requests

url = "https://api.channelautomation.com/api/conversations/phone?phone=%2B15137734774"

headers = {
    "X-Workspace-Id": "15213",
    "X-API-Key": "<X-API-Key>"
}

response = requests.get(url, headers=headers)

print(response.text)
```

## Responses

### 200

Conversation history retrieved successfully

#### Example

```json
{
  "status": "ok",
  "data": [
    "Agent: Hi Bhavesh, this is Taylor from HANSONS...",
    "Contact: Open today until 7pm or from 6.30 to 8pm tomorrow",
    "Agent: What project are you looking to get a price on?",
    "Contact: Roof"
  ],
  "pagination": {
    "total": 8,
    "limit": 50,
    "offset": 0,
    "has_more": false
  }
}
```

One of:

- `ConversationResponseSimple`
- `ConversationResponseDetailed`

### 400

Invalid request parameters

#### Example

```json
{
  "status": "error",
  "error": "phone query parameter is required"
}
```

- `status` (`get/api/conversations/phone.response.400.status`; string, optional)
  - example `"error"`
- `error` (`get/api/conversations/phone.response.400.error`; string, optional)
  - example `"phone query parameter is required"`

### 401

Authentication required

#### Example

```json
{
  "error": "Authentication required",
  "success": false
}
```

- `error` (`get/api/conversations/phone.response.401.error`; string, optional)
  - example `"Authentication required"`
- `success` (`get/api/conversations/phone.response.401.success`; boolean, optional)
  - example `false`

### 404

Contact not found for this phone number

#### Example

```json
{
  "status": "error",
  "error": "Contact not found for this phone number"
}
```

- `status` (`get/api/conversations/phone.response.404.status`; string, optional)
  - example `"error"`
- `error` (`get/api/conversations/phone.response.404.error`; string, optional)
  - example `"Contact not found for this phone number"`

### 500

Internal server error

#### Example

```json
{
  "error": "Internal server error",
  "details": "string",
  "success": false
}
```

- `error` (`get/api/conversations/phone.response.500.error`; string, optional)
  - example `"Internal server error"`
- `details` (`get/api/conversations/phone.response.500.details`; string, optional)
- `success` (`get/api/conversations/phone.response.500.success`; boolean, optional)
  - example `false`


Source: https://developer.channelautomations.com/api/get-api-conversations-phone/index.md