Macros automate tasks and help agents streamline customer support. While macros are typically created by Admins and available for everyone (global) or restricted to certain groups; agents can also create their own personal macros for their needs. There may come a time when it's necessary to convert a personal macro into a global macro accessible to all agents within the Zendesk instance. Let's explore together how to achieve this using the Zendesk API.

This article covers the following topics: 

• Before you begin
• Get a list of active macros via the API
• Identify/Locate a personal macro within the JSON result
• Obtain the macro ID
• Update a macro via the API

Before you begin

• JSON Formatting: When you run an API call in your browser, the result is returned in JSON format and it's not formatted very nicely to start with. We recommend that you install a browser extension that can format the JSON automatically so it's a lot easier to read. 
  • Check out the Chrome extension JSON Viewer here. We use this one ourselves! P.S It's free. 
• API Platform: In order to run the API call to update the macro(s) you'll also need a platform that can run the call for you to the Zendesk system. Some developers like to use the Terminal built into their computers. Other's like to utilise platforms that can do this. We recommend using Postman. 
  • Postman - Available for free. You'll need to create an online account to use it. You can either use the web browser interface or download a desktop application to utilise. 
    • Download Postman for desktop
• Authentication for Postman: You can either use your standard Zendesk email/password login or utilise an API key. 
  • See the Zendesk guide here: Generating a new API key
• Zendesk API: You can find all of the Zendesk API references here - Zendesk API Reference Documentation 

Get a list of active macros via the API

The first part of converting personal macros is to first find the record of the macros in question through the API. In order to do this we will use the List Active Macros API call. This will pull a record of all macros which are currently available on the Zendesk account in the browser. 

• List active macros API call

1. Open your Zendesk in a new browser window to ensure you are currently logged into Zendesk. 
2. In the same browser window you just opened, paste in the following URL: https://{subdomain}.zendesk.com/api/v2/macros/active
   • REMEMBER TO REPLACE {subdomain} with your Zendesk account subdomain
3. Press enter on your keyboard to load the new URL. 
4. You will now see all of your macros displaying in JSON format within the browser window. 

Identify/Locate a personal macro within the JSON result

Now that you have successfully pulled a list of all the active macros inside your Zendesk account via the API, we can locate the personal macros inside the results from here. 

Each macro has a restriction setting applied to it which determines whether the macro is available for everyone, restricted to a group or a personal agent macro. We will now need to locate the macros which have the specific personal agent restriction. Here are examples below of what the different restriction types look like inside the JSON results. 

Restriction Type	Example
Global macro
Shared macro
Personal macro

As part of this guide, we've located our test personal macro in the JSON body in the example below:

Obtain the macro ID

After you've found the personal macro(s) you're looking for, we'll need to grab the macro ID so we can use it in the last step to make the update to the macro. 

When you're looking at the JSON for the macro, each macro has a visible ID associated with it. The macro ID is visible below the macro URL. 

1. Locate the macro ID inside the JSON for the personal macro in question
2. Copy & Paste the macro ID so you have it handy for the next step
   • Alternatively, leave this window open with the JSON results so you can copy and paste from it

Update a macro via the API

Once we've completed all of the above steps, the last thing to do from here is to now make the update to the macro via the API. Enter Postman!

• Update Macro API

1. Open Postman and create a new collection with the + button so you can save your API call it. You can also name your collection if you like.
   • Note: A collection is basically a folder in postman
2. Inside your new collection, Click on the Authorization tab and select "Basic Auth" from the type drop-down.
3. Input your email and password.
   • Alternatively: If you are using the API key method, it will need to look like this when you input it. The password = API token 
     • 
4. Add a new request to your new collection and set the following:
   • PUT request - https://{subdomain}.zendesk.com//api/v2/macros/{macro_id}
   • REPLACE {subdomain} with your Zendesk account subdomain
   • REPLACE {macro_id} with the macro ID you collected in the last step
   • RAW BODY: 

     • {
        "macro": {
          "restriction": null
        }
       }

   • Click Send

If the update is successful, the status will display as 200 OK and show your results below. 

You can then also scroll through the body results to double-check that the restriction has been updated to the null value. Alternatively, you can also open the macro settings inside your Zendesk Admin Centre and see if the macro in question is now set as a global macro visible to all agents. 

Example from inside the Zendesk admin centre:

Considerations:

• The above walkthrough utilises the API call to update 1 macro at a time. If needed, there is an API call that can allow you to update many macros at once. 
• To update many macros - please utilise the API call Update Many Macros which can be found here.