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.

System status