API Block - Call External APIs from Your Chatbot Flow

Overview

The API Block lets your chatbot call any external REST API mid-conversation, capture the response, and route the flow based on success or failure. Use it to look up orders in your database, verify OTPs, fetch shipment status, check account balances, or integrate any system that exposes an HTTP endpoint.

When the bot reaches an API block, it sends the configured HTTP request, waits for the response, extracts fields from the JSON or XML body into variables, and then follows the success branch (HTTP 2xx/3xx) or the failure branch (HTTP 4xx/5xx). The next blocks in the flow can use the extracted variables in messages, conditions, or subsequent API calls.

Where to Find It

1. Open your chatbot in Studio
2. Drag the API block from the left sidebar onto the canvas
3. Connect it from any previous block
4. Double-click the block to configure it

The API block has two output connections: Success (top/default) for 2xx and 3xx responses, and Failure (secondary) for 4xx and 5xx responses.

Configuration

Step 1: Set the Request URL and Method

Field	Description
URL	The full endpoint, for example https://api.example.com/orders/{order_id}
Method	HTTP verb: GET, POST, PUT, PATCH, or DELETE

You can insert any variable captured earlier in the flow using {variable_name} syntax (single curly braces). Variables are resolved at runtime before the request is sent.

Step 2: Add Query Parameters (Optional)

For GET requests, use Query Parameters to append key-value pairs to the URL. Each row takes a Key and a Value. Variable substitution works in both fields.

Key: customer_email       Value: {email}
Key: include_archived     Value: false

Step 3: Configure Headers

Add custom HTTP headers under the Headers section. Each row takes a Key and a Value.

Key: Content-Type         Value: application/json
Key: Accept               Value: application/json
Key: X-Custom-Header      Value: {tenant_id}

Content-Type is auto-detected when you choose a body format, but you can override it.

Step 4: Add Authentication

The API block supports three authentication modes. Choose one that matches your target API.

Auth Type	Fields	How It Is Sent
Basic Auth	Username, Password	Sent as Authorization: Basic <base64>
Bearer Token	Bearer Token	Sent as Authorization: Bearer <token>
Custom Header	Header Name, Header Value	Sent as <Name>: <Value> (for API keys, custom schemes)

Note: For APIs that use x-api-key or similar, choose Custom Header and set Name to x-api-key and Value to your key. You can also store the key in a variable and reference it as {api_key}.

Step 5: Build the Request Body

For POST, PUT, and PATCH requests, configure the body in the Body section. Pick the format:

Format	Use When
JSON	Most modern REST APIs
XML	Legacy SOAP or XML endpoints
None	No body needed (typical for GET and DELETE)

Write the raw JSON or XML in the body editor. Variables can be inserted inline:

{
  "order_id": "{order_id}",
  "customer": {
    "name": "{name}",
    "email": "{email}"
  },
  "total": {amount}
}

Step 6: Map Response to Variables

Under Save Response to Variables, define how to extract fields from the JSON response into flow variables.

JSON Path	Variable Name
result.user.name	user_name
data.orders[0].status	order_status
items[*].id	item_ids

Supported path syntax:

• Dot notation for nested objects: result.user.email
• Array index: items[0].name
• Wildcard array extraction: items[*].id returns all IDs as an array
• Root field: status or message

The extracted values are available in all subsequent blocks as {variable_name}.

Step 7: Submit and Save

Click Submit in the block modal, then save the flow using Save Changes in the top bar.

How the Response Is Handled

Success Path (HTTP 2xx / 3xx)

1. Variables from Save Response to Variables are populated
2. The flow follows the Success output connection

Failure Path (HTTP 4xx / 5xx)

1. Response variables may or may not populate depending on the error body
2. The flow follows the Failure output connection
3. Use this branch to send a friendly error message or retry

Timeout

Requests time out after 30 seconds. If your API is slow, consider breaking the work into two steps or using a webhook-driven async pattern.

Testing in the API Playground

Every API block call is logged and available in the API Playground inside Studio. For each test run you can see:

• The fully resolved URL, method, and headers
• The request body that was sent
• The HTTP status code received
• The full response body
• The variables that were extracted

Use the playground to debug template variables, authentication, and JSON path mappings before shipping the flow.

Best Practices

• Store secrets in variables, not in the block config. Capture API keys from environment-specific settings and pass them in via variables so the same flow works in staging and production
• Always configure the Failure branch. Never assume the API call succeeds. Send a fallback message like "We could not retrieve your order right now. Please try again later."
• Keep request bodies small. Do not send entire chat histories or large payloads unless the API needs them
• Validate response fields before using them. If order_status may be missing, add a Condition block after the API call to check {order_status} before using it in a message
• Use descriptive variable names. user_email is better than val1 because it is easier to debug in the Playground and the conversation log
• Set Content-Type explicitly when sending JSON, so strict APIs accept the request

Common Use Cases

Order Lookup

Customer provides an order ID, bot fetches status from your e-commerce backend.

• Method: GET
• URL: https://api.myshop.com/orders/{order_id}
• Auth: Bearer Token
• Response Map: data.status to order_status, data.tracking_url to tracking_url

OTP Verification

Bot collects a 6-digit code, calls your verification endpoint, and branches based on result.

• Method: POST
• URL: https://api.myapp.com/verify-otp/
• Body: {"phone": "{phone}", "code": "{otp_code}"}
• Response Map: verified to otp_verified
• Use a Condition block next: if {otp_verified} == true continue, else ask again

CRM Contact Sync

Push collected contact details to your CRM when the user completes qualification.

• Method: POST
• URL: https://api.crm.com/v1/contacts/
• Auth: Custom Header (x-api-key: {crm_key})
• Body: {"name": "{name}", "email": "{email}", "source": "chatbot"}

Troubleshooting

Request fails with 401 Unauthorized

1. Check that the auth type matches what the API expects
2. For Bearer tokens, do not include the word Bearer in the token field. The block adds it automatically
3. For Custom Header auth, verify the header name exactly matches the API docs (case-sensitive for some APIs)
4. Inspect the request in the API Playground to confirm the header is being sent

Variables are not populating from the response

1. Open the API Playground and inspect the actual response body
2. Confirm the JSON path matches the response structure. Paths are case-sensitive
3. For arrays, use items[0].field for a single value or items[*].field for all values
4. If the response is XML, make sure you set the body format correctly. JSON paths work on the parsed XML as well

Flow follows the failure branch even when the API works

1. Check the HTTP status code in the API Playground. Some APIs return 201 (Created) on POST which is still success
2. If the API returns 200 but with an error in the body, use a Condition block after the success branch to inspect the response field

Request times out

1. The timeout is fixed at 30 seconds. If your API regularly takes longer, the API may not be a good fit for real-time chat
2. Consider moving the slow work to a background job and polling for result, or use a webhook to be notified when ready

Template variables appear as raw {variable} in the request

1. Confirm the variable was set by an earlier block in the flow
2. Check the variable name spelling (case-sensitive)
3. Use the Conversation Log to inspect which variables are actually populated at that point

Next Steps

• Webhook Block - Receive inbound HTTP calls to trigger or resume a flow
• Conversation End Block - End conversations with a restart button
• Studio Overview - Explore all block types and flow builder features