Mavenoid help center

Mavenoid help center

  • Admin
  • Flows
  • Agent dashboard

›Reference

Get started

  • Intro to flows
  • Tutorial - Create a flow for live support
  • Tutorial - Create a flow for troubleshooting
  • Tutorial - Create a flow for FAQs

Learn more

  • Understand the types of nodes
  • Working with symptoms and solutions
  • Working with backtracks and choice lists
  • Understand potential solutions
  • Understand escalation
  • Understand search
  • Understand step-by-step guides
  • Understand canvas notes
  • Understand form data
  • Understand markup
  • Understand secrets
  • Understand flow components
  • Understand conditions
  • Understand translations
  • Understand flow feedback
  • Best practices for writing flows

How-to guides

  • Preview nodes and flows
  • Embed images and files
  • Embed videos
  • Receive conversation transcript emails
  • Set a flow image
  • Work with step-by-step guides
  • Add canvas notes
  • Copy and paste nodes
  • Create and embed flow components
  • Work with conditions
  • Configure flow feedback
  • View and manage flow feedback
  • Export, import, and copy flows
  • Set flow visibility
  • Manage translations
  • Create a live support node
  • Create an external API node
  • Start the user on different nodes based on the embedding page
  • Dynamically populate a choice list form field

Reference

  • Text formatting
  • Live support settings
  • Actions settings
  • External API settings
  • Form field types
  • Reserved form data
  • Markup expressions and operators
  • Supported languages
  • Glossary of terms

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.

External API node 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.

Last updated on 2/23/2022
← Actions settingsForm field types →
  • Operation name
  • Request configuration
    • Request type
    • URL
    • Bearer token
    • Timeout (seconds)
    • Payload type
    • Data to send
  • Response configuration
    • Allowed statuses (comma separated)
    • Response type
    • Form data assignments
Help center
AdminFlowsAgent dashboard
Product
Self-serviceLive supportWhy Mavenoid?PricingGet a demoTry it free
Learn
Customer storiesBlogWebinarsHelp centerROI calculator
Company
About usCareersPressContact us
© Mavenoid AB 2023 • Privacy policy