Prep work: Prepare your endpoints and schemas

Before getting started building a workflow, make sure you have a strong understanding of which APIs you would like to call from within it. It’s important to have a clear understanding of which APIs you will call including the:

• Domain
• Path
• HTTP Method
• Request Body Schema (if relevant)
• Response Body Schema

Step 1: Define your API domain and headers

Visit Settings ⇒ Integrations ⇒ API endpoints to configure your custom APIs.

You’ll want to start off by configuring your API domain and headers, which will become reusable by any endpoints you want to create. Click the Manage Domains button and add your domain for your APIs. You’ll also want to set up headers you want to attach to your API requests. Common headers may include:

• Authorization
• Content-Type

Headers are simply key-value pairs so you’ll want to include the key and value as if you were making a raw request. For example, a bearer token for Authorization might have a value Bearer {token_value} .

You can add as many domains as you’d like.

Step 2: Define your endpoints

Now that you’ve defined your domain(s), you can setup custom endpoints that you can make requests to. Click Configure new endpoints to start.

You’ll build your endpoint by providing important information such as:

• name: the name you want to give to this endpoint
• method: the HTTP request method
• domain: the domain you want to use for this endpoint (selected from the list you created above)
• path : the path you want make a request to (including query parameters)
  • If you’d like to define a path with URL parameters or query parameters that are dynamic values, you can do so by defining templates within your path.
  • For example, if you define your path as /orders/{{order_id}} , order_id will be replaced by its corresponding variable in the automation that hits this endpoint. If order_id has a value of “12345” in the automation, your path will become /orders/12345. Refer to Step 3A for more information on how these variables are parsed.

Click Save API endpoint to save your endpoint.

Step 3: Use your endpoints in a workflow

Now that you’ve built your endpoint(s), you’re ready to build your workflow that uses it!

Assuming you’ve built one before, you’ll build a workflow like any other. Create your path selection criteria, and start adding steps.

Step 3A: Parse necessary information

Before your Custom API step, you’ll want to make sure that your workflow has all the information it needs. For example, you may need to look up email via our Zendesk Data Lookup step first, or you might need to use Parse variables to understand the customer’s sentiment.

All of these pieces of information (referred to as variables from here) are added to conversation context.

For example, if you looked up email from Zendesk Data Lookup, a new variable, email, will be made available that corresponds to the email value found the lookup.

You’ll only need to do the above if you’re making a request that requires dynamic information (e.g. email, order id).

Step 3B: Custom API step

Now that Cal has all the information you need in its context, you can set up a Custom API step.

Add a Custom API step and you first will have to select the API you would like Cal to request. You should see a list of endpoints that you created earlier.

Request Body

Next, if you selected an endpoint that uses a request body (POST, PUT, PATCH), you’ll have the chance to input your request body in JSON format. You can include static values or you can include variables that you have parsed in previous steps in the workflow.

You can define a dynamic value using the following syntax: {{variableName: type}} where where type refers to int, string, boolean, or float .

Note: The type is optional with the default being string , so {{variableName}} would represent a string value.

• ❗ An important note is that whatever dynamic variables your request body includes must match the name of a variable made available to the context of the workflow in an earlier step. By defining your schema in this way, Cal can dynamically generate a payload for your request based on the information parsed earlier in the workflow.
• ❗Note the syntax of the below request. Field names must be wrapped in “”. String values must be wrapped in “”. Variable place holders should not be wrapped in “”.

For example, imagine you are making a POST request and define your schema as such:

{
	"name": "Cal", 
	"email": {{email}},
	"inquiry": {
			"message": {{message}}
			"orderId": {{order_id: int}}
		}
}

You’ll need to ensure that email, message , and order_id were variables either created via a Parse variables step or one of our other data lookup steps (or even another custom API step!)

Output Variables (optional)

Finally, you’ll need to define any output variables you might want to add to your context for future steps. Output variables are created by mapping new context variables to your request response.

Say you had a response that looked something this:

{
	"status": "closed", 
	"order_id": "5678", 
	"fulfillment": {
		"tracking_number": "90322321312"
	}
}

You can define a new variable and map it to the corresponding value in your request response. You define the variable name and how Cal should assign the variable. Some possible mappings might include:

Any variables added here will be available to other steps later in your workflow.

Example

An example Custom API step can be found below: