Tell us how we can improve docs for you.
BotPenguin updates
What's NewGo to dashboard

API Component | Request Information

It allows your chatbot to connect with external systems and respond dynamically based on API responses.

API Component – Create & Manage API-Based Chat Flow

The API component allows your chatbot to connect with external systems and respond dynamically based on API responses. You can route users to different messages or flows depending on the API response code (such as 200, 400, or others).

This is useful for:

  • Fetching real-time data (orders, bookings, user details)

  • Validating user input via backend systems

  • Triggering conditional flows based on API success or failure

  • Integrating CRMs, ERPs, payment gateways, or custom services

Where to Find the API Component

  1. Log in to your BotPenguin Dashboard

  2. Open your bot

  3. Go to Edit Chat Flow

  4. From Add Chat Component, select API

  5. Drag and drop it into your chat flow

Understanding the API Component Layout

1. API Block in Chat Flow

The API block appears in the flow editor with response tags such as:

  • 200 – Success response

  • 400 – Error or failed request

  • Others – Any response code not explicitly handled

Each response code can be connected to a different next message or flow.

2. Customize Tab (Right Panel)

Choose API

Select the API you want to use from the dropdown.

APIs must be configured first using Configure APIs.

Response Code Mapping

For each response code, configure:

Response Code

Examples:

  • 200 – Successful API response

  • 400 – Client or validation error

  • Others – Any unexpected response

Go to Next Message

Choose the next message, component, or flow to continue the conversation.

This allows you to:

  • Show success messages for valid responses

  • Display error messages when the API fails

  • Redirect users to fallback flows when needed

Configure APIs

Click Configure APIs to:

APIs Management Screen Overview

The APIs Management page displays all configured APIs in a list format.

Available Actions

  • Search by API name – Quickly find an API

  • Add API – Create a new API

  • Edit (⚙️) – Modify an existing API

  • Delete (🗑️) – Remove an API

  • Checkbox Select – Bulk actions (if enabled)

API List Columns

  • API Name – Friendly name used in chat flows

  • Method – GET / POST

  • URL – Endpoint URL

  • Actions – Edit or delete API

Adding a New API

Click Add API to open the Configure API screen.

1. Configure API

This screen allows you to configure JSON-based APIs and prepare them for use inside chat flows.

Basic API Details

API Name

Enter a recognizable name for your API. Example: Get Order Status

Method

Choose the HTTP method:

  • GET

  • POST

API URL

Enter the complete API endpoint URL.

Description (Optional)

Add a short description explaining what the API does.

Testing the API

Click the Test button to:

  • Trigger the API instantly

  • View the API response

  • Validate request configuration before using it in chat flows

The response appears in the Response panel on the right.

Parameters Tab

Use this tab to pass query parameters.

Fields

  • Key – Parameter name

  • Value – Static value or variable

Click Add another field to add more parameters.

Example:

Headers Tab

The Headers tab allows you to define HTTP headers that are sent along with your API request. Headers are commonly used for authentication, authorization, and content formatting.

This section is essential when working with secure or third-party APIs.

When to Use Headers

Use headers when:

  • The API requires authentication tokens

  • You need to pass API keys

  • The API expects specific content types

  • Authorization details must not be exposed in the URL or body

Header Fields

Key

Enter the header name.

Common examples:

  • Authorization

  • Content-Type

  • x-api-key

  • Accept

Value

Enter the header value.

Examples:

You can also use bot variables in header values if required.

Add Another Field

Click Add another field to add multiple headers.

This is useful when an API requires more than one header (e.g., Authorization + Content-Type).

Add Authentication Field

Click Add authentication field to quickly insert commonly used authentication headers.

This helps:

  • Reduce manual errors

  • Standardize authentication setup

  • Speed up API configuration

Typically used for:

  • Bearer tokens

  • API keys

  • OAuth-based headers

Advanced Options (Headers)

The Advanced Options section allows additional control over header behavior, such as:

  • Dynamic value handling

  • Advanced authentication configurations (if applicable)

  • Custom header rules for special APIs

  • Use this tab to pass request headers.

Testing Headers

After adding headers:

  1. Click Test

  2. Verify the response in the Response panel

  3. Ensure the API returns a valid response code and data

If authentication fails, recheck:

  • Header key spelling

  • Token validity

  • Content-Type format

Body Tab (For POST APIs)

Used when the API requires a request body.

  • Supports JSON format

  • Can include bot variables

  • Ideal for form submissions or data creation

Example:

Manage API Responses

This section allows you to define how the chatbot handles API responses.

  • Identify response keys from JSON

  • Save response values into variables

  • Use these variables later in:

    • Messages

    • If/Else branches

    • Conditions

    • API-based routing

Third Party Integration

Third Party Integration Tab

The Third Party Integration tab allows you to connect your API configuration with supported external platforms directly from BotPenguin. This enables secure, authenticated data exchange without manually managing complex authorization headers or tokens.

What This Tab Is Used For

Use this tab when:

  • You want to integrate with supported platforms like Zoho CRM

  • The external service requires account-level authentication

  • You prefer a one-click connection instead of manual API token handling

  • You want to sync chatbot data with third-party tools

Tab Layout Overview

The tab displays a list of available third-party services with the following columns:

Name

Shows the name and logo of the supported integration platform Example: Zoho CRM

Status

Indicates the current connection state:

  • Not Connected – Integration is not yet linked

  • Connected – Integration is successfully authenticated

Action

Provides the action button based on status:

  • Connect – Start the authentication and linking process

  • (Once connected, the action updates accordingly)

Connecting a Third-Party Service

To connect a service:

  1. Open the Third Party Integration tab

  2. Click Connect next to the desired platform

  3. Complete the authentication steps (login & permission grant)

  4. Return to BotPenguin once authentication is successful

  5. Status will update to Connected

Using Third-Party Integrations in Chat Flows

Once connected:

  • API calls can securely access the third-party platform

  • Data can be fetched, created, or updated in external systems

  • Chatbot interactions can trigger CRM updates or fetch records

Example use cases:

  • Create a lead in Zoho CRM

  • Fetch customer details from CRM

  • Update contact or deal status during chat

Response Panel

The Response panel on the right displays:

  • API test responses

  • Confirmation of successful third-party data access

  • Errors (if authentication or permissions fail)

Click Test to verify the integration after connecting.

Save Configuration

After connecting and testing:

  • Click Save to apply the integration

  • The connected service becomes available for use in chat flows

2. API Logs

The API Logs tab provides a detailed record of all API requests and responses triggered within your chatbot flows. It helps you monitor API behavior, debug issues, and verify whether APIs are working as expected.

What API Logs Are Used For

Use API Logs to:

  • Track every API call made by the chatbot

  • Check API response status codes

  • Debug failed or unexpected API responses

  • Verify successful API execution in live conversations

  • Troubleshoot integration or authentication issues

API Logs Overview

When you open the API Logs tab, you’ll see:

Search by Status Code

A search bar that allows you to filter logs based on response status codes such as:

  • 200 – Successful requests

  • 400 – Client-side errors

  • 500 – Server-side errors

This helps you quickly locate failed or successful API calls.

Logs Area

This section displays the history of:

  • API requests triggered by chat flows

  • Corresponding API responses

  • Status codes returned by each API

If no APIs have been triggered yet, an informational message is shown indicating that logs will appear once APIs are used.

What Information Is Logged

Each API log typically includes:

  • API name

  • Request timestamp

  • Response status code

  • Request and response details

  • Success or failure indication

This information is useful for identifying where and why an API may not be working as expected.

Common Use Cases

  • Debugging: Identify why an API is returning an error

  • Testing: Confirm that APIs work correctly after configuration

  • Monitoring: Ensure APIs are responding consistently in live bots

  • Support: Share log details with technical teams for faster resolu

Using the API in Chat Flow

Once configured, the API becomes available inside the API Chat Component.

Steps:

  1. Open Edit Chat Flow

  2. Drag and drop API component

  3. Select your API from Choose API

  4. Configure response-based routing:

    • 200 → Success flow

    • 400 → Error flow

    • Others → Fallback flow

  • Search existing APIs.

  • To add new, Click on Add API Button.

  • Set request URL and method (GET/POST)

  • Add headers (Authorization, Content-Type, etc.)

  • Define request parameters or body

  • Map API response data to bot variables

Once configured, the API becomes available in the Choose API dropdown.

Example Use Case

Order Status Check

  • API returns 200 → Show order details

  • API returns 400 → Ask user to recheck order ID

  • API returns Others → Show “Something went wrong” message

Best Practices

  • Always handle Others response to avoid dead-end conversations

  • Use meaningful success and error messages after each response

  • Test APIs using the Test button before installing the bot

  • Combine API blocks with If/Else Branches for advanced logic

Related Components

  • If/Else Branch – Apply logic based on API variables

  • User Reply – Collect input before triggering API

  • Redirect – Move users to another flow after API response

Advanced Settings (API)

The Advanced tab for the API component controls message timing and provides network details required for secure API communication. These settings are especially useful when integrating with protected or internal systems.

Add Delay Before Message

Adds a delay (in seconds) before the API step is executed or displayed in the chat flow.

Why use this?

  • Prevents abrupt transitions

  • Gives users time to read the previous message

  • Makes API-triggered responses feel more natural

Best practices:

  • 1–2 seconds → Smooth conversational pacing

  • 3+ seconds → Pause before critical actions (payments, validations)

IP Whitelisting

If your API endpoint requires IP whitelisting, you must allow requests from the following IP address:

Use this when:

  • Your server blocks unknown outbound requests

  • Your API is protected by firewall or security rules

  • You are integrating with enterprise or internal systems

💡 Make sure this IP is added to your server’s allowlist to avoid failed API calls.

How API Response Codes Work

The API component can route the conversation based on response status codes:

  • 200 → Success flow

  • 400 → Error or validation failure flow

  • Others → Fallback or exception handling flow

This allows you to design different chatbot paths based on real-time API results.

Best Practices for API (Advanced)

  • Always whitelist the BotPenguin IP before testing

  • Add a short delay for better UX

  • Handle error (400) and others paths gracefully

  • Log API responses when debugging complex flows

FAQs:

Do I need technical knowledge to use the API component?

Basic understanding of APIs is helpful, but BotPenguin provides a UI-based setup for easy integration.

What happens if no response code is matched?

The flow will stop. Always configure the Others response to avoid this.

Can I reuse the same API in multiple flows?

Yes, once configured, an API can be reused across different chat flows.

Can I store API response data?

Yes, API responses can be saved in variables and used later in the conversation.

What happens if the API fails?

If no response code is mapped, the flow stops. Always configure the Others response.

PreviousRequest InformationNextSend Information

Last updated

Was this helpful?