Conversations · Ready Docs

#Conversations

The inbox has one thread per contact. To reply, send to the contact with POST /v1/messages; it lands in the same thread.

Errors here carry their code in code unless noted. View-only teammates can read conversations but not change them.

#List conversations

GET/conversations

Your inbox threads: starred first, then by latest message.

Cost Free

Query parameters

limitintegerOptionalDefault 50Max 1000: Page size.
offsetintegerOptionalDefault 0: Rows to skip: a whole number, 0 or more.
filterenumOptional: Which view; default is open threads (archived and snoozed hidden). Unknown values are ignored.
unread
starred
archived
snoozed
spam
blocked
searchstringOptional: Matches the contact's name, phone, email or company, or the thread's most recent message.
Details
Older messages aren't searched. A full phone number in any format matches exactly.
line_idsstringOptional: Comma-separated number ids from GET /v1/numbers (not phone numbers), up to 100.
Details
For example line_ids=2647,2648. Invalid values are ignored, which returns the whole inbox.
freshintegerOptional: Lists are cached up to 30 seconds. Send 1 after a change to read live.

Returns

data[]object[]: Threads. Ignore fields you don't recognize.
Details
Fields include id, contact_id, first_name, last_name, phone, status, unread_count, starred, pinned, assigned_to, last_message_at, last_message_preview, phone_number_id, from_number, tags and more.
has_moreboolean: Keep paging while true.
totalinteger: Threads matching filter and search, counted up to 1,000.
Details
Past that, total_capped: true and count_cap: 1000. With line_ids, total and counts ignore the lines and count every line's threads, so use has_more.
countsobject: Thread counts per view.
Details
all (the default view, without archived and snoozed), unread, starred, pinned, archived, snoozed, spam.

Errors

HTTP	Code	When
400	`invalid_offset`	Not a whole number, 0 or more (in `error_code`).

GET /conversations

curl "https://api.tryready.com/conversations?limit=50&filter=unread" \
  -H "X-API-Key: $READY_API_KEY"

const res = await fetch('https://api.tryready.com/conversations?limit=50&filter=unread', {
  headers: {
    'X-API-Key': process.env.READY_API_KEY,
  },
});
const json = await res.json();
if (!res.ok || json.success === false) {
  throw new Error(`${res.status} ${json.error_code || json.code}: ${json.error}`);
}

import os, requests

r = requests.get(
    "https://api.tryready.com/conversations",
    headers={"X-API-Key": os.environ["READY_API_KEY"]},
    params={
        "limit": 50,
        "filter": "unread"
    },
    timeout=30,
)
data = r.json()
if not r.ok or data.get("success") is False:
    raise RuntimeError(f'{r.status_code} {data.get("error_code") or data.get("code")}: {data.get("error")}')

Response

{
  "success": true,
  "data": [
    {
      "id": 5521,
      "contact_id": 101,
      "first_name": "Ada",
      "last_name": "Lovelace",
      "phone": "+12125550199",
      "status": "open",
      "unread_count": 1,
      "starred": 0,
      "pinned": 0,
      "assigned_to": null,
      "last_message_at": "2026-10-01T20:40:12.004Z",
      "last_message_preview": "Yes, I'm interested!",
      "phone_number_id": 2647,
      "from_number": "+14155550100"
    }
  ],
  "total": 1,
  "has_more": false,
  "total_capped": false,
  "count_cap": 1000,
  "counts": {
    "all": 238,
    "unread": 1,
    "starred": 0,
    "pinned": 0,
    "archived": 10,
    "snoozed": 0,
    "spam": 0
  }
}

#List messages in a conversation

GET/conversations/:id/messages

One thread's messages: the newest page, oldest first within the page.

Cost Free

Important. Reading the newest page marks the thread as read. Sync jobs should add mark_read=0.

Path parameters

idintegerRequired: The conversation id.

Query parameters

mark_readintegerOptional: Send 0 to leave the unread state alone.
limitintegerOptionalDefault 50Max 500: Page size.
offsetintegerOptionalDefault 0: Increase to go further back in time.

Returns

data[]object[]: Messages. Ignore fields you don't recognize.
Details
Fields include id, direction (inbound or outbound), body, status, to_number, from_number, segments, cost, media_url, created_at, sent_at, delivered_at, failed_at, and more.

Errors

HTTP	Code	When
403	`CONVERSATION_NOT_ASSIGNED`	Teammate access doesn't cover this thread. Details Assigned to someone else. Also `CONVERSATION_NOT_ALLOCATED`: the thread's number isn't allocated to you.
404	`CONVERSATION_NOT_FOUND`	No such conversation on your account.

GET /conversations/:id/messages

curl "https://api.tryready.com/conversations/5521/messages?mark_read=0&limit=50" \
  -H "X-API-Key: $READY_API_KEY"

const res = await fetch('https://api.tryready.com/conversations/5521/messages?mark_read=0&limit=50', {
  headers: {
    'X-API-Key': process.env.READY_API_KEY,
  },
});
const json = await res.json();
if (!res.ok || json.success === false) {
  throw new Error(`${res.status} ${json.error_code || json.code}: ${json.error}`);
}

import os, requests

r = requests.get(
    "https://api.tryready.com/conversations/5521/messages",
    headers={"X-API-Key": os.environ["READY_API_KEY"]},
    params={
        "mark_read": 0,
        "limit": 50
    },
    timeout=30,
)
data = r.json()
if not r.ok or data.get("success") is False:
    raise RuntimeError(f'{r.status_code} {data.get("error_code") or data.get("code")}: {data.get("error")}')

Response

{
  "success": true,
  "data": [
    {
      "id": 19292894,
      "direction": "outbound",
      "body": "Your order #1042 has shipped.",
      "status": "delivered",
      "to_number": "+12125550199",
      "from_number": "+14155550100",
      "segments": 1,
      "cost": 0.0245,
      "media_url": null,
      "created_at": "2026-10-01T20:32:03.473Z",
      "sent_at": "2026-10-01T20:32:04.102Z",
      "delivered_at": "2026-10-01T20:32:09.856Z",
      "failed_at": null
    },
    {
      "id": 19408828,
      "direction": "inbound",
      "body": "Yes, I'm interested!",
      "status": "received",
      "to_number": "+14155550100",
      "from_number": "+12125550199",
      "segments": 1,
      "cost": 0.0145,
      "media_url": null,
      "created_at": "2026-10-01T20:40:12.004Z",
      "sent_at": null,
      "delivered_at": null,
      "failed_at": null
    }
  ]
}

#Find a contact's conversation

GET/conversations/by-contact/:contactId

The thread for one contact, or null if there isn't one.

Cost Free

Path parameters

contactIdintegerRequired: The contact id.

Returns

dataobject | null: The thread, or null. An unknown contact id also returns null, not a 404.
Details
This row has contact_status, dnd_sms and opt_out_at, and no tags.

Errors

HTTP	Code	When
403	`CONVERSATION_NOT_ASSIGNED`	Teammate access doesn't cover this thread. Details Assigned to someone else. Also `CONVERSATION_NOT_ALLOCATED`: the thread's number isn't allocated to you.

GET /conversations/by-contact/:contactId

curl "https://api.tryready.com/conversations/by-contact/101" \
  -H "X-API-Key: $READY_API_KEY"

const res = await fetch('https://api.tryready.com/conversations/by-contact/101', {
  headers: {
    'X-API-Key': process.env.READY_API_KEY,
  },
});
const json = await res.json();
if (!res.ok || json.success === false) {
  throw new Error(`${res.status} ${json.error_code || json.code}: ${json.error}`);
}

import os, requests

r = requests.get(
    "https://api.tryready.com/conversations/by-contact/101",
    headers={"X-API-Key": os.environ["READY_API_KEY"]},
    timeout=30,
)
data = r.json()
if not r.ok or data.get("success") is False:
    raise RuntimeError(f'{r.status_code} {data.get("error_code") or data.get("code")}: {data.get("error")}')

Response

{
  "success": true,
  "data": {
    "id": 5521,
    "contact_id": 101,
    "first_name": "Ada",
    "last_name": "Lovelace",
    "phone": "+12125550199",
    "status": "open",
    "unread_count": 0,
    "contact_status": "active",
    "dnd_sms": 0,
    "opt_out_at": null,
    "last_message_at": "2026-10-01T20:40:12.004Z"
  }
}

{
  "success": true,
  "data": null
}

#Assign a conversation

PUT/conversations/:id/assign

Replaces the thread's assignees.

Auth API key, not view-only
Cost Free

Path parameters

idintegerRequired: The conversation id.

Body parameters

assignee_idsinteger[]Required: Team member ids (Settings → Team); [] unassigns. The first id is the primary owner.
Details
The first id also becomes the contact's owner. It must be a JSON array of ids.

Returns

assignee_idsinteger[]: The new assignees, at the top level.

Errors

HTTP	Code	When
400	`invalid_assignee_ids`	Not a list of ids (in `error_code`).
400	`invalid_assignee`	An id isn't on your team.
404	`not_found`	No such conversation (lower case here).

PUT /conversations/:id/assign

curl -X PUT "https://api.tryready.com/conversations/5521/assign" \
  -H "X-API-Key: $READY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "assignee_ids": [
      88,
      91
    ]
  }'

const res = await fetch('https://api.tryready.com/conversations/5521/assign', {
  method: 'PUT',
  headers: {
    'X-API-Key': process.env.READY_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "assignee_ids": [
      88,
      91
    ]
  }),
});
const json = await res.json();
if (!res.ok || json.success === false) {
  throw new Error(`${res.status} ${json.error_code || json.code}: ${json.error}`);
}

import os, requests

r = requests.put(
    "https://api.tryready.com/conversations/5521/assign",
    headers={"X-API-Key": os.environ["READY_API_KEY"]},
    json={
        "assignee_ids": [88, 91]
    },
    timeout=30,
)
data = r.json()
if not r.ok or data.get("success") is False:
    raise RuntimeError(f'{r.status_code} {data.get("error_code") or data.get("code")}: {data.get("error")}')

Response

{
  "success": true,
  "assignee_ids": [
    88,
    91
  ]
}

#Set conversation status

PUT/conversations/:id/status

Opens or closes a thread.

Auth API key, not view-only
Cost Free

Path parameters

idintegerRequired: The conversation id.

Body parameters

statusenumRequired: open or closed (also active, archived). To archive, prefer Archive, which also sets the archive time.

Errors

HTTP	Code	When
400	`invalid_status`	Missing or unknown status.
404	no code	No such conversation.

PUT /conversations/:id/status

curl -X PUT "https://api.tryready.com/conversations/5521/status" \
  -H "X-API-Key: $READY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "closed"
  }'

const res = await fetch('https://api.tryready.com/conversations/5521/status', {
  method: 'PUT',
  headers: {
    'X-API-Key': process.env.READY_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "status": "closed"
  }),
});
const json = await res.json();
if (!res.ok || json.success === false) {
  throw new Error(`${res.status} ${json.error_code || json.code}: ${json.error}`);
}

import os, requests

r = requests.put(
    "https://api.tryready.com/conversations/5521/status",
    headers={"X-API-Key": os.environ["READY_API_KEY"]},
    json={
        "status": "closed"
    },
    timeout=30,
)
data = r.json()
if not r.ok or data.get("success") is False:
    raise RuntimeError(f'{r.status_code} {data.get("error_code") or data.get("code")}: {data.get("error")}')

Response

{
  "success": true
}

#Mark read

PUT/conversations/:id/read

Clears the thread's unread count. No body.

Auth API key, not view-only
Cost Free

Path parameters

idintegerRequired: The conversation id.

Errors

HTTP	Code	When
404	`CONVERSATION_NOT_FOUND`	No such conversation on your account.

PUT /conversations/:id/read

curl -X PUT "https://api.tryready.com/conversations/5521/read" \
  -H "X-API-Key: $READY_API_KEY"

const res = await fetch('https://api.tryready.com/conversations/5521/read', {
  method: 'PUT',
  headers: {
    'X-API-Key': process.env.READY_API_KEY,
  },
});
const json = await res.json();
if (!res.ok || json.success === false) {
  throw new Error(`${res.status} ${json.error_code || json.code}: ${json.error}`);
}

import os, requests

r = requests.put(
    "https://api.tryready.com/conversations/5521/read",
    headers={"X-API-Key": os.environ["READY_API_KEY"]},
    timeout=30,
)
data = r.json()
if not r.ok or data.get("success") is False:
    raise RuntimeError(f'{r.status_code} {data.get("error_code") or data.get("code")}: {data.get("error")}')

Response

{
  "success": true
}

#Mark unread

PUT/conversations/:id/unread

Sets the thread's unread count to 1. No body.

Auth API key, not view-only
Cost Free

Path parameters

idintegerRequired: The conversation id.

Errors

HTTP	Code	When
404	`CONVERSATION_NOT_FOUND`	No such conversation on your account.

PUT /conversations/:id/unread

curl -X PUT "https://api.tryready.com/conversations/5521/unread" \
  -H "X-API-Key: $READY_API_KEY"

const res = await fetch('https://api.tryready.com/conversations/5521/unread', {
  method: 'PUT',
  headers: {
    'X-API-Key': process.env.READY_API_KEY,
  },
});
const json = await res.json();
if (!res.ok || json.success === false) {
  throw new Error(`${res.status} ${json.error_code || json.code}: ${json.error}`);
}

import os, requests

r = requests.put(
    "https://api.tryready.com/conversations/5521/unread",
    headers={"X-API-Key": os.environ["READY_API_KEY"]},
    timeout=30,
)
data = r.json()
if not r.ok or data.get("success") is False:
    raise RuntimeError(f'{r.status_code} {data.get("error_code") or data.get("code")}: {data.get("error")}')

Response

{
  "success": true
}

#Archive

PUT/conversations/:id/archive

Archives the thread and clears its unread count. No body.

Auth API key, not view-only
Cost Free

Path parameters

idintegerRequired: The conversation id.

Errors

HTTP	Code	When
404	`CONVERSATION_NOT_FOUND`	No such conversation on your account.

PUT /conversations/:id/archive

curl -X PUT "https://api.tryready.com/conversations/5521/archive" \
  -H "X-API-Key: $READY_API_KEY"

const res = await fetch('https://api.tryready.com/conversations/5521/archive', {
  method: 'PUT',
  headers: {
    'X-API-Key': process.env.READY_API_KEY,
  },
});
const json = await res.json();
if (!res.ok || json.success === false) {
  throw new Error(`${res.status} ${json.error_code || json.code}: ${json.error}`);
}

import os, requests

r = requests.put(
    "https://api.tryready.com/conversations/5521/archive",
    headers={"X-API-Key": os.environ["READY_API_KEY"]},
    timeout=30,
)
data = r.json()
if not r.ok or data.get("success") is False:
    raise RuntimeError(f'{r.status_code} {data.get("error_code") or data.get("code")}: {data.get("error")}')

Response

{
  "success": true
}

#Unarchive

PUT/conversations/:id/unarchive

Brings the thread back to the inbox with status: "open", even if it was closed. No body.

Auth API key, not view-only
Cost Free

Path parameters

idintegerRequired: The conversation id.

Errors

HTTP	Code	When
404	`CONVERSATION_NOT_FOUND`	No such conversation on your account.

PUT /conversations/:id/unarchive

curl -X PUT "https://api.tryready.com/conversations/5521/unarchive" \
  -H "X-API-Key: $READY_API_KEY"

const res = await fetch('https://api.tryready.com/conversations/5521/unarchive', {
  method: 'PUT',
  headers: {
    'X-API-Key': process.env.READY_API_KEY,
  },
});
const json = await res.json();
if (!res.ok || json.success === false) {
  throw new Error(`${res.status} ${json.error_code || json.code}: ${json.error}`);
}

import os, requests

r = requests.put(
    "https://api.tryready.com/conversations/5521/unarchive",
    headers={"X-API-Key": os.environ["READY_API_KEY"]},
    timeout=30,
)
data = r.json()
if not r.ok or data.get("success") is False:
    raise RuntimeError(f'{r.status_code} {data.get("error_code") or data.get("code")}: {data.get("error")}')

Response

{
  "success": true
}

#Star or unstar

PUT/conversations/:id/star

Toggles the star on or off. No body.

Auth API key, not view-only
Cost Free

Path parameters

idintegerRequired: The conversation id.

Returns

data.starredinteger: The new value, 1 or 0. For a specific state, read starred from the list first.

Errors

HTTP	Code	When
404	`CONVERSATION_NOT_FOUND`	No such conversation on your account.

PUT /conversations/:id/star

curl -X PUT "https://api.tryready.com/conversations/5521/star" \
  -H "X-API-Key: $READY_API_KEY"

const res = await fetch('https://api.tryready.com/conversations/5521/star', {
  method: 'PUT',
  headers: {
    'X-API-Key': process.env.READY_API_KEY,
  },
});
const json = await res.json();
if (!res.ok || json.success === false) {
  throw new Error(`${res.status} ${json.error_code || json.code}: ${json.error}`);
}

import os, requests

r = requests.put(
    "https://api.tryready.com/conversations/5521/star",
    headers={"X-API-Key": os.environ["READY_API_KEY"]},
    timeout=30,
)
data = r.json()
if not r.ok or data.get("success") is False:
    raise RuntimeError(f'{r.status_code} {data.get("error_code") or data.get("code")}: {data.get("error")}')

Response

{
  "success": true,
  "data": {
    "starred": 1
  }
}