AI reply agents

An AI reply agent answers your contacts' texts for you. These endpoints do what the bar above an inbox conversation does (its Take over and Resume AI buttons): see which agent is handling a conversation, stop it so a person can reply, and hand the conversation back. You can also switch an agent on or off. Each reply an agent sends costs 1 × your per-segment rate on top of the text itself. An agent is made in the dashboard, and each one runs inside an automation.

#List AI agents

Every AI reply agent on your account, oldest first. Needs the manage_campaigns permission.

Returns

dataobject[]: One object per agent. Read id, name and status. The other fields describe how the agent is set up and can change, so don’t rely on them.
data[].statusenum: auto replies on its own, suggest writes drafts for a person to send, off does nothing.

Errors

HTTP	Code	When
500	`agents_unavailable`	We couldn’t read your agents. Retry.

curl "https://api.tryready.com/ai-agents" \
  -H "X-API-Key: $READY_API_KEY"

const res = await fetch('https://api.tryready.com/ai-agents', {
  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/ai-agents",
    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": 12,
      "name": "Front desk",
      "status": "auto",
      "…": "…"
    }
  ]
}

#See which agent has a conversation

Which AI agent is handling a contact’s conversation, and whether it is paused. Needs the view_messages permission.

Parameters

contactIdinteger, pathRequired: The contact’s id.

Returns

data.agentobject | null: The agent’s id, name and status. null when no agent that is switched on has answered or been paused on this contact. The other fields below are then left out.
data.engagedboolean: Always true when agent is set.
data.pausedinteger: 1 when the agent has stopped replying to this contact, else 0.
data.paused_byenum | null: Who paused it: human (a takeover), ai (the agent handed off by itself) or automation. null when not paused.
data.handoff_labelstring | null: Why the agent handed off, as a sentence to show a person. Set only when paused_by is ai. Its wording can change, so don’t match on it.

Errors

HTTP	Code	When
400	`invalid_field`	`contactId` isn’t a whole number.
403	`CONVERSATION_NOT_ASSIGNED`	Your seat sees only its assigned contacts, and this conversation is a teammate’s.
500	`agents_unavailable`	We couldn’t read the AI status. Retry.

curl "https://api.tryready.com/ai-agents/for-contact/4410" \
  -H "X-API-Key: $READY_API_KEY"

const res = await fetch('https://api.tryready.com/ai-agents/for-contact/4410', {
  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/ai-agents/for-contact/4410",
    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": {
    "agent": { "id": 12, "name": "Front desk", "status": "auto" },
    "engaged": true,
    "paused": 1,
    "paused_by": "ai",
    "handoff_label": "The lead asked to talk to a person"
  }
}

#Turn an agent on or off

Switches the automation the agent runs in, the same switch as turning that automation on or off in the dashboard. Off, the agent stops replying to everyone and nothing is billed. On, it starts answering again, and each reply it sends costs 1 × your per-segment rate on top of the text itself. Sending the same value twice changes nothing. Needs the manage_campaigns permission.

Parameters

idinteger, pathRequired: The agent’s id, from List your agents.
enabledbooleanRequired: true turns the agent on, false turns it off. There is no default.

Returns

data.idinteger: The agent’s id.
data.enabledboolean: The state you set.
data.statusenum: The agent’s status now: off after you turn it off, and its saved mode (auto or suggest) after you turn it back on.

Errors

HTTP	Code	When
400	`invalid_enabled`	`enabled` is missing or isn’t `true` or `false`. A path `id` that isn’t a whole number answers `400 invalid_field`.
404	`agent_not_found`	No agent with this id on your account.
409	`AGENT_HAS_NO_AUTOMATION`	The agent isn’t part of an automation yet, so there is nothing to switch. Add it to one in the dashboard.
409	`AUTOMATION_UNFINISHED`	Turning on is refused because the automation isn’t finished. The message says what is missing. Finish it in the dashboard.
400	`SHEETS_ACTIVATION_FAILED`	Turning on is refused because the automation’s Google Sheets trigger couldn’t start. Fix it in the dashboard, then try again.
404	`automation_not_found`	The agent’s automation is gone.
500	`agents_unavailable`	Nothing changed. Retry.

curl -X PUT "https://api.tryready.com/ai-agents/12/enabled" \
  -H "X-API-Key: $READY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": false
  }'

const res = await fetch('https://api.tryready.com/ai-agents/12/enabled', {
  method: 'PUT',
  headers: {
    'X-API-Key': process.env.READY_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "enabled": false
  }),
});
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/ai-agents/12/enabled",
    headers={"X-API-Key": os.environ["READY_API_KEY"]},
    json={
        "enabled": False
    },
    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": 12,
    "enabled": false,
    "status": "off"
  }
}

#Take over a conversation

Stops the agent from replying to one contact, so a person can reply. The agent keeps answering everyone else. Sending it again changes nothing. Needs the manage_campaigns permission.

Parameters

idinteger, pathRequired: The agent’s id, from See which agent has a conversation.
contact_idintegerRequired: The contact whose conversation you take over.

Returns

successboolean: true. Nothing else.

Errors

HTTP	Code	When
400	`contact_required`	`contact_id` is missing or isn’t a whole number.
404	`agent_not_found`	No agent with this id on your account. A path `id` that isn’t a whole number answers `400 invalid_field`.
404	`contact_not_found`	No contact with this id on your account.
403	`CONVERSATION_NOT_ASSIGNED`	Your seat sees only its assigned contacts, and this conversation is a teammate’s.
500	`agents_unavailable`	Nothing changed. Retry.

curl -X POST "https://api.tryready.com/ai-agents/12/pause" \
  -H "X-API-Key: $READY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contact_id": 4410
  }'

const res = await fetch('https://api.tryready.com/ai-agents/12/pause', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.READY_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "contact_id": 4410
  }),
});
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/ai-agents/12/pause",
    headers={"X-API-Key": os.environ["READY_API_KEY"]},
    json={
        "contact_id": 4410
    },
    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
}

#Hand a conversation back

Lets the agent reply to this contact again, whoever paused it. Its count of replies to the contact starts over. Sending it again changes nothing. Needs the manage_campaigns permission.

Parameters

idinteger, pathRequired: The agent’s id.
contact_idintegerRequired: The contact whose conversation you hand back.

Returns

successboolean: true. Nothing else.

Errors

The same as Take over a conversation.

curl -X POST "https://api.tryready.com/ai-agents/12/resume" \
  -H "X-API-Key: $READY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contact_id": 4410
  }'

const res = await fetch('https://api.tryready.com/ai-agents/12/resume', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.READY_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "contact_id": 4410
  }),
});
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/ai-agents/12/resume",
    headers={"X-API-Key": os.environ["READY_API_KEY"]},
    json={
        "contact_id": 4410
    },
    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
}

#Try an agent

Gets the reply the agent would send to a practice conversation. Nothing is sent or saved, and the agent’s tools (tags, bookings) don’t run. Needs the manage_campaigns permission.

Parameters

idinteger, pathRequired: The agent’s id.
messagesobject[]Required: The conversation so far, oldest first, at least one. Each is { "direction": "inbound", "body": "..." }: inbound is the contact, outbound is the agent. Only the last 40 are read, and only the first 1000 characters of each.

Returns

data.replystring: The agent’s reply.
data.handoffboolean: true when the agent would hand this conversation to a person.

Errors

HTTP	Code	When
400	`invalid_field`	`messages` is missing, empty or not a list.
404	`agent_not_found`	No agent with this id on your account.
429	none	Too many AI requests from your account. Wait a few minutes.
502	`ai_unavailable`	The AI didn’t answer. Retry later.
503	`ai_unavailable`	The monthly AI spending limit for agent replies is reached. It fails until the month resets.

curl -X POST "https://api.tryready.com/ai-agents/12/try" \
  -H "X-API-Key: $READY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "direction": "inbound",
        "body": "Do you have anything open on Friday?"
      }
    ]
  }'

const res = await fetch('https://api.tryready.com/ai-agents/12/try', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.READY_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "messages": [
      {
        "direction": "inbound",
        "body": "Do you have anything open on Friday?"
      }
    ]
  }),
});
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/ai-agents/12/try",
    headers={"X-API-Key": os.environ["READY_API_KEY"]},
    json={
        "messages": [
            {
                "direction": "inbound",
                "body": "Do you have anything open on Friday?"
            }
        ]
    },
    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": {
    "reply": "We do! Friday at 10am or 2pm. Which works for you?",
    "handoff": false
  }
}