API Integration

API Integration tools let your agent call external REST APIs during conversations. This enables real-time data fetching, action execution, and seamless integration with your existing business systems.

---

Overview

With API Integration, your agent can:

• Fetch live data - Check order status, account balances, inventory levels
• Perform actions - Create tickets, update records, send notifications
• Integrate systems - Connect to CRMs, ERPs, custom backends

User: "What's the status of my order #12345?"
        ↓
Agent calls: GET /api/orders/12345
        ↓
API returns: { "status": "shipped", "tracking": "1Z999..." }
        ↓
Agent responds: "Your order #12345 has shipped!
                 Here's your tracking number: 1Z999..."

---

Creating an API Tool

Step 1: Basic Information

Field	Description	Example
Name	Tool identifier (used internally)	get_order_status
Description	When to use this tool (critical!)	"Retrieves the current status of a customer order. Use when customer asks about their order, shipment, or delivery."

Description is Critical

The description tells the AI when to use this tool. A vague description leads to the tool being used incorrectly or not at all. Be specific about the scenarios where this tool applies.

Step 2: Endpoint Configuration

Field	Description	Example
Method	HTTP method	GET, POST, PUT, DELETE
URL	Endpoint URL	https://api.yourcompany.com/orders/{order_id}
Headers	Request headers	Authorization: Bearer

Using Path Parameters

Include parameters in the URL with curly braces:

https://api.example.com/customers/{customer_id}/orders/{order_id}

The agent will extract values from the conversation to fill these parameters.

Step 3: Request Configuration

Headers

Add any required headers:

Content-Type: application/json
Authorization: Bearer {{api_key}}
X-Request-ID: {{$uuid}}

Using Variables

• - References credentials stored securely
• - Generates a unique request ID
• - Current Unix timestamp

Query Parameters

For GET requests with query strings:

Parameter	Value
status
limit	10

Request Body (POST/PUT)

For requests with a body, define the JSON schema:

{
  "type": "object",
  "properties": {
    "customer_id": {
      "type": "string",
      "description": "The customer's unique identifier"
    },
    "message": {
      "type": "string",
      "description": "The support message content"
    }
  },
  "required": ["customer_id", "message"]
}

Schema Descriptions Matter

The description field in your schema helps the agent understand what data to collect. Write descriptions as if explaining to a human.

Step 4: Response Handling

Configure how the agent interprets API responses:

Field	Description
Success codes	HTTP codes that indicate success (e.g., 200, 201)
Response mapping	How to extract useful data from responses

---

Example: Order Status Tool

Configuration

Name: check_order_status

Description:

Retrieves the current status of a customer order including shipping information and estimated delivery date. Use when a customer asks about their order status, where their package is, or when it will arrive.

Method: GET

URL: https://api.yourcompany.com/v1/orders/{order_id}

Headers:

Authorization: Bearer {{orders_api_key}}
Content-Type: application/json

Path Parameters:

Parameter	Description
order_id	The order number provided by the customer

Expected Response

{
  "order_id": "ORD-12345",
  "status": "shipped",
  "items": [
    { "name": "Widget Pro", "quantity": 2 }
  ],
  "shipping": {
    "carrier": "UPS",
    "tracking_number": "1Z999AA10123456784",
    "estimated_delivery": "2025-01-20"
  }
}

Conversation Example

Customer: "Hi, I ordered something last week. Order number is 12345. Where is it?"

Agent: [Calls check_order_status with order_id="12345"]

"I found your order #12345! It's currently shipped and on its way to you. It's being delivered by UPS with tracking number 1Z999AA10123456784. The estimated delivery date is January 20th. Would you like me to explain how to track it?"

---

Example: Create Support Ticket

Configuration

Name: create_support_ticket

Description:

Creates a new support ticket in the helpdesk system. Use when a customer reports an issue that cannot be resolved immediately, needs to be escalated, or requests a callback.

Method: POST

URL: https://api.yourcompany.com/v1/tickets

Headers:

Authorization: Bearer {{helpdesk_api_key}}
Content-Type: application/json

Request Body Schema:

{
  "type": "object",
  "properties": {
    "customer_email": {
      "type": "string",
      "description": "Customer's email address"
    },
    "subject": {
      "type": "string",
      "description": "Brief summary of the issue"
    },
    "description": {
      "type": "string",
      "description": "Detailed description of the problem"
    },
    "priority": {
      "type": "string",
      "enum": ["low", "medium", "high", "urgent"],
      "description": "Ticket priority based on issue severity"
    }
  },
  "required": ["customer_email", "subject", "description"]
}

Conversation Example

Customer: "My account has been locked for two days and I can't access my data. This is affecting my business!"

Agent: "I understand this is urgent—let me create a priority support ticket for you right away. Could you confirm your email address?"

Customer: "It's john@business.com"

Agent: [Creates ticket with priority="urgent"]

"I've created an urgent support ticket for you. Your ticket number is #45678. Our team will prioritize this and reach out within the next 2 hours. Is there anything else I can help you with while you wait?"

---

Best Practices

1. Validate Before Calling

Instruct your agent to confirm required information before making API calls:

Before calling external APIs:
- Confirm you have all required information
- Verify identifiers with the customer: "Just to confirm, your order number is 12345?"
- Don't guess or assume values

2. Handle Errors Gracefully

Configure error responses in your instructions:

## API Error Handling
If an API call fails:
- Don't expose technical details
- Apologize: "I'm having trouble accessing that information right now."
- Offer alternatives: "Would you like me to connect you with a team member who can help?"
- Log the issue (the system handles this automatically)

3. Rate Limiting

Be mindful of API rate limits:

• Configure appropriate timeouts
• Avoid calling the same API repeatedly in one conversation
• Cache results when possible (handled by the platform)

4. Security Considerations

• Never put API keys directly in the URL or body
• Use the secure credentials system for sensitive values
• Consider what data should be exposed to end users
• Use read-only API keys when possible

---

Troubleshooting

Tool Not Being Used

• Check the description—is it clear when to use this tool?
• Verify the agent's instructions don't contradict tool usage
• Test in Playground with explicit requests

Incorrect Parameters

• Review schema descriptions—are they clear?
• Add examples to help the agent understand expected formats
• Use enum for fields with limited valid values

API Errors

• Check authentication credentials
• Verify the endpoint URL is correct
• Test the API independently with the same parameters
• Check for CORS issues if calling from browser-based deployments

---

Related Documentation

• Tools Overview - Understanding agent tools
• Manual Tools - For complex integrations
• Knowledge Base - Document-based Q&A