Fields

Macro objects have the following fields and links:

Fields

field name description
name name of the macro
description an optional description
enabled whether or not the macro is enabled for use
position placement in the UI
folders array of folders associated with this macro

Links

rel class embeddable? description
self macro no this macro
macro_actions macro_action no this macro's actions

List

Retrieve a paginated list of all macros.

GET https://yoursite.desk.com/api/v2/macros

Applicable Roles

Agent, Reporting Agent, Workflow Manager, Knowledgebase Manager, Content Manager, Business Manager, Administrative Manager, Administrator, Knowledgebase Adminstrator, and Billing Administrator

ETags

The Macros List endpoint has support for ETags. See ETag Caching for details.

Limits

The maximum per_page parameter value for this endpoint is currently 1000.

Example Curl Request

1
2
3
$ curl https://yoursite.desk.com/api/v2/macros \
    -u email:password \
    -H 'Accept: application/json'

Example Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
{
  "total_entries": 2,
  "page": 1,
  "_links": {
    "self": {
      "href": "/api/v2/macros?page=1&per_page=50",
      "class": "page"
    },
    "first": {
      "href": "/api/v2/macros?page=1&per_page=50",
      "class": "page"
    },
    "last": {
      "href": "/api/v2/macros?page=1&per_page=50",
      "class": "page"
    },
    "next": null,
    "previous": null
  },
  "_embedded": {
    "entries": [
      {
        "name": "Macro Macro",
        "description": "On repeat",
        "enabled": true,
        "position": 1,
        "folders": [
          "Sample Macros",
          "Favorites"
        ],
        "_links": {
          "self": {
            "href": "/api/v2/macros/1",
            "class": "macro"
          },
          "actions": {
            "href": "/api/v2/macros/1/actions",
            "class": "macro_action"
          }
        }
      },
      {
        "name": "Another Macro",
        "description": null,
        "enabled": true,
        "position": 2,
        "folders": [
          "Sample Macros",
          "Favorites"
        ],
        "_links": {
          "self": {
            "href": "/api/v2/macros/2",
            "class": "macro"
          },
          "actions": {
            "href": "/api/v2/macros/1/actions",
            "class": "macro_action"
          }
        }
      }
    ]
  }
}

Show

Retrieve a single macro.

GET https://yoursite.desk.com/api/v2/macros/:id

Applicable Roles

Agent, Reporting Agent, Workflow Manager, Knowledgebase Manager, Content Manager, Business Manager, Administrative Manager, Administrator, Knowledgebase Adminstrator, and Billing Administrator

Example Curl Request

1
2
3
$ curl https://yoursite.desk.com/api/v2/macros/:id \
    -u email:password \
    -H 'Accept: application/json'

Example Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
{
  "name": "Macro Macro",
  "description": "On repeat",
  "enabled": true,
  "position": 1,
  "folders": [
    "Sample Macros",
    "Favorites"
  ],
  "_links": {
    "self": {
      "href": "/api/v2/macros/1",
      "class": "macro"
    },
    "actions": {
      "href": "/api/v2/macros/1/actions",
      "class": "macro_action"
    }
  }
}

Create

Create a macro.

POST https://yoursite.desk.com/api/v2/macros

Applicable Roles

Knowledgebase Manager, Content Manager, Business Manager, Administrative Manager, Administrator, Knowledgebase Adminstrator, and Billing Administrator

Fields

field name description
name name of the macro
description an optional description
enabled whether or not the macro is enabled for use
folders array of folders associated with this macro

Example Curl Request

1
2
3
4
5
6
$ curl https://yoursite.desk.com/api/v2/macros \
    -u email:password \
    -X POST \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{"name":"Assign to Engineering"}'

Example Request Body

1
2
3
4
{
  "name": "Assign to Engineering",
  "description": "It's raining fire!"
}

Example Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
{
  "name": "Assign to Engineering",
  "description": "It's raining fire!",
  "enabled": true,
  "position": 1,
  "folders": [
    "Sample Macros",
    "Favorites"
  ],
  "_links": {
    "self": {
      "href": "/api/v2/macros/1",
      "class": "macro"
    },
    "actions": {
      "href": "/api/v2/macros/1/actions",
      "class": "macro_action"
    }
  }
}

Update

Update a macro.

PATCH https://yoursite.desk.com/api/v2/macros/:id

Applicable Roles

Knowledgebase Manager, Content Manager, Business Manager, Administrative Manager, Administrator, Knowledgebase Adminstrator, and Billing Administrator

Fields

Please see Create for details on the fields available for update.

Example Curl Request

1
2
3
4
5
6
$ curl https://yoursite.desk.com/api/v2/macros/1 \
    -u email:password \
    -X PATCH \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{"name":"Macro 5"}'

Example Request Body

1
2
3
{
  "name": "Macro 5"
}

Example Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
{
  "name": "Macro 5",
  "description": "On repeat",
  "enabled": true,
  "position": 1,
  "folders": [
    "Sample Macros",
    "Favorites"
  ],
  "_links": {
    "self": {
      "href": "/api/v2/macros/1",
      "class": "macro"
    },
    "actions": {
      "href": "/api/v2/macros/1/actions",
      "class": "macro_action"
    }
  }
}

Delete

Delete a macro.

DELETE https://yoursite.desk.com/api/v2/macros/:id

Applicable Roles

Knowledgebase Manager, Content Manager, Business Manager, Administrative Manager, Administrator, Knowledgebase Adminstrator, and Billing Administrator

Example Curl Request

1
2
3
$ curl https://yoursite.desk.com/api/v2/macros/1 \
    -u email:password \
    -X DELETE

Example Response

1
204 No Content

Action Fields

Macro Action objects have the following fields and links:

Common Fields

field name description
type The type of action to be performed; see below for details
value Value to set for the given type
enabled Whether or not the action is enabled; either true or false
created_at When the action was created
updated_at When the action was last updated

Action Types

action type input type description
set-case-description string Sets case description
set-case-labels array of strings Replaces all labels
append-case-labels array of strings Appends given labels to existing labels
set-case-priority integer Sets case priority from 1 to 10, 1 is lowest priority.
set-case-status string Sets case status to one of open, pending, resolved, or closed
set-case-agent integer Sets assigned agent to the given user_id
set-case-group integer Sets assigned group to the given group_id
append-case-article integer Appends the article with the given article_id to the case
set-case-quick-reply string Sets case's quick reply
set-case-outbound-email-subject string Sets case's outbound email subject
set-case-language string Sets case's language from the given language code. This language must be enabled for your site.
set-case-custom-N custom Sets the value of a custom field, where N is the name of a custom field, e.g. set-case-custom-internal-customer-id
set-case-note string Sets a note on the case

Links

rel class embeddable? description
self macro_action no this macro action
macro macro no macro for this action
group group no group for action type set-case-group
user user no user for action type set-case-agent
article article no article for action type append-case-article
custom_field custom_field no custom field for action type set-case-custom-N

List Actions

Retrieve a paginated list of all actions for this macro.

GET https://yoursite.desk.com/api/v2/macros/:macro_id/actions

Applicable Roles

Agent, Reporting Agent, Workflow Manager, Knowledgebase Manager, Content Manager, Business Manager, Administrative Manager, Administrator, Knowledgebase Adminstrator, and Billing Administrator

Example Curl Request

1
2
3
$ curl https://yoursite.desk.com/api/v2/macros/:macro_id/actions \
    -u email:password \
    -H 'Accept: application/json'

Example Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
{
  "total_entries": 2,
  "page": 1,
  "_links": {
    "self": {
      "href": "/api/v2/macros/1/actions?page=1&per_page=50",
      "class": "page"
    },
    "first": {
      "href": "/api/v2/macros/1/actions?page=1&per_page=50",
      "class": "page"
    },
    "last": {
      "href": "/api/v2/macros/1/actions?page=1&per_page=50",
      "class": "page"
    },
    "next": null,
    "previous": null
  },
  "_embedded": {
    "entries": [
      {
        "type": "set-case-description",
        "value": "From a VIP Customer",
        "enabled": true,
        "created_at": "2017-10-18T18:08:06Z",
        "updated_at": "2017-10-18T18:08:06Z",
        "_links": {
          "self": {
            "href": "/api/v2/macros/1/actions/1",
            "class": "macro_action"
          },
          "macro": {
            "href": "/api/v2/macros/1",
            "class": "macro"
          }
        }
      },
      {
        "type": "set-case-priority",
        "value": "10",
        "enabled": true,
        "created_at": "2017-10-18T18:08:06Z",
        "updated_at": "2017-10-18T18:08:06Z",
        "_links": {
          "self": {
            "href": "/api/v2/macros/1/actions/2",
            "class": "macro_action"
          },
          "macro": {
            "href": "/api/v2/macros/1",
            "class": "macro"
          }
        }
      }
    ]
  }
}

Show Action

Retrieve an action for this macro.

GET https://yoursite.desk.com/api/v2/macros/:macro_id/actions/:id

Applicable Roles

Agent, Reporting Agent, Workflow Manager, Knowledgebase Manager, Content Manager, Business Manager, Administrative Manager, Administrator, Knowledgebase Adminstrator, and Billing Administrator

Example Curl Request

1
2
3
$ curl https://yoursite.desk.com/api/v2/macros/:macro_id/actions/:id \
    -u email:password \
    -H 'Accept: application/json'

Example Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
{
  "type": "set-case-description",
  "value": "From a VIP Customer",
  "enabled": true,
  "created_at": "2017-10-18T18:08:06Z",
  "updated_at": "2017-10-18T18:08:06Z",
  "_links": {
    "self": {
      "href": "/api/v2/macros/1/actions/1",
      "class": "macro_action"
    },
    "macro": {
      "href": "/api/v2/macros/1",
      "class": "macro"
    }
  }
}

Update Action

Update an action.

PATCH https://yoursite.desk.com/api/v2/macros/:macro_id/actions/:id

Applicable Roles

Knowledgebase Manager, Content Manager, Business Manager, Administrative Manager, Administrator, Knowledgebase Adminstrator, and Billing Administrator

Fields

field name description
value Value to set for the given type.
enabled Whether or not the action is enabled. true or false.

Example Curl Request

1
2
3
4
5
6
$ curl https://yoursite.desk.com/api/v2/macros/:macro_id/actions/:id \
    -u email:password \
    -X PATCH \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{"enabled":false}'

Example Request Body

1
2
3
{
  "enabled": false
}

Example Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
{
  "type": "set-case-description",
  "value": "From a VIP Customer",
  "enabled": false,
  "created_at": "2017-10-18T18:08:06Z",
  "updated_at": "2017-10-18T18:08:06Z",
  "_links": {
    "self": {
      "href": "/api/v2/macros/1/actions/1",
      "class": "macro_action"
    },
    "macro": {
      "href": "/api/v2/macros/1",
      "class": "macro"
    }
  }
}