Canned Responses

Overview

The Canned Responses API allows you to manage pre-defined quick replies for your organization.

Permissions

Role	List	Create	Update	Delete	Use
Admin	Yes	Yes	Yes	Yes	Yes
Manager	Yes	Yes	Yes	Yes	Yes
Agent	Yes	No	No	No	Yes

List Canned Responses

Retrieve all canned responses for your organization.

GET /api/canned-responses

Query Parameters

Parameter	Type	Description
category	string	Filter by category (e.g., greeting, support)
search	string	Search in name, content, and shortcut
active_only	string	Set to "true" to only return active responses

Response

{
  "status": "success",
  "data": {
    "canned_responses": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "Welcome Message",
        "shortcut": "welcome",
        "content": "Hello {{contact_name}}! Thank you for reaching out. How can I help you today?",
        "category": "greeting",
        "is_active": true,
        "usage_count": 42,
        "created_at": "2024-01-15T10:30:00Z",
        "updated_at": "2024-01-15T10:30:00Z"
      },
      {
        "id": "550e8400-e29b-41d4-a716-446655440001",
        "name": "Business Hours",
        "shortcut": "hours",
        "content": "Our business hours are Monday to Friday, 9 AM to 6 PM EST.",
        "category": "support",
        "is_active": true,
        "usage_count": 28,
        "created_at": "2024-01-15T11:00:00Z",
        "updated_at": "2024-01-15T11:00:00Z"
      }
    ]
  }
}

Get Canned Response

Retrieve a single canned response by ID.

GET /api/canned-responses/{id}

Response

{
  "status": "success",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Welcome Message",
    "shortcut": "welcome",
    "content": "Hello {{contact_name}}! Thank you for reaching out. How can I help you today?",
    "category": "greeting",
    "is_active": true,
    "usage_count": 42,
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  }
}

Create Canned Response

Create a new canned response.

POST /api/canned-responses

Request Body

{
  "name": "Welcome Message",
  "shortcut": "welcome",
  "content": "Hello {{contact_name}}! Thank you for reaching out. How can I help you today?",
  "category": "greeting"
}

Fields

Field	Type	Required	Description
name	string	Yes	Display name for the response
content	string	Yes	The response text (supports placeholders)
shortcut	string	No	Quick-access code for slash commands
category	string	No	Category for organization

Response

{
  "status": "success",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Welcome Message",
    "shortcut": "welcome",
    "content": "Hello {{contact_name}}! Thank you for reaching out. How can I help you today?",
    "category": "greeting",
    "is_active": true,
    "usage_count": 0,
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  }
}

Update Canned Response

Update an existing canned response.

PUT /api/canned-responses/{id}

Request Body

{
  "name": "Updated Welcome Message",
  "shortcut": "hi",
  "content": "Hi {{contact_name}}! Welcome to our support. How may I assist you?",
  "category": "greeting",
  "is_active": true
}

Fields

Field	Type	Description
name	string	Display name for the response
content	string	The response text
shortcut	string	Quick-access code
category	string	Category for organization
is_active	boolean	Whether the response is active

Delete Canned Response

Delete a canned response.

DELETE /api/canned-responses/{id}

Response

{
  "status": "success",
  "data": {
    "message": "Canned response deleted"
  }
}

Track Usage

Increment the usage counter for a canned response. This is typically called automatically when a response is used in chat.

POST /api/canned-responses/{id}/use

Response

{
  "status": "success",
  "data": {
    "message": "Usage incremented"
  }
}

Categories

The following categories are supported:

Value	Label
greeting	Greetings
support	Support
sales	Sales
closing	Closing
general	General

Tip

You can use any string as a category value. The categories listed above are pre-defined in the UI, but you can create responses with custom categories via the API.

Placeholders

Canned response content can include placeholders that are replaced with actual values when used:

Placeholder	Description
{{contact_name}}	Contact’s profile name
{{phone_number}}	Contact’s phone number

Note

Placeholder replacement is handled client-side when inserting the response into the chat. The API stores and returns the raw content with placeholders intact.

Error Responses

400 Bad Request

{
  "status": "error",
  "message": "name and content are required"
}

404 Not Found

{
  "status": "error",
  "message": "Canned response not found"
}

409 Conflict

{
  "status": "error",
  "message": "Canned response with this name already exists"
}