External Web Call

Within SmartFlows, use the External Web Call module to set up an external web call to send and receive information. An HTTP request allows you to interact with applications and code outside of SmartFlows. 

 

 

The external web call has two events under the action dropdown that trigger transitions.

 

Transition Triggers

Success

A connection was made.

 

Fail

The URL does not successfully return or has an error. 

 

Response variables

Once the external web call returns a valid JSON object, select your data and create your variable.  

 

Note: This is the response someone might expect if they used dot notation (i.e. array[0].first_name) to access the contents of an item in an array.

[

   {

        “_id”: “5c86c534307bb30000jkjaa”,

       “first_name”: “John”,

        “last_name”: “Smith”,

        “pin”: 7777,

    }

]

 

 

Fields:

 

Headers

Use HTTP headers to pass additional information to the API endpoint along with the request. 

 

  • They are typically used to add metadata to the request. 
  • The accepted headers are based on what is configured in the API endpoint and should be present in the API documentation.
  • Authorization/key 

 

Username and Password

These fields support basic authentication in the event that it is required for access to the API endpoint. 

 

  • Token-based authentication can also be supported by adding a custom header to the request.

 

Method

Indicate the action for the URL to perform per the API configuration. 

 

These methods are supported by SmartFlows but depend upon the specific API configuration. 

 

Note: Currently, POST, GET, and  PUT are available to support submitting information and extracting information, respectively. More methods will be added soon.

 

 

Timeout

Set the timeout duration in seconds that SmartFlows should wait for the API response before failing the request. 

 

  • The default is set to 10 seconds. Most requests will be returned in less than a second. 
  • A best practice is to keep this to a short time window to prevent consuming capacity unnecessarily. 

 

URL of Service

Enter the URL of the API endpoint here. 

 

  • Variables can be used inside URLs to target specific objects.

 

Response Variables

Extract JSON/XML responses into named variables. 

 

  • When a request is sent, the entire response is collected in a variable called EXTCALL_6.responsebody
  • User-configured response variables, however, offer more granularity and allow the user to extract a subset of the response. For example, if the user is interested in extracting a value named orderStatus from their API, they can add a response variable with that name to the external web call action. The name must be a literal match to the name sent by the API.
  • The extracted data is then stored in a SmartFlows variable of the same name. This variable can then be invoked in later parts of the flow using the following syntax:

$EXTCALL_6.orderStatus

 

This variable also appears in the Available Variables section of the action configuration panel in subsequent actions. There it can be used in messages, text-to-speech, analytics, and other web calls.

 

Variables

The external web call action creates several variables.

 

  1. User-configured response variables
    • Any key in the API that matches a named response variable on the web call action will allow its corresponding value to be stored in the response variable. 

 

  1. responsebody
  2. The entire response from the external API.
  3. statuscode
  4. The response code generated from the API (e.g. 200 for success, 400 for bad request, 404 not found, etc.)