Get conversation history by phone number

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.

GET

https://api.channelautomation.com/api/conversations/phone

Authorization

ApiKeyAuth
optional
API key in header

BearerAuth
optional
HTTP Bearer (JWT)

Query parameters

phone
string
required
Contact phone number in E.164 format
format
optional
default
or
detailed
Response format:
- default: Simple text strings prefixed with "Agent:" or "Contact:"
- detailed: Full message objects with timestamp, direction, channel, and body
default: "default"
include_agent
optional
boolean
Include messages sent by human agents

default: true
include_bot
optional
boolean
Include messages sent by automations (flows, sequences, keywords)

default: true
limit
optional
integer
Maximum number of messages to return

maximum: 100 · minimum: 1 · default: 50
offset
optional
integer
Number of messages to skip (for pagination)

minimum: 0 · default: 0

Header parameters

X-Workspace-Id
string
required
Workspace ID for data isolation

Returns

200

Conversation history retrieved successfully

JSON

One of the following:

ConversationResponseSimple
- status
  optional
  string
- data
  optional
  array of
  string
- pagination
  optional
  object
  total
  optional
  integer
  Total number of messages matching filters
  
  limit
  optional
  integer
  Maximum messages per page
  
  offset
  optional
  integer
  Number of messages skipped
  
  has_more
  optional
  boolean
  Whether more messages are available
}
ConversationResponseDetailed
- status
  optional
  string
- data
  optional
  array of
  object
  id
  optional
  string
  Unique message identifier
  
  format: uuid
  timestamp
  optional
  string
  Message date/time (UTC)
  
  format: date-time
  direction
  optional
  inbound
  or
  outbound
  inbound = from contact, outbound = from your team or automations
  
  sender
  optional
  contact
  or
  agent
  or
  bot
  contact = the lead/customer, agent = human team member, bot = automation (flow, sequence, keyword)
  
  channel
  optional
  sms
  or
  mms
  or
  email
  Message channel type
  
  body
  optional
  string
  Message content (may contain HTML for email messages)
  
  media_urls
  optional
  array of
  string
  Attached media URLs (only present for MMS messages)
- contact
  optional
  object
  id
  optional
  string
  Contact ID
  
  format: uuid
  name
  optional
  string
  Contact full name
  
  phone_number
  optional
  string
  Contact phone number in E.164 format
- pagination
  optional
  object
  total
  optional
  integer
  Total number of messages matching filters
  
  limit
  optional
  integer
  Maximum messages per page
  
  offset
  optional
  integer
  Number of messages skipped
  
  has_more
  optional
  boolean
  Whether more messages are available
}

400

Invalid request parameters

JSON

status
optional
string
error
optional
string

401

Authentication required

JSON

error
optional
string
success
optional
boolean

404

Contact not found for this phone number

JSON

status
optional
string
error
optional
string

500

Internal server error

JSON

error
optional
string
details
optional
string
success
optional
boolean

{ "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 } }