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
`page`	integer	Page number (default: 1)
`limit`	integer	Items per page (default: 20)
`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,
        "buttons": [
          {
            "id": "track_order",
            "title": "Track Order",
            "type": "reply"
          }
        ],
        "created_at": "2024-01-15T10:30:00Z",
        "updated_at": "2024-01-15T10:30:00Z"
      }
    ],
    "total": 1,
    "page": 1,
    "limit": 20
  }
}

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,
    "buttons": [
      {
        "id": "track_order",
        "title": "Track Order",
        "type": "reply"
      }
    ],
    "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",
  "buttons": [
    {
      "id": "track_order",
      "title": "Track Order",
      "type": "reply"
    }
  ]
}

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
`buttons`	array	No	Optional interactive buttons to attach to the response

Button Fields

Field	Type	Required	Description
`id`	string	Yes	Unique button identifier
`title`	string	Yes	Button label (max 20 characters for reply buttons)
`type`	string	No	Button type: `reply` (default), `url`, `phone`, `voice_call`
`url`	string	No	Target URL (for `url` buttons)
`phone_number`	string	No	Target phone number (for `phone` buttons)
`ttl_minutes`	integer	No	Button TTL in minutes (for `voice_call` buttons)

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,
    "buttons": [
      {
        "id": "track_order",
        "title": "Track Order",
        "type": "reply"
      }
    ],
    "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,
  "buttons": []
}

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
`buttons`	array	Interactive buttons configuration

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.

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

Response

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

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