Inbox categories, translation and auto-reply

#List inbox categories

Returns the categories your inbox sorts conversations into. Everyone on your account shares one list, and so do your sub-accounts. A white label sub-account keeps its own.

Returns

dataobject[]: The categories in the order the inbox shows them. Each has an id (like cat_3f9a1c2b7d10), a name and usually a color. [] when you have none.

Errors

HTTP	Code	When
503	`ACCOUNT_UNAVAILABLE`	We couldn’t tell which account’s list to read. Try again. The list can also fail to load with a `503` and no code; try that again too.

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

const res = await fetch('https://api.tryready.com/conversations/chat-categories', {
  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/chat-categories",
    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,
  "data": [
    {
      "id": "cat_3f9a1c2b7d10",
      "name": "Hot leads",
      "color": "#DC2626"
    },
    {
      "id": "cat_81e04d5a9c22",
      "name": "Follow up",
      "color": "#2563EB"
    }
  ]
}

#Save inbox categories

Replaces your account’s whole category list with the one you send. A category you leave out is deleted, and every conversation in it goes back to no category. The change shows for everyone on your account. Needs the send_sms permission and a live key.

Parameters

categoriesobject[]Required: The full list, at most 50. Each entry has a name (text, up to 60 characters) and may have a color (a hex color like #2563EB or a CSS color word). Keep the id of a category you already have; an entry with an unknown id, or none, gets a new id unless a stored category has the same name.
basestring[]: The ids of the list you last read. If your save would delete a category that isn’t in base (someone added it since), nothing is saved and you get a 409.
base_listobject[]: The entries you last read, each with id, name and color. If someone renamed or recolored one of them since, nothing is saved and you get a 409.

Returns

dataobject[]: The saved list, with the id of every category, including ones you just created.

Errors

HTTP	Code	When
400	`invalid_field`	`categories` is missing or not a list, or `base` or `base_list` isn’t a list.
400	`INVALID_CATEGORIES`	More than 50 categories, an entry that isn’t an object, or a name that isn’t text or is over 60 characters.
400	`INVALID_CATEGORY_COLOR`	A `color` that isn’t a hex color or a color word.
409	`CATEGORIES_CHANGED`	The list changed since you read it (see `base` and `base_list`). Nothing was saved. Read the list again and retry.
429	`rate_limited`	Too many requests this minute for your account.
500	(none)	We couldn’t confirm the save. Read the list before you try again.
503	`ACCOUNT_UNAVAILABLE`	We couldn’t tell which account’s list to save. Nothing changed; try again.

curl -X PUT "https://api.tryready.com/conversations/chat-categories" \
  -H "X-API-Key: $READY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "categories": [
      {
        "id": "cat_3f9a1c2b7d10",
        "name": "Hot leads",
        "color": "#DC2626"
      },
      {
        "name": "Booked",
        "color": "#16A34A"
      }
    ],
    "base": [
      "cat_3f9a1c2b7d10",
      "cat_81e04d5a9c22"
    ]
  }'

const res = await fetch('https://api.tryready.com/conversations/chat-categories', {
  method: 'PUT',
  headers: {
    'X-API-Key': process.env.READY_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "categories": [
      {
        "id": "cat_3f9a1c2b7d10",
        "name": "Hot leads",
        "color": "#DC2626"
      },
      {
        "name": "Booked",
        "color": "#16A34A"
      }
    ],
    "base": [
      "cat_3f9a1c2b7d10",
      "cat_81e04d5a9c22"
    ]
  }),
});
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/chat-categories",
    headers={"X-API-Key": os.environ["READY_API_KEY"]},
    json={
        "categories": [
            {
                "id": "cat_3f9a1c2b7d10",
                "name": "Hot leads",
                "color": "#DC2626"
            },
            {
                "name": "Booked",
                "color": "#16A34A"
            }
        ],
        "base": ["cat_3f9a1c2b7d10", "cat_81e04d5a9c22"]
    },
    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": [
    {
      "id": "cat_3f9a1c2b7d10",
      "name": "Hot leads",
      "color": "#DC2626"
    },
    {
      "id": "cat_5b27e0f1a4c9",
      "name": "Booked",
      "color": "#16A34A"
    }
  ]
}

#Move a conversation to a category

Puts a conversation in one of your inbox categories, or takes it out with null. A conversation is in one category at most. Its tags don’t change. Needs the send_sms permission and a live key.

Parameters

idinteger, pathRequired: The conversation id.
category_idstring | nullRequired: A category id from your list, or null (or "") to take the conversation out of its category. Leaving the field out is an error, not a clear.

Returns

category_idstring | null: The conversation’s category now, at the top level.

Errors

HTTP	Code	When
400	`category_not_found`	The id isn’t in your category list, or `category_id` is missing. Nothing changed.
400	`invalid_field`	The conversation id isn’t a whole number, or `category_id` is a list or object.
404	`CONVERSATION_NOT_FOUND`	No such conversation on your account, or it has no contact.
500	`CONVERSATION_UPDATE_FAILED`	The change wasn’t saved. Nothing changed; try again in a minute.

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

const res = await fetch('https://api.tryready.com/conversations/5521/category', {
  method: 'PUT',
  headers: {
    'X-API-Key': process.env.READY_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "category_id": "cat_3f9a1c2b7d10"
  }),
});
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/category",
    headers={"X-API-Key": os.environ["READY_API_KEY"]},
    json={
        "category_id": "cat_3f9a1c2b7d10"
    },
    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,
  "category_id": "cat_3f9a1c2b7d10"
}

#Translate a message to English

Detects the language of a message you received and translates it to English. Pass message_id and the translation is saved on the message, so asking again is instant. Or pass text to translate any text without saving it. There is no charge. Needs the send_sms permission and a live key.

Parameters

message_idinteger: An inbound message on your account. Outbound messages can’t be translated. When you send it, text is ignored.
textstring: Text to translate, used when there’s no message_id. Only the first 2,000 characters are translated.

Returns

data.source_langstring | null: The detected language in English, like Spanish. English when no translation was needed.
data.is_englishboolean: true when the message is already in English.
data.translationstring | null: The English text. "" when the message is already English.
data.cachedboolean: true when the translation came from the one saved on the message. Left out otherwise.
data.unavailableboolean: true when translation isn’t working right now. The answer is still a 200, with translation: null. Show the original and try again later.

Errors

HTTP	Code	When
400	`NO_TEXT_TO_TRANSLATE`	No `message_id` and no `text`, or the message or text is empty.
400	`TRANSLATE_OUTBOUND`	The message is one you sent. Only received messages can be translated.
400	`invalid_field`	`text` is a list or object.
403	`CONVERSATION_NOT_ASSIGNED`	The key’s user only sees their own contacts, and this message’s contact is assigned to a teammate.
403	`CONVERSATION_NOT_ALLOCATED`	The key’s user is limited to some of your numbers, and this message is on another one.
404	`MESSAGE_NOT_FOUND`	No such message on your account.
429	`TRANSLATE_DAILY_LIMIT`	The key’s user reached today’s translation limit. It resets at midnight UTC; `resets_at` says when, if present.
429	`rate_limited`	Too many AI requests from your account in the last 15 minutes.
503	`TRANSLATE_READ_FAILED`	We couldn’t load the message. Try again in a moment.

curl -X POST "https://api.tryready.com/conversations/translate" \
  -H "X-API-Key: $READY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message_id": 90412
  }'

const res = await fetch('https://api.tryready.com/conversations/translate', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.READY_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "message_id": 90412
  }),
});
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.post(
    "https://api.tryready.com/conversations/translate",
    headers={"X-API-Key": os.environ["READY_API_KEY"]},
    json={
        "message_id": 90412
    },
    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": {
    "source_lang": "Spanish",
    "is_english": false,
    "translation": "Yes, I'm interested. What time works?"
  }
}

{
  "success": true,
  "data": {
    "source_lang": null,
    "is_english": false,
    "translation": null,
    "unavailable": true
  }
}

#Get the auto-reply

The text your account sends back when a contact texts you outside business hours, with the hours and time zone it uses. The setting belongs to the account, so every team member reads the same one. If you never saved it, you get the defaults with enabled: false.

Returns

data.enabledboolean: Whether the auto-reply is on.
data.messagestring: The text it sends.
data.scheduleobject: Your business hours, one key per day (monday to sunday). Each day has enabled, start and end as 24-hour HH:MM. The default is 09:00 to 17:00 on weekdays, with the weekend off.
data.timezonestring: The IANA time zone the hours are in, like America/Chicago.

curl "https://api.tryready.com/settings/auto-reply" \
  -H "X-API-Key: $READY_API_KEY"

const res = await fetch('https://api.tryready.com/settings/auto-reply', {
  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/settings/auto-reply",
    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,
  "data": {
    "enabled": true,
    "message": "Thanks for your text! We're closed right now and will reply when we open.",
    "schedule": {
      "monday": { "enabled": true, "start": "09:00", "end": "17:00" },
      "tuesday": { "enabled": true, "start": "09:00", "end": "17:00" },
      "wednesday": { "enabled": true, "start": "09:00", "end": "17:00" },
      "thursday": { "enabled": true, "start": "09:00", "end": "17:00" },
      "friday": { "enabled": true, "start": "09:00", "end": "17:00" },
      "saturday": { "enabled": false, "start": "10:00", "end": "14:00" },
      "sunday": { "enabled": false, "start": "10:00", "end": "14:00" }
    },
    "timezone": "America/Chicago"
  }
}

#Update the auto-reply

Turns the auto-reply on or off, or changes its text, hours or time zone. Send only what you change: a field you leave out keeps its saved value. On a first save, a field you leave out takes the value Get the auto-reply shows. Needs the send_sms permission.

Parameters

enabledboolean: On or off.
messagestring: The text to send, up to 480 characters. It can’t be blank.
scheduleobject: Your business hours, keyed by day (monday to sunday). Each day is { "enabled": true, "start": "09:00", "end": "17:00" }, with times as 24-hour HH:MM. The auto-reply goes out outside these hours. It replaces the saved hours.
timezonestring: An IANA time zone, like America/Chicago. A first save without one uses your account’s time zone.

Returns

{ "success": true }. Read the saved values back with Get the auto-reply.

Errors

HTTP	Code	When
400	`invalid_field`	A field has the wrong type, or `timezone` is over 64 characters.
400	no code	An empty body, a blank `message`, a message over 480 characters, a day in `schedule` that isn’t in the right shape, or a time zone we don’t know. Nothing was saved.

curl -X PUT "https://api.tryready.com/settings/auto-reply" \
  -H "X-API-Key: $READY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "message": "Thanks for your text! We are closed right now and will reply when we open.",
    "timezone": "America/Chicago"
  }'

const res = await fetch('https://api.tryready.com/settings/auto-reply', {
  method: 'PUT',
  headers: {
    'X-API-Key': process.env.READY_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "enabled": true,
    "message": "Thanks for your text! We are closed right now and will reply when we open.",
    "timezone": "America/Chicago"
  }),
});
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/settings/auto-reply",
    headers={"X-API-Key": os.environ["READY_API_KEY"]},
    json={
        "enabled": True,
        "message": "Thanks for your text! We are closed right now and will reply when we open.",
        "timezone": "America/Chicago"
    },
    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
}