# Canned Responses

> API reference for managing canned responses

Source: https://docs.soosh.io/reference/api/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

```json
{
  "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

```json
{
  "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

```json
{
  "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

```json
{
  "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

```json
{
  "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

```json
{
  "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

```json
{
  "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

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

### 404 Not Found

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

### 409 Conflict

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