Skip to content
Whatomate

Canned Responses

Overview

Section titled “Overview”

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

Permissions

Section titled “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

Section titled “List Canned Responses”

Retrieve all canned responses for your organization.

Terminal window
GET /api/canned-responses

Query Parameters

Section titled “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

Section titled “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

Section titled “Get Canned Response”

Retrieve a single canned response by ID.

Terminal window
GET /api/canned-responses/{id}

Response

Section titled “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

Section titled “Create Canned Response”

Create a new canned response.

Terminal window
POST /api/canned-responses

Request Body

Section titled “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

Section titled “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

Section titled “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

Section titled “Update Canned Response”

Update an existing canned response.

Terminal window
PUT /api/canned-responses/{id}

Request Body

Section titled “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

Section titled “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

Section titled “Delete Canned Response”

Delete a canned response.

Terminal window
DELETE /api/canned-responses/{id}

Response

Section titled “Response”
{
  "status": "success",
  "data": {
    "message": "Canned response deleted"
  }
}

Track Usage

Section titled “Track Usage”

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

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

Response

Section titled “Response”
{
  "status": "success",
  "data": {
    "message": "Usage incremented"
  }
}

Categories

Section titled “Categories”

The following categories are supported:

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

Placeholders

Section titled “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 |

Error Responses

Section titled “Error Responses”

400 Bad Request

Section titled “400 Bad Request”
{
  "status": "error",
  "message": "name and content are required"
}

404 Not Found

Section titled “404 Not Found”
{
  "status": "error",
  "message": "Canned response not found"
}

409 Conflict

Section titled “409 Conflict”
{
  "status": "error",
  "message": "Canned response with this name already exists"
}