# Use Custom Integrations to get WhatsApp flow images

{{<tags>}}

In this guide, you'll learn how to set up a **Custom Integration** in your **WhatsApp flows** to send user-uploaded images to an endpoint you define.

> Disclaimer: Configuring API requests requires a solid understanding of APIs and authentication methods. We recommend involving a developer or a tech-savvy individual to assist or handle this process.

## Before you begin

To follow this guide, you should be familiar with setting up **Custom Integrations** and using them in flows. If you're not yet familiar, we **strongly recommend** reading the following guides first:

  -  {{< newtab href="/guides/api_external_connection_wa_flows" >}}Custom integrations{{< /newtab >}}: to better understand how to create an integration. 
  -  {{< newtab href="/guides/api_external_connection_wa" >}}Configure your flows to perform API requests{{< /newtab >}}: to learn how to use the API integration within your flows.
  
> Important: The image URLs you receive in your **WhatsApp flow** are typically hosted on **AWS S3** and are time-sensitive. These URLs usually expire after a predefined period of **15 minutes**. Ensure you process or retrieve the images within this time-frame.

## Creating the integration

1. In the left sidebar of **Customer Engagement** product, click on **Integrations**.
2. Click the **New Integration** button.
   {{<img src="/images/illustrations/api_external_connection/02_open_new_integration.gif" alt="Open New Integration" width="100%" class="border border-slate-300 rounded-md">}}

3. Fill in the **Integration name** (required) and optionally add a **Description** and a **URL of the logo that identifies the integration**.
4. Select the authentication scheme for the action you'll create. **Currently, only API key authentication is supported**.
   {{<img src="/images/illustrations/customer_engagement/img_integration_name_and_auth.png" alt="setting name and authentication scheme" width="90%" class="border border-slate-300 rounded-md">}}
   Click **Save and continue** to proceed with the authentication section.

## Configuring authentication

Set up authentication to be used by the **actions**:

1. **Adding Authentication fields**: Define the fields required by your APIs for authentication:

{{<img src="/images/illustrations/customer_engagement/img_integration_auth_fields.png" alt="adding an authentication field" width="90%" class="border border-slate-300 rounded-md">}}

**Fill in the following fields**:
   
   * **Authentication name**: (Optional). A custom name to easily recognize the authentication later.
   * **Identifier**: (Required). The **Identifier** will be used to reference an authentication field inside API requests. It should only contain lowercase letters, digits, and underscores ('_'). It must not start with a digit or underscore, nor end with an underscore. 
   * **Type**: Choose **text** or **password** (passwords are **end-to-end encrypted** in our systems.). 
   * **Required**: Mark this option to make the authentication field **Required** when creating a credential.
   * Review all the fields and click on the **Save** button.

> Note: At this stage, you are not setting any actual API key; you are merely defining the fields that will contain those keys. **Please do not enter any credentials at this point**.

Click **Next** to proceed with the **Configure a test request** step.

2. **Configure a test request**: Set up a simple request to test the credentials defined in the authentication fields. We recommend using a request that only retrieves information to avoid accidentally making changes to your system data during testing.

**Fill in the test request**:

   * **Type of request**: Select from: ``GET``, ``POST``, ``PUT``, ``DELETE``, ``OPTIONS``, ``CONNECT``, ``TRACE`` or ``PATCH``. We recommend using a method that only retrieves information (e.g., ``GET``) to avoid unintended modifications to your system data.
   * **Endpoint**: Enter your endpoint **URL**.
   * **Query Params**: If required, set the **key-value** pairs for the query parameters of your test request.
   * **Headers**: If required, enter the **key-value** pairs for the headers of your test request.

   {{<img src="/images/illustrations/customer_engagement/img_integration_test_request.png" alt="configuring a test request" width="90%" class="border border-slate-300 rounded-md">}}
   
   Click on **Save and continue** to proceed to set the **Credentials**.

3. **Setting Credentials and Testing**: Click the **Add credentials** button to set the credential that will contain value for your authentication field. A modal will appear where you can set your new credential's name and **enter actual value for the authentication field**.

   {{<img src="/images/illustrations/customer_engagement/img_integration_add_credentials.png" alt="add credentials step" width="80%" class="border border-slate-300 rounded-md">}}

   The **Credential name** you set here will help you easily recognize it later when using it in **Truora's Flow builder**.

   {{<img src="/images/illustrations/customer_engagement/img_integration_credential_fields.png" alt="setting a credential" width="45%" class="border border-slate-300 rounded-md">}}

Click **Save and continue**. The system will test your credentials against the test request you configured in **step 2**. Ensure that the status code and the response body are correct:

   {{<img src="/images/illustrations/customer_engagement/img_integration_credential_testing.png" alt="testing in progress" width="40%" class="border border-slate-300 rounded-md">}}

   {{<img src="/images/illustrations/customer_engagement/img_integration_test_credential_ok.png" alt="test response success" width="40%" class="border border-slate-300 rounded-md">}}

If everything is correctly **set and tested**, click **Continue to Actions**.

{{<img src="/images/illustrations/customer_engagement/img_integration_continue_to_actions.png" alt="test response success" width="90%" class="border border-slate-300 rounded-md">}}

## Creating the action for your integration

Now we'll create an action named **post_image_url** to receive the user's image and make a POST request to an endpoint with the image URL in the request's Body.

Click the **Add action** button. A new view will appear with a sequence of steps:

{{<img src="/images/illustrations/api_external_connection/13_actions_section_empty.png" alt="credentials table" width="80%" class="border border-slate-300 rounded-md">}}

### Create post_image_url action

1. **Action name and description**: 
   - **Name**: (Required). Set a name to easily recognize the action when using **Truora's Flow builder**. For our example, the action will be named **post_image_url**.
   - **Description**: (Optional). A description for easier recognition later.

   {{<img src="/images/illustrations/customer_engagement/img_integration_actions_name.png" alt="new action's name" width="90%" class="border border-slate-300 rounded-md">}}
   
   Click **Save and continue** to proceed to **define inputs**.

2. **Define inputs**: Define the required inputs for the request. For this example, the input will be the **User Image** provided by the user in the **WhatsApp flow**. We'll mark it as **Required**.

   {{<img src="/images/illustrations/customer_engagement/img_integration_define_input.png" alt="action input" width="90%" class="border border-slate-300 rounded-md">}}

**Fill in the following fields**:
   
   * **Input name**: (Required). Enter a custom name to easily recognize it in your **WhatsApp flow**.
   * **Key**: (Required). This is the actual **key** used to perform your request. Be sure to write this correctly. It should only contain lowercase letters, digits, and underscores ('_'), and must not start with a digit or underscore, nor end with an underscore.
   * **Type**: (Required). Select the **type** of your input. For our use case we'll select ``string``.
   * **Required**: Mark this to make the input field **required** when using the **action**.
   * Review all the fields and click on the **Save** button.

Click **Next** to proceed to **Configure your API Request**.

3. **Configure API Request**: Fill in the required fields for the API request.

**Set request**:

   * **Type of request**: We'll select ``POST`` for this specific use case.
   * **Endpoint**: Enter the endpoint **URL**.
   * **Query Params**: If required, set the **key-value** pairs for the query parameters of your request (none are used in this example).
   * **Body**: For this specific use case, select Body ``json`` type and find the previously created input to configure the body to include the user image. For example:

      {{<code lang="json" lang_title="JSON Body">}}
      {"image":"{{.input_data.user_image}}"}
      {{</code>}}
      
      
      {{<img src="/images/illustrations/customer_engagement/img_integration_set_api_request.gif" alt="Set Request" width="90%" class="border border-slate-300 rounded-md">}}

   * **Headers**: Enter the required **key-value** pairs for the headers of your request (none are used in this example).

   Once you've configured your API request, click **Save and continue** to proceed to **Test your API Request**.

4. **Test API request**: Here you can test the created request by setting a test value for the input defined earlier and selecting the credential. We recommend using a credential pointing to a test account or user.

   {{<img src="/images/illustrations/customer_engagement/img_integration_testing_request.png" alt="test action step" width="90%" class="border border-slate-300 rounded-md">}}

- Click **Test and continue** and review the response:
   
   {{<img src="/images/illustrations/customer_engagement/img_integration_save_action.png" alt="test action step" width="90%" class="border border-slate-300 rounded-md">}}

- Click on **Save action** to be redirected to the initial actions section:

{{<img src="/images/illustrations/customer_engagement/img_integration_finish.png" alt="test action step" width="90%" class="border border-slate-300 rounded-md">}}

- Click on **Finish integration** to complete the process. Your new integration should now appear in the general integrations view:

 {{<img src="/images/illustrations/customer_engagement/img_integration_connected.png" alt="our new integration!" width="35%" class="border border-slate-300 rounded-md">}}

## Configure the Integration in your Flow

For this example, configure a simple flow like the one shown below:

{{<img src="/images/illustrations/customer_engagement/img_integration_example_flow.png" alt="Get Image Test Flow " width="100%" class="border border-slate-400 rounded-md">}}


1. In the **Open question** box **Properties**:
   - **Title**: Enter a recognizable title. A variable with this title will store the user's answer, which, in this case, is the uploaded image's URL.
   - **Message**: The message requesting the image to the user.
   - **Expected response type**:  Select **Image** as the expected response type.
   {{<img src="/images/illustrations/customer_engagement/img_integration_open_question.png" alt="Open Question Properties" width="50%" class="border border-slate-400 rounded-md">}}

2. In the **Custom integration** box **Properties**:
   - **Integration**: Select your created integration.
   - **Credential**: Select the credential created in your integration.
   - **Action**: Select the Action created in your integration.
   - **Inputs**: Click **Add Inputs** and select the **Variable** associated with the **Open Question** Box.
   {{<img src="/images/illustrations/customer_engagement/img_integration_flow_block.gif" alt="Integration Block Properties" width="90%" class="border border-slate-400 rounded-md">}}

## Testing the Completed flow

To test the flow:

1. **Save and publish** the flow.
2. Click on **Test Conversation**.
3. Select **Your user sends it** and click **Continue**.
4. Review the **Chatbot phone** and **Message** that triggers the conversation, then click **Continue**.
5. Test your conversation:
    - Click on **Open conversation** to directly open and test the WhatsApp conversation with the **Chatbot**.
    - Or click **Copy link** and use it to test the conversation on any device.

   {{<img src="/images/illustrations/customer_engagement/img_integration_flow_testing.gif" alt="Integration Block Properties" width="90%" class="border border-slate-400 rounded-md">}}

### Example Interaction with the Chatbot:

   {{<img src="/images/illustrations/customer_engagement/img_integration_whatsapp_interaction.png" alt="Get Image WhatsApp Interaction" width="30%">}}

### Example Caught Request after Interaction:

Once the user uploads the image during the WhatsApp flow, the endpoint receives a POST request that should look like the one configured during the **Custom Integration**:

{{<code lang="json" lang_title="JSON Payload Received">}}
  {
     "image": "https://demo.s3.amazonaws.com/open-question/IDP00aa0fa54XXXXXXXX"
  }
{{</code>}}

>Note: The S3 image URL will expire 15 minutes after it is generated.

**Image URL opened in browser:**

   {{<img src="/images/illustrations/customer_engagement/img_integration_image_in_browser.png" alt="S3 Image in Browser" width="80%" class="border border-slate-400 rounded-md">}}

**Image URL opened in browser - expired after 15 minutes:**

   {{<img src="/images/illustrations/customer_engagement/img_integration_url_expired.png" alt="S3 Image Expired" width="80%" class="border border-slate-400 rounded-md">}}