Skip to main content

How to Configure the REST API Call Bot Block

Updated

The API write-back can be customized by configuring the REST API Call bot block. Customizing the API write-back and creating an API REST block enables MSPbots to establish a seamless integration with your systems and allows us to retrieve relevant data so we can create reports that will help you monitor your performance, receive alerts, and perform necessary actions programmatically.

This article is a guide on how to configure the REST API Call bot block. It will use the Monitoring [Opened Tickets Today - Template] for_test bot as an example.

Prerequisites

  • A bot of the trigger type has been created.
  • A widget or dataset has been created to filter integration data according to your needs.
  • The API documentation for the corresponding integration is available, and APIs that meet your requirements have been identified.

Required Permissions

You need admin-level permissions to follow this guide perform the operations.

 

Setting up the bot block

  1. Go to Bots on the MSPbots menu. 

    MSPbots bots
  2. Open the bot where you need to add a REST API Call block. Let's use the bot Monitoring [Opened Tickets Today - Template] for_test as an example.

    my bot
  3. When the selected bot opens, go to the Design tab. If another window opens, close it. 

    bot design
  4. In the trigger block, configure the widget or dataset that you have already created as a data source according to your needs. Review the For detailed configuration information of the trigger block, refer to Set up the bot trigger.



  5. Hover over the horizontal line between the blocks. Click the add icon , select Add a Block, and select the new block. 

    add a block
  6. Type REST API Call in the search bar and click REST API Call.

    rest api call
  7. Next, hover over the ellipsis for the REST API Call block and select Edit.

    edit block
  8. (Optional) If you are configuring a REST API from an existing integration with MSPbots, select the integration from the Integration dropdown list in the REST API Call window. Otherwise, do not configure this parameter and proceed to the next step.  

    API_rest _call_block_new_UI.jpg



  9. Next, select the HTTP method used when calling the API. The commonly used methods when using this block are post and delete. If you want to learn examples of these two methods, refer to Examples of commonly used HTTP Methods when using the REST API Call block.
    • GET - Retrieves information from the database without modifying or adding data. The results are consistent regardless of how many operations are performed.
    • POST - Submits data and adds operations to the server.
    • PUT - Modifies the existing data on the server. This is similar to POST except that it modifies instead of adding. 
    • PATCH - Used to apply partial modifications to an existing resource
    • DELETE - Removes a specific resource and deletes a record in a database.
    • OPTIONS - Before using any of these methods, you can check the browser request to ensure the server will accept it. 

      API_rest _http_method.jpg

  10. Enter the URL of the API that will receive requests.
    Example: h    ttps://mspbotstest.halopsa.com/api/Tickets 

    API_rest _call_block_URL.jpg
  11. Next, set up the Headers and input the relevant Key and Value. Headers are additional information included in the API call, which may include authentication tokens and content types. 
    Because our bots already support authentication information by default, you don't need to add any extra authentication information to REST API Call block.

    API_rest_call_headers.jpg
    You can click the +Add link to add more keys and values and click the Delete icon to remove existing ones. 

    API_rest_call_add-remove.jpg

  12. Set up the Query Params. and enter data for the Key and Value fields. 

    API_rest_call_block_query_params.jpg

    URL query parameters refer to additional parameters or information passed to the server through key-value pairs attached to the URL. Query parameters are commonly used for filtering, sorting, pagination, or passing other optional parameters. They are placed after the question mark symbol (?) in the URL and key-value pairs are separated by an equals sign (=), while multiple query parameters are connected with an ampersand (&). By utilizing URL query parameters, we can pass additional parameters in the API call and customize the results requested.
  13. Configure the Body settings. The parameters available for the request body method are none, form-data, x-www-form-urlencoded, json, and xml.  

    API_rest_call_body.jpg

    The request body is the HTTP request data that is included in a POST or PUT request. It is only configured when the method is POST or PUT. This data can be in different formats such as JSON, XML, or form data. These parameters are usually used for submitting forms, uploading files, or sending other types of data.
  14. Click Next to configure other blocks, and click Finish when done.
  15. Click Save to keep your settings.

Examples of commonly used HTTP Methods when using the REST API Call block

  • POST- Create tickets to the Halo app with the filtered data that meets the criteria.

*For more detailed information, refer to: How to Create or Modify Halo Tickets using a Rest API-based Bot.

Parameter Field  Description
url Fill in the interface address for creating or modifying tickets in Halo: https://{host}/api/Tickets, for example: https://mspbotstest.halopsa.com/api/Tickets.
Integration Halo
method post
headers Can be left empty.
params
  1. Click body.
  2. Select json. 
  3. Input parameter fields in the JSON body, using the following columns as an example to create tickets.
  4. [ 
      { 
       "actioncode":0, 
       "dateoccurred":"2023-12-15T14:35:55.618Z", 
       "summary":"{job_title}", 
       "details":"{user_name}", 
       "status_id":"2", 
       "tickettype_id":"{update_source}" 
      } 
    ]

  5. About the example:

    • The "actioncode", "dateoccurred", "summary", "details", "status_id", "tickettype_id" are from the official API documentation of Halo, https://halo.haloservicedesk.com/apidoc/resources/tickets. These fields are generally obtained from the official API documentation of the integration.

    • The {job_title}, {user_name}, {update_source} are from the data you added in the widget or dataset in the Trigger block. Note that the format of the field must be {Field}.

 

  • DELETE - Delete tickets in the Halo app that meet the filtering criteria.

Parameter Field  Description
url Fill in the interface address to delete tickets in Halo: https://{host}/api/Tickets, for example: https://mspbotstest.halopsa.com/api/Tickets/{id}.
Integration Halo
method delete
headers Can be left empty.
params
  1. Click body.
  2. Select json. 
  3. Input parameter fields in the JSON body, using the following columns as an example.
  4. [ 
      { 
       "id":"{ticket_id}",
       "reason":"{delete_reason}" 
      } 
    ]

  5. About the example:

    • The "id", "reason" are from the official API documentation of Halo, https://halo.haloservicedesk.com/apidoc/resources/tickets. These fields are generally obtained from the official API documentation of the integration.

    • The {ticket_id}, {delete_reason} are from the data you added in the widget or dataset in the Trigger block. Note that the format of the field must be {Field}.
 

 

Related articles