HTTP Tools - Ansa

Overview

HTTP tools allow your agent to:

Fetch data from external APIs
Send data to webhooks
Integrate with any REST API
Display results with rich formatting

Configuration

Basic HTTP Tool

{
  "name": "get_weather",
  "description": "Get current weather when user asks about weather conditions.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "city": {
        "type": "string",
        "description": "City name to get weather for"
      }
    },
    "required": ["city"]
  },
  "executionType": "http",
  "httpUrl": "https://api.weatherapi.com/v1/current.json?key=YOUR_KEY&q=${city}",
  "httpMethod": "GET"
}

HTTP Configuration Options

Field	Required	Description
`httpUrl`	Yes	The API endpoint URL
`httpMethod`	Yes	`GET`, `POST`, `PUT`, or `DELETE`
`httpHeaders`	No	Custom headers (auth, content-type)

Parameter Substitution

Use ${paramName} to insert input parameters into URLs, headers, and bodies:

URL Parameters

{
  "httpUrl": "https://api.example.com/products/${productId}?include=${include}"
}

If the AI calls with {"productId": "123", "include": "reviews"}, the URL becomes:

https://api.example.com/products/123?include=reviews

Header Parameters

{
  "httpHeaders": {
    "Authorization": "Bearer ${api_key}",
    "X-User-ID": "${user_id}"
  }
}

Request Body (POST/PUT)

For POST and PUT requests, the input schema parameters are sent as the JSON body:

{
  "name": "create_ticket",
  "inputSchema": {
    "type": "object",
    "properties": {
      "title": { "type": "string" },
      "description": { "type": "string" },
      "priority": { "type": "string", "enum": ["low", "medium", "high"] }
    }
  },
  "executionType": "http",
  "httpUrl": "https://api.ticketing.com/tickets",
  "httpMethod": "POST",
  "httpHeaders": {
    "Authorization": "Bearer ${api_token}",
    "Content-Type": "application/json"
  }
}

User Context Variables

In addition to AI-generated parameters (${param}), you can access user identity data using {{context}} syntax. This is useful for passing authentication tokens or user information to your APIs.

Available Variables

Variable	Description
`{{userId}}`	The user ID passed via `ansa.identify()`
`{{userMetadata.key}}`	Top-level metadata value
`{{userMetadata.nested.path}}`	Nested metadata value (supports deep paths)

Setting Up User Identity

First, identify your user in your website’s JavaScript:

ansa.identify({
  userId: 'user_123',
  userMetadata: {
    authToken: 'eyJhbG...',
    email: 'user@example.com',
    plan: 'premium',
    organization: {
      id: 'org_456',
      name: 'Acme Inc'
    }
  }
});

Using Identity in Headers

Pass the user’s auth token to your API:

{
  "name": "get_user_orders",
  "description": "Get the user's recent orders",
  "httpUrl": "https://api.yourstore.com/orders",
  "httpMethod": "GET",
  "httpHeaders": {
    "Authorization": "Bearer {{userMetadata.authToken}}",
    "X-User-ID": "{{userId}}",
    "X-Organization-ID": "{{userMetadata.organization.id}}"
  }
}

Using Identity in URLs

{
  "httpUrl": "https://api.yourstore.com/users/{{userId}}/orders?status=${status}"
}

The {{context}} syntax is for user identity data (set via identify()), while ${param} is for AI-generated input values. You can use both in the same tool configuration.

Security Considerations

User identity is passed from the client-side widget, so treat it as untrusted input
Your backend API should validate any auth tokens (JWT signature verification, etc.)
Don’t rely solely on {{userId}} for authorization - verify it against your session/token
The identity data is not stored by Ansa - it’s passed through to your APIs at runtime

Authentication

API Key in Header

{
  "httpHeaders": {
    "Authorization": "Bearer YOUR_API_KEY"
  }
}

API Key in URL

{
  "httpUrl": "https://api.example.com/data?api_key=YOUR_API_KEY"
}

Basic Auth

{
  "httpHeaders": {
    "Authorization": "Basic BASE64_ENCODED_CREDENTIALS"
  }
}

Use the Marketplace to install pre-configured tools that handle authentication setup for popular services.

Examples

Product Search (GET)

{
  "name": "search_products",
  "description": "Search for products when user asks about items, availability, or prices.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "query": {
        "type": "string",
        "description": "Search term"
      },
      "category": {
        "type": "string",
        "description": "Category to filter by"
      },
      "maxResults": {
        "type": "number",
        "description": "Maximum results to return"
      }
    },
    "required": ["query"]
  },
  "executionType": "http",
  "httpUrl": "https://api.store.com/products?q=${query}&category=${category}&limit=${maxResults}",
  "httpMethod": "GET",
  "httpHeaders": {
    "Authorization": "Bearer ${STORE_API_KEY}"
  },
  "displayConfig": {
    "type": "product_carousel",
    "fieldMappings": {
      "title": "$.products[*].name",
      "price": "$.products[*].price",
      "image": "$.products[*].image_url"
    }
  }
}

Order Lookup (GET)

{
  "name": "lookup_order",
  "description": "Look up order status when user provides an order number.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "orderNumber": {
        "type": "string",
        "description": "The order number to look up"
      }
    },
    "required": ["orderNumber"]
  },
  "executionType": "http",
  "httpUrl": "https://api.store.com/orders/${orderNumber}",
  "httpMethod": "GET",
  "displayConfig": {
    "type": "product_card",
    "fieldMappings": {
      "title": "Order #${orderNumber}",
      "status": "$.status",
      "tracking": "$.tracking_url"
    }
  }
}

Create Support Ticket (POST)

{
  "name": "create_ticket",
  "description": "Create a support ticket when user has an issue that needs human help.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "subject": {
        "type": "string",
        "description": "Brief description of the issue"
      },
      "description": {
        "type": "string",
        "description": "Detailed description"
      },
      "priority": {
        "type": "string",
        "enum": ["low", "medium", "high"],
        "description": "Issue priority"
      },
      "email": {
        "type": "string",
        "description": "User's email for follow-up"
      }
    },
    "required": ["subject", "description", "email"]
  },
  "executionType": "http",
  "httpUrl": "https://api.zendesk.com/api/v2/tickets",
  "httpMethod": "POST",
  "httpHeaders": {
    "Authorization": "Bearer ${ZENDESK_TOKEN}",
    "Content-Type": "application/json"
  }
}

Update Record (PUT)

{
  "name": "update_preferences",
  "description": "Update user preferences when they want to change settings.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "userId": { "type": "string" },
      "notifications": { "type": "boolean" },
      "theme": { "type": "string", "enum": ["light", "dark"] }
    },
    "required": ["userId"]
  },
  "executionType": "http",
  "httpUrl": "https://api.example.com/users/${userId}/preferences",
  "httpMethod": "PUT",
  "httpHeaders": {
    "Authorization": "Bearer ${API_KEY}",
    "Content-Type": "application/json"
  }
}

Response Handling

Successful Responses

The API response is:

Passed to the AI for interpretation
Formatted according to displayConfig (if specified)
Included in the agent’s response

Error Handling

If the API returns an error:

4xx errors: Agent acknowledges the issue
5xx errors: Agent apologizes for technical difficulties
Timeout: Agent suggests trying again

Display Configuration

Pair HTTP tools with display config for rich responses:

{
  "displayConfig": {
    "type": "product_carousel",
    "fieldMappings": {
      "title": "$.items[*].name",
      "price": "$.items[*].price",
      "image": "$.items[*].image"
    },
    "textFallback": "Found {{count}} items matching your search."
  }
}

See Display Configuration for all options.

Testing HTTP Tools

Mock Mode

Before connecting to live APIs, test with mock mode:

{
  "executionType": "mock",
  "mockResponse": "Found 3 products matching '${query}': Widget A ($19.99), Widget B ($24.99), Widget C ($29.99)"
}

Live Testing

Create the tool with your API configuration
Open the chat playground
Ask a question that should trigger the tool
Check the response and refine as needed

Best Practices

API Design

Keep responses concise — Large responses slow down processing
Return only needed fields — Use API filtering when available
Handle pagination — Consider limits for list endpoints

Security

Never expose secrets in URLs — Use headers for auth tokens
Use HTTPS — All external APIs should use HTTPS
Rotate keys — Update API keys regularly

Reliability

Handle errors gracefully — Write descriptions that help AI explain failures
Set timeouts — APIs should respond within 30 seconds
Monitor usage — Track API calls to stay within limits

​Overview

​Configuration

​Basic HTTP Tool

​HTTP Configuration Options

​Parameter Substitution

​URL Parameters

​Header Parameters

​Request Body (POST/PUT)

​User Context Variables

​Available Variables

​Setting Up User Identity

​Using Identity in Headers

​Using Identity in URLs

​Security Considerations

​Authentication

​API Key in Header

​API Key in URL

​Basic Auth

​Examples

​Product Search (GET)

​Order Lookup (GET)

​Create Support Ticket (POST)

​Update Record (PUT)

​Response Handling

​Successful Responses

​Error Handling

​Display Configuration

​Testing HTTP Tools

​Mock Mode

​Live Testing

​Best Practices

​API Design

​Security

​Reliability

​See Also

Overview

Configuration

Basic HTTP Tool

HTTP Configuration Options

Parameter Substitution

URL Parameters

Header Parameters

Request Body (POST/PUT)

User Context Variables

Available Variables

Setting Up User Identity

Using Identity in Headers

Using Identity in URLs

Security Considerations

Authentication

API Key in Header

API Key in URL

Basic Auth

Examples

Product Search (GET)

Order Lookup (GET)

Create Support Ticket (POST)

Update Record (PUT)

Response Handling

Successful Responses

Error Handling

Display Configuration

Testing HTTP Tools

Mock Mode

Live Testing

Best Practices

API Design

Security

Reliability

See Also