Introduction

File integrations support the ability of consumers to upload files that you require.

Get oriented to this feature and learn about approaches.

Important notes

• You can use any REST endpoint that can accept an upload.
• Use of credentials isn't supported.
• The response body of an API request via a File integration can’t be retrieved.
• Before the upload to your external file share occurs, the file type (PDF, JPEG, etc.) is automatically set to the bot's botContext. If desired, use the getFileType function to retrieve the file type and pass it as a parameter via the File integration.
• In some channels, such as Web messaging, the consumer is offered a way to caption (label) the file that they are uploading, for example, "John Doe's paystub." If desired, use the getFileCaption function to retrieve this caption and pass it as a parameter via the File integration.

Add a File integration

1. Open the bot, and click Integrations in the upper-left corner.
2. Configure the integration settings (required fields are marked with asterisks):
   • Integration Name: Enter the name of integration. Enter a name that's meaningful (it describes well the integration's purpose), concise, and follows a consistent pattern. This helps with organization, and it makes it easier for bot developers to work with the integration during bot development.
   • Response Data Variable Name: Enter the name of the variable that gets populated with the response from the API. You can enter any value here. In practice, this value plays no role since the response body can’t be retrieved in this type of integration.
   • Integration Type: Select File.
   • Method: Select the type of HTTP request method. PUT and POST are industry standards and commonly used.
   • URL: Enter the request target, i.e., the URL for your external upload service that can accept the file stream.
   • Request Headers: Add any message headers to include in the request.
   • Request Parameters: Add the request parameters to pass in the URL’s query string.
   • Post Body: Enter the payload to send.
   • Transform Result Script: If applicable, use this section to write JavaScript code that transforms the raw result (typically in JSON format), so you can use the information in the bot's dialog. For more on this, see Transform an API result.
   • Custom Data Fields: Add the fields that will store the result data in key/value pairs. Users who are tasked with creating bots can use and display this data in interactions by referencing these fields.
3. Click Save.

Example

The integration automatically includes the uploaded file as a binary body when making the POST request to the URL.

An example of what it would look like using an API platform like Postman is below.