Make an HTTP request to an external API endpoint. The results of the call can be stored as form data.

This action type has several settings.

Request type

Which method to use for the HTTP request to the external API. Currently, the available options are "GET", "POST", and "PUT".

Default: "GET", meaning that an HTTP GET request will be sent.

URL

The URL of the external API endpoint.

Note: The URL can be dynamically generated from form data. To include the value associated with a given key, use the syntax {{key}}. For example, to access a URL based on an order number stored as form data associated with the key "order-number", you can write a URL like https://api.example.com/order/{{order-number}}.

Default: None. You must specify the URL to use.

Timeout (seconds)

How many seconds to wait for the HTTP request to time out. If no response is received before the specified time elapses, the request will time out and no form data assignments will occur.

This must be set to an integer no less than 1 (one second) and no greater than 120 (two minutes).

Be careful when adjusting this value. Longer timeouts will allow slower operations to complete but can mean that users will be waiting for longer. Operations that take a long time to complete may not be a good fit for API calls made from flows.

Default: "4", meaning that API calls that do not return within four seconds will time out and no form data assignments will occur.

Headers to send

Headers to send as part of the HTTP request. For each header, specify the key and the value.

Note: A value can be dynamically generated from form data. To include the value associated with a given key, use the syntax {{key}}. For example, to send a header with key "x-api-version" and the form data value associated with the key api-version, set the header key to x-api-version and the value to {{api-version}}.

Header values also have access to the reserved form data key $secrets. This is a map of names to values for your organization's secrets. For example, to use an OAuth 2.0 Bearer Token stored as a secret named "bearer", set the header key to Authorization and the value to Bearer {{$secrets["bearer"]}}.

Default: None, meaning no extra headers will be sent.

Payload type

This option only available for request types "POST" and "PUT".

What format the API request payload is in. There are multiple options described below.

1. JSON (Default)
   Send the request payload as a JSON object. If this option is selected, the payload must also be specified in the "Data to send" field, which defaults to {} for an empty JSON object.
    
   Note: The payload can be dynamically generated from form data. To include the value associated with a given key, use the syntax {{key}}. For example, to create a payload using a product number stored as form data with the key "product-number", you might write a payload like { "product": {{product-number}}, "action": "update" }.

2. URL-Encoded Form
   Send the request payload as a URL-encoded form. If this option is selected, the payload must also be specified as a set of key/value pairs in the "Form to send" field, which defaults to an empty pair.
    
   Note: A value can be dynamically generated from form data. To include the value associated with a given key, use the syntax {{key}}. For example, to send a form item with key "product" and the form data value associated with the key product-number, set the key to product and the value to {{product-number}}.

This API call has side-effects

If checked, the product assistant will prevent the user from backing through this node so that it will not be triggered multiple times. We recommend you strongly consider checking this box if the API call you are making is not idempotent.

Default: Unchecked, meaning the user is not prevented from backing through this node and the API request can easily be made multiple times.

Response type

The expected format of the HTTP response body. Currently, the only available options are "JSON" and "String".

If response type is set to "JSON", then Mavenoid will attempt to parse the response body as a JSON string. If the body is invalid JSON, no form data assignments will occur. If instead the response type is set to "String", then Mavenoid will not attempt to parse the HTTP response body.

Default: JSON, meaning that Mavenoid will attempt to parse the response body as a JSON string and invalid JSON will prevent form data assignments from occurring.

Allowed statuses (comma separated)

A set of HTTP status codes to allow. You must specify the first digit of each code as a number but the other digits can be replaced with "x" as a wildcard.

If the API response has an HTTP status code that does not match any of the listed statuses, no form data assignments will occur.

For example, to allow all success statuses and also the status code 418 but reject all other statuses, you could set the values to 2xx and 418.

Default: "2xx", meaning that only success statuses are allowed and other response statuses will prevent form data assignments from occurring.

Form data assignments

What form data to set based on the API response. This data can be used by other nodes later in the flow, will be included in the conversation transcript, and is viewable on the agent dashboard if the conversation includes a live chat.

Like a write data node, you can add any number of form data assignments for this action to perform. For each one, you must specify the key to update and the value to set it to. Note that all values are treated as already being in double-curly-braces, meaning that to reference the key name you would enter "name" instead of {{name}}.

All normal form data keys and all global reserved form data keys are available. Additionally, the following limited reserved form data keys are available, allowing you to set values dynamically based on the response from the API server:

• $status: The numeric HTTP status code of the API's response.

• $headers: A JSON array of the HTTP headers included in the API's response. These can be accessed using JSON array syntax and are case-sensitive. For example, to refer to the value of the "Content-Language" header, you would write $headers["Content-Language"].

• $body: The body of the API's response. The format depends on the response type. If it is "String", the value of $body will be a string containing the entire response body. If the response type is instead "JSON", the value of $body will be a JSON array. You can use JSON array syntax to refer to values within such a body. For example, if the response body is { "order": { "id": "4123724", "status": "processing" } } then the value of $body["order"]["status"] will be processing.

Note that any of the following events will prevent form data assignments from occurring:
 

1. The HTTP request does not receive a response before the specified timeout duration passes.

2. The HTTP response has a status code that does not match any of the allowed statuses.

3. The response type is set to "JSON" and the HTTP response body is not valid JSON.
    

The conversation will still proceed along the flow, but this action will make no changes to form data. This means that the easiest way to account for API errors is usually by using the "Fallback" option on later read data nodes.

Default: None, meaning no form data will be set.

Delay in seconds

How long to wait after reaching this node before making the API call.

This provides a grace period during which the user can reach this node and then go back to an earlier point in the flow, such as because they have changed their mind or they realized they have provided incorrect information and want to update it. If the user backs through the node before the delay has elapsed, the API call will not be made, preventing superfluous or unintended calls.

Note: If there are form data assignments in place, the delay will be set to "0" automatically as later nodes in the flow may use that form data and therefore rely on the API call to be made before they can be rendered properly.

Default: "0", meaning the API call is made immediately when the user reaches this node.

Outbound IP Address

The Call External API actions use a pool of dynamic IP addresses. For a static IP address, use the Custom JavaScript action.