External API settings

External API nodes still work, but for new flows we recommend using the Actions node instead for greater configurability.

Click on any external API node in the assistant builder to edit it and access its settings.

Operation name

The name displayed on the node within the assistant builder. It has no effect on the node's operation.

We recommend using a descriptive name to keep the flow more readable.

Request configuration

Options for configuring the HTTP request that Mavenoid will make to the external API.

Request type

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

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 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.

Bearer token

If specified, what value to use for an OAuth 2.0 Bearer Token. For example, if you set the value "YOUR_TOKEN", the API request will include the header Authorization: Bearer YOUR_TOKEN.

This is only required if it is used by the API you are accessing.

Default: None, meaning no bearer token header is sent with the HTTP request.

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.

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.

Payload type

This option only available for request type "POST".

What format the API request's payload is in. Currently, the only available option is "JSON".

Default: JSON, meaning that the request's payload is formatted as JSON.

Data to send

This option only available for request type "POST".

The API request payload to send.

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" }.

Default: "{}", an empty JSON object.

Response configuration

Options for handling the HTTP response received by Mavenoid from the external API.

Allowed statuses (comma separated)

A comma-separated list 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, if you wanted to allow all success statuses and also the status code 418 but consider all other statuses to be errors, you could write your list as 2xx,418.

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

Response type

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

If response type is set to "String", then Mavenoid will not attempt to parse the HTTP response body. 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.

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.

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 node to perform. For each one, you must specify the key to update and the value to set it to.

Unlike a write data node, external API nodes can set values dynamically based on the HTTP response from the external API. Three special variables are available:

• $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 node 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.