Conversation actions

#Assign a conversation

Replaces the thread’s assignees.

Parameters

idinteger, pathRequired: The conversation id.
assignee_idsinteger[]: A JSON array of team member ids (Settings → Team). Send [] to unassign. A body with neither assignee_ids nor assigned_to is refused with 400 invalid_assignee_ids and nothing changes. The first id is the primary owner and also becomes the contact’s owner.
base_idsinteger[]: The assignees you last read with Get a conversation’s assignees. If the thread’s assignees changed since (order doesn’t matter), nothing is saved and you get 409 ASSIGNEES_CHANGED. Leave it out to save without the check.

Returns

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

Errors

HTTP	Code	When
400	`invalid_assignee_ids`	The body has neither `assignee_ids` nor `assigned_to`, `assignee_ids` or `base_ids` isn’t a list of ids, or `assigned_to` isn’t an id. Nothing changed. `code` and `error_code` both carry it.
400	`invalid_assignee`	An id isn’t on your team.
404	`not_found`	No such conversation (lower case here, not `CONVERSATION_NOT_FOUND`).
409	`ASSIGNEES_CHANGED`	You sent `base_ids` and someone changed the assignees since. Nothing was saved. Read the current assignees, then pick again.

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().catch(() => ({}));
if (!res.ok || json.success === false) {
  throw new Error(`${res.status}${json.error_code || json.code ? ' ' + (json.error_code || json.code) : ''}: ${json.error || json.message || res.statusText}`);
}

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 r.headers.get("content-type", "").startswith("application/json") else {}
if not r.ok or data.get("success") is False:
    raise RuntimeError(f'{r.status_code} {data.get("error_code") or data.get("code") or ""}: {data.get("error") or data.get("message") or r.reason}')

Returns:

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

#Set a conversation’s status

Opens or closes a thread.

Parameters

idinteger, pathRequired: The conversation id.
statusenumRequired: open or closed, or archived, which does what Archive a conversation does: it archives the thread and clears the unread count.

Errors

HTTP	Code	When
400	`invalid_status`	Missing or unknown status.
404	`CONVERSATION_NOT_FOUND`	No such conversation, or the key’s user can’t see it. Upper case here, unlike assign.
500	`CONVERSATION_UPDATE_FAILED`	The change wasn’t saved. Try again.

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().catch(() => ({}));
if (!res.ok || json.success === false) {
  throw new Error(`${res.status}${json.error_code || json.code ? ' ' + (json.error_code || json.code) : ''}: ${json.error || json.message || res.statusText}`);
}

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 r.headers.get("content-type", "").startswith("application/json") else {}
if not r.ok or data.get("success") is False:
    raise RuntimeError(f'{r.status_code} {data.get("error_code") or data.get("code") or ""}: {data.get("error") or data.get("message") or r.reason}')

Returns:

{
  "success": true
}

#Mark a conversation read

Clears the thread’s unread count. No body.

Parameters

idinteger, pathRequired: The conversation id.

Errors

HTTP	Code	When
404	`CONVERSATION_NOT_FOUND`	No such conversation, or the key’s user can’t see it. Upper case here, unlike assign.
500	`CONVERSATION_UPDATE_FAILED`	The change wasn’t saved. Try again.

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().catch(() => ({}));
if (!res.ok || json.success === false) {
  throw new Error(`${res.status}${json.error_code || json.code ? ' ' + (json.error_code || json.code) : ''}: ${json.error || json.message || res.statusText}`);
}

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 r.headers.get("content-type", "").startswith("application/json") else {}
if not r.ok or data.get("success") is False:
    raise RuntimeError(f'{r.status_code} {data.get("error_code") or data.get("code") or ""}: {data.get("error") or data.get("message") or r.reason}')

Returns:

{
  "success": true
}

#Mark a conversation unread

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

Parameters

idinteger, pathRequired: The conversation id.

Errors

HTTP	Code	When
404	`CONVERSATION_NOT_FOUND`	No such conversation, or the key’s user can’t see it. Upper case here, unlike assign.
500	`CONVERSATION_UPDATE_FAILED`	The change wasn’t saved. Try again.

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().catch(() => ({}));
if (!res.ok || json.success === false) {
  throw new Error(`${res.status}${json.error_code || json.code ? ' ' + (json.error_code || json.code) : ''}: ${json.error || json.message || res.statusText}`);
}

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 r.headers.get("content-type", "").startswith("application/json") else {}
if not r.ok or data.get("success") is False:
    raise RuntimeError(f'{r.status_code} {data.get("error_code") or data.get("code") or ""}: {data.get("error") or data.get("message") or r.reason}')

Returns:

{
  "success": true
}

#Archive a conversation

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

Parameters

idinteger, pathRequired: The conversation id.

Errors

HTTP	Code	When
404	`CONVERSATION_NOT_FOUND`	No such conversation, or the key’s user can’t see it. Upper case here, unlike assign.
500	`CONVERSATION_WRITE_FAILED`	The change wasn’t saved. Try again.

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().catch(() => ({}));
if (!res.ok || json.success === false) {
  throw new Error(`${res.status}${json.error_code || json.code ? ' ' + (json.error_code || json.code) : ''}: ${json.error || json.message || res.statusText}`);
}

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 r.headers.get("content-type", "").startswith("application/json") else {}
if not r.ok or data.get("success") is False:
    raise RuntimeError(f'{r.status_code} {data.get("error_code") or data.get("code") or ""}: {data.get("error") or data.get("message") or r.reason}')

Returns:

{
  "success": true
}

#Unarchive a conversation

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

Parameters

idinteger, pathRequired: The conversation id.

Errors

HTTP	Code	When
404	`CONVERSATION_NOT_FOUND`	No such conversation, or the key’s user can’t see it. Upper case here, unlike assign.
500	`CONVERSATION_WRITE_FAILED`	The change wasn’t saved. Try again.

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().catch(() => ({}));
if (!res.ok || json.success === false) {
  throw new Error(`${res.status}${json.error_code || json.code ? ' ' + (json.error_code || json.code) : ''}: ${json.error || json.message || res.statusText}`);
}

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 r.headers.get("content-type", "").startswith("application/json") else {}
if not r.ok or data.get("success") is False:
    raise RuntimeError(f'{r.status_code} {data.get("error_code") or data.get("code") or ""}: {data.get("error") or data.get("message") or r.reason}')

Returns:

{
  "success": true
}

#Star or unstar a conversation

Sets the star on or off. Send starred to say which, so a retry after a timeout can’t undo the change. With no body it toggles instead.

Parameters

idinteger, pathRequired: The conversation id.
starredboolean, body: true to star, false to unstar. Optional: leave it out and the call toggles. Anything else is a 400 invalid_starred.

Returns

data.starredinteger: The new value, 1 or 0.

Errors

HTTP	Code	When
404	`CONVERSATION_NOT_FOUND`	No such conversation, or the key’s user can’t see it. Upper case here, unlike assign.
500	`CONVERSATION_UPDATE_FAILED`	The change wasn’t saved. Try again.

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

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

import os, requests

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

Returns:

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

#Get a conversation’s assignees

Lists the team members assigned to a thread. The primary owner comes first. Send this list as base_ids when you assign the conversation, so you don’t overwrite a change a teammate made in between.

Parameters

idinteger, pathRequired: The conversation id.

Returns

assignee_idsinteger[]: Team member ids, primary first, at the top level. [] when nobody is assigned.

Errors

HTTP	Code	When
400	`invalid_field`	The id isn’t a whole number.
404	`not_found`	No such conversation, or the key’s user can’t see it (lower case here, not `CONVERSATION_NOT_FOUND`).
500	`ASSIGNEES_READ_FAILED`	We couldn’t read the assignees. Try again.

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

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

import os, requests

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

Returns:

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