Canned responses

Canned responses are pre-written message templates that technicians can insert into ticket and lead communications. Each response specifies a delivery channel (email or SMS), an optional usage context, and, for email, a subject line.

The canned response object

{
  "object": "canned_response",
  "id": 7,
  "title": "Repair complete, ready for pickup",
  "body": "Hi {{customer_name}}, your device is ready for pickup. Please come by during business hours. Thank you!",
  "context": "ticket",
  "channel": "email",
  "subject": "Your repair is complete",
  "created_at": "2025-11-03T09:14:00.000Z"
}

Field	Type	Description
id	integer	Canned response ID
title	string	Internal display name (max 255 characters)
body	string	Message body; may contain {{placeholder}} tokens (max 10,000 characters)
context	string	Where the response is used: ticket or lead
channel	string	Delivery channel: email or sms
subject	string | null	Email subject line (email channel only; null for SMS)
created_at	string	ISO-8601 creation timestamp

---

List canned responses

GET /api/v1/canned-responses

Returns canned responses sorted by most-recently-created first. Supports optional filtering by context and channel.

Scope required: canned_responses.read

Query parameters

Parameter	Type	Description
context	string	Filter by context: ticket or lead
channel	string	Filter by channel: email or sms
limit	integer	Page size, 1–100 (default: 20)
cursor	string	Opaque cursor from a previous response’s next_cursor

curl

curl "https://app.benchkey.com/api/v1/canned-responses?context=ticket&limit=20" \
  -H "Authorization: Bearer bk_live_01J8X4_kvWz9nP3mRqTs7uYeBfGhDjLa"

Node.js

const res = await fetch(
  "https://app.benchkey.com/api/v1/canned-responses?context=ticket&limit=20",
  { headers: { Authorization: "Bearer bk_live_01J8X4_kvWz9nP3mRqTs7uYeBfGhDjLa" } }
);
const { data, has_more, next_cursor } = await res.json();

Response

{
  "object": "list",
  "data": [
    {
      "object": "canned_response",
      "id": 7,
      "title": "Repair complete, ready for pickup",
      "body": "Hi {{customer_name}}, your device is ready for pickup.",
      "context": "ticket",
      "channel": "email",
      "subject": "Your repair is complete",
      "created_at": "2025-11-03T09:14:00.000Z"
    },
    {
      "object": "canned_response",
      "id": 6,
      "title": "Awaiting parts",
      "body": "Hi {{customer_name}}, we are waiting on a part for your repair. We'll update you soon.",
      "context": "ticket",
      "channel": "sms",
      "subject": null,
      "created_at": "2025-10-28T16:42:00.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

See Pagination for how to page through results.

---

Retrieve a canned response

GET /api/v1/canned-responses/:id

Returns a single canned response by ID.

Scope required: canned_responses.read

curl

curl "https://app.benchkey.com/api/v1/canned-responses/7" \
  -H "Authorization: Bearer bk_live_01J8X4_kvWz9nP3mRqTs7uYeBfGhDjLa"

Node.js

const res = await fetch(
  "https://app.benchkey.com/api/v1/canned-responses/7",
  { headers: { Authorization: "Bearer bk_live_01J8X4_kvWz9nP3mRqTs7uYeBfGhDjLa" } }
);
const cr = await res.json();

Response

Returns the canned response object. Returns 404 if not found.

---

Create a canned response

POST /api/v1/canned-responses

Creates a new canned response.

Scope required: canned_responses.write

Request body

Field	Required	Description
title	yes	Internal display name (max 255 characters)
body	yes	Message body (max 10,000 characters)
context	no	ticket (default) or lead
channel	no	email (default) or sms
subject	no	Email subject line (email channel only; omit or null for SMS); whitespace-only values are normalized to null

curl

curl -X POST https://app.benchkey.com/api/v1/canned-responses \
  -H "Authorization: Bearer bk_live_01J8X4_kvWz9nP3mRqTs7uYeBfGhDjLa" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Repair complete, ready for pickup",
    "body": "Hi {{customer_name}}, your device is ready for pickup. Please come by during business hours. Thank you!",
    "context": "ticket",
    "channel": "email",
    "subject": "Your repair is complete"
  }'

Node.js

const res = await fetch("https://app.benchkey.com/api/v1/canned-responses", {
  method: "POST",
  headers: {
    Authorization: "Bearer bk_live_01J8X4_kvWz9nP3mRqTs7uYeBfGhDjLa",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    title: "Repair complete, ready for pickup",
    body: "Hi {{customer_name}}, your device is ready for pickup. Please come by during business hours. Thank you!",
    context: "ticket",
    channel: "email",
    subject: "Your repair is complete",
  }),
});
const cr = await res.json(); // HTTP 201

Response

Returns the created canned response object with HTTP 201 Created.

{
  "object": "canned_response",
  "id": 7,
  "title": "Repair complete, ready for pickup",
  "body": "Hi {{customer_name}}, your device is ready for pickup. Please come by during business hours. Thank you!",
  "context": "ticket",
  "channel": "email",
  "subject": "Your repair is complete",
  "created_at": "2025-11-03T09:14:00.000Z"
}

---

Update a canned response

PATCH /api/v1/canned-responses/:id

Updates one or more fields on an existing canned response. Only the fields you send are changed.

Scope required: canned_responses.write

Request body

Send any combination of the following fields:

Field	Type	Description
title	string	New display name (max 255 characters)
body	string	New message body (max 10,000 characters)
channel	string	email or sms
subject	string | null	Email subject line; send null to clear it; whitespace-only values are normalized to null

curl

curl -X PATCH "https://app.benchkey.com/api/v1/canned-responses/7" \
  -H "Authorization: Bearer bk_live_01J8X4_kvWz9nP3mRqTs7uYeBfGhDjLa" \
  -H "Content-Type: application/json" \
  -d '{"subject": "Your BenchKey repair is ready!"}'

Node.js

const res = await fetch("https://app.benchkey.com/api/v1/canned-responses/7", {
  method: "PATCH",
  headers: {
    Authorization: "Bearer bk_live_01J8X4_kvWz9nP3mRqTs7uYeBfGhDjLa",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ subject: "Your BenchKey repair is ready!" }),
});
const cr = await res.json();

Response

Returns the updated canned response object. Returns 404 if not found.

---

Delete a canned response

DELETE /api/v1/canned-responses/:id

Permanently deletes a canned response. This action cannot be undone.

Scope required: canned_responses.write

curl

curl -X DELETE "https://app.benchkey.com/api/v1/canned-responses/7" \
  -H "Authorization: Bearer bk_live_01J8X4_kvWz9nP3mRqTs7uYeBfGhDjLa"

Node.js

const res = await fetch("https://app.benchkey.com/api/v1/canned-responses/7", {
  method: "DELETE",
  headers: { Authorization: "Bearer bk_live_01J8X4_kvWz9nP3mRqTs7uYeBfGhDjLa" },
});
const result = await res.json();

Response

{
  "object": "canned_response",
  "id": 7,
  "deleted": true
}

Returns 404 if the canned response does not exist.

---

Error codes

HTTP status	Code	Meaning
400	missing_field	A required field (title or body) is absent or empty
400	invalid_id	:id is not a valid positive integer, or exceeds 2,147,483,647
400	invalid_query	A list filter parameter was supplied as an array or object instead of a single scalar value
400	invalid_context	context is not ticket or lead
400	invalid_channel	channel is not email or sms
400	invalid_field	A field value has the wrong type (e.g. body, title, or subject is not a string)
400	invalid_title	title is present but empty after trimming (PATCH only)
400	invalid_body	body is present but empty after trimming (PATCH only)
400	title_too_long	title exceeds 255 characters
400	body_too_long	body exceeds 10,000 characters
400	subject_too_long	subject exceeds 500 characters
400	no_fields	PATCH request contained no updatable fields
400	invalid_cursor	cursor is malformed
404	not_found	Canned response not found
422	create_failed	The canned response was not persisted, the upstream write failed
422	update_failed	The update could not be applied
422	delete_failed	The deletion could not be completed
403	insufficient_scope	API key lacks canned_responses.read or canned_responses.write

See Errors for the full error envelope format.