Tool Proxy

Proxies tool calls from Telnyx Conversational AI during active voice calls. Looks up tool configuration from the database, injects authentication, and forwards the request.

Volume: ~29K runs/week | Auth: None (internal Telnyx callback)

Request

POST /api/v1/tool-proxy
Content-Type: application/json

Body Parameters

Responses

Success

Returns the proxied tool response:

{
  "status": 200,
  "response": {
    "result": "Appointment scheduled for Tuesday at 2 PM"
  }
}

Tool Not Configured

{ "error": "Tool not configured", "tool_id": "unknown_tool" }

Proxy Error

{
  "error": "Tool execution failed",
  "status": 502,
  "tool_id": "tool_123"
}

Test with cURL

curl -X POST http://localhost:3000/api/v1/tool-proxy \
  -H "Content-Type: application/json" \
  -d '{
    "tool_id": "tool_schedule_appointment",
    "body": {
      "date": "2026-04-01",
      "time": "14:00",
      "contact_name": "John Doe"
    },
    "location_id": "loc_123",
    "contact_id": "contact_789"
  }'

Pipeline Flow

1. Look up tool configuration from DB (Prisma Tool + ToolHeader)
2. If tool not found: auto-register and return error
3. Fetch SubAccount access token (if location_id provided)
4. Build headers from tool config (including auth token injection)
5. Forward request to tool's configured URL
6. Return proxied response

Auto-Registration

Unknown tools are automatically registered in the database with:

• name: the tool_id
• description: "Auto-registered tool: {tool_id}"
• toolType: "CUSTOM"

Configure the tool's URL and headers in the database to make it functional.