Use the following built-in functions to get information on the results of an integration.

Is API integration execution successful?

isApiExecutionSuccessful is used to determine whether execution of an API integration was successful. Returns "true" if execution was successful; returns "false" if execution was unsuccessful.

This function is evaluated based on a variable that’s set behind the scenes after execution of the code located in the Transform Result Script section of the API integration. So, never use isApiExecutionSuccessful in code in the Transform Result Script section. This is too early in the flow, so the function will always return false. Instead, use isApiExecutionSuccessful in the Post-Process Code of the Integration interaction.

This function always returns the result of the most recent API integration that was executed. Keep this in mind when you have a dialog that contains multiple API integrations.

Example

var isApiExecutionSuccessful = botContext.isApiExecutionSuccessful();

This method is commonly used together with getApiStatusCode (discussed below), for example:

// check to see if API was executed
var isApiExecutionSuccessful = botContext.isApiExecutionSuccessful();
if(isApiExecutionSuccessful){
  var apiStatusCode = botContext.getApiStatusCode();
  botContext.printDebugMessage("API Execution Successful with Status Code: "+apiStatusCode);

  if(apiStatusCode == "200"|apiStatusCode == "201"|apiStatusCode == "203"){
    // request was successful
    botContext.printDebugMessage("All is well.");
  }else{
    // request was not successful
    botContext.printDebugMessage("Something went wrong!");
  }

}

You can also define rules in an interaction based on the result of an API integration.

Get API integration status code

getApiStatusCode is used to retrieve the HTTP status (response) code returned from execution of an API integration. The returned code might indicate success or failure, and, in the case of a failure, it can provide insight into the type of error that occurred.

This method always returns the result of the most recent API integration that was executed. Keep this in mind when you have a dialog that contains multiple API integrations.

Example

var apiStatusCode = botContext.getApiStatusCode();

This method is commonly used together with isApiExecutionSuccessful; see that entry above for an example.

Get API integration results count

Most commonly used to check whether an API integration returned any results at all, and how many. If no results are returned, you should display an error message or redirect to a failover message.

For example, assume you are using the KnowledgeBase feature to create an FAQ bot. If the user’s query doesn’t return any results, you might want to respond with another message that provides some guidance.

Example

In the below example, faqIntegration is the name of the API integration, title is the custom data field mapping name, and count is the parameter that gives you the actual count.

var results = botContext.getBotVariable('faqIntegration.title.count');
if (results < 1) {
      botContext.sendMessage('Sorry, I was not able to find any notes for this contact.');
}

Get file type

Use the getFileType function to retrieve the file type (PDF, JPEG, etc.) of the file being uploaded to an external file share via a File integration.

Before the upload to the external share occurs, the file type is automatically set to the bot's botContext. If desired, you can use this function to retrieve the file type and pass it as a parameter via the File integration.

Example

// get the file type
var fileType = botContext.getFileType();

Get file caption

In some channels, such as Web messaging, the consumer is offered a way to caption (label) the file that they are uploading (via a File integration), for example, "John Doe's paystub."

If desired, you can use this function to retrieve the file caption and pass it as a parameter via the File integration. If no caption is available, this function returns “__EMPTYTEXT__”.

Example

// get the file caption
var fileCaption = botContext.getFileCaption();