UltraVoiceDocs

Tools & Integrations

Give your voice agents the ability to take real actions — look up data, create calendar events, send messages, and call any external API. The LLM decides when to use a tool based on conversation context.

TWO WAYS TO ADD TOOLS

Connector Integrations

One-click OAuth integrations (Google Calendar, CRMs, etc.) that your agent can use without managing API keys.

Custom REST Tools

Point the agent at any HTTP endpoint. Bring your own API key and define the JSON Schema for inputs.

Connector Integrations

Connectors let you link third-party services to UltraVoice via OAuth — no API key management needed. Once a connection is authorised, you can attach it to any agent as a tool in one click.

Available Connectors

INTEGRATIONS

Google Calendar

Check availability, create, update, and cancel events.

Google Meet

Create and manage video meeting links automatically.

HubSpot CRM

Create contacts, log calls, update deal stages.

Salesforce

Query and update Salesforce objects during calls.

Slack

Post messages or notifications to Slack channels.

Custom Webhook

Trigger any webhook URL with structured payload.

Walkthrough: Appointment Booking Agent

This end-to-end example builds a voice agent that books, checks, and cancels Google Calendar appointments over the phone.

Step 1 — Connect Google Calendar

In the UltraVoice dashboard:

  • Go to Integrations in the left sidebar
  • Click Connect next to Google Calendar
  • Sign in with your Google account and grant calendar read/write permissions
  • The integration status shows Connected — copy the Connection ID shown
💡

Each workspace has its own integration connections. You can connect multiple Google accounts.

Step 2 — Create the Agent

BASH
curl -X POST https://ultravoice.us.inc/api/v1/agents/ \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Appointment Booking Agent",
    "system_prompt": "You are a friendly appointment booking assistant. Help callers schedule, reschedule, or cancel appointments.\n\nRules:\n- Always confirm the caller'''s name and preferred time before booking.\n- Check availability before proposing a slot.\n- Keep responses under 2 sentences.\n- When booking, always confirm the event was created.",
    "welcome_message": "Hi! I can help you book or manage your appointments. What would you like to do?",
    "workspace_id": "YOUR_WORKSPACE_ID",
    "language": "en"
  }'
BASH
export AGENT_ID="<agent_id from response>"

Step 3 — Add Calendar Tools

Add three connector tools to the agent — check availability, create event, and cancel event.

Tool 1 — Check Availability:

BASH
curl -X POST https://ultravoice.us.inc/api/v1/agents/$AGENT_ID/tools \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "check_availability",
    "description": "Check if a time slot is available on the calendar. Use this before proposing or booking any appointment.",
    "tool_type": "connector",
    "connector_id": "YOUR_CONNECTION_ID",
    "action": "check_availability",
    "parameters": {
      "type": "object",
      "properties": {
        "date": {
          "type": "string",
          "description": "Date in YYYY-MM-DD format, e.g. 2025-06-10"
        },
        "time": {
          "type": "string",
          "description": "Start time in HH:MM 24h format, e.g. 14:30"
        },
        "duration_minutes": {
          "type": "integer",
          "description": "Duration of the appointment in minutes, default 30"
        }
      },
      "required": ["date", "time"]
    }
  }'

Tool 2 — Book Appointment:

BASH
curl -X POST https://ultravoice.us.inc/api/v1/agents/$AGENT_ID/tools \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "book_appointment",
    "description": "Create a calendar appointment after the caller confirms the time slot. Always check availability first.",
    "tool_type": "connector",
    "connector_id": "YOUR_CONNECTION_ID",
    "action": "create_event",
    "parameters": {
      "type": "object",
      "properties": {
        "title": {
          "type": "string",
          "description": "Event title, e.g. Appointment with John Smith"
        },
        "date": {
          "type": "string",
          "description": "Date in YYYY-MM-DD format"
        },
        "time": {
          "type": "string",
          "description": "Start time in HH:MM 24h format"
        },
        "duration_minutes": {
          "type": "integer",
          "description": "Duration in minutes"
        },
        "attendee_email": {
          "type": "string",
          "description": "Email address of the attendee (optional)"
        }
      },
      "required": ["title", "date", "time", "duration_minutes"]
    }
  }'

Tool 3 — Cancel Appointment:

BASH
curl -X POST https://ultravoice.us.inc/api/v1/agents/$AGENT_ID/tools \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "cancel_appointment",
    "description": "Cancel an existing calendar appointment by event ID. Ask the caller to confirm before cancelling.",
    "tool_type": "connector",
    "connector_id": "YOUR_CONNECTION_ID",
    "action": "delete_event",
    "parameters": {
      "type": "object",
      "properties": {
        "event_id": {
          "type": "string",
          "description": "The Google Calendar event ID to cancel"
        }
      },
      "required": ["event_id"]
    }
  }'

Step 4 — Set AI Providers

Configure LLM, ASR, and TTS for the agent:

BASH
curl -X POST https://ultravoice.us.inc/api/v1/agents/$AGENT_ID/providers \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "llm": {
      "provider": "openai",
      "model": "gpt-4o-mini",
      "api_key": "sk-...",
      "temperature": 0.4
    },
    "asr": {
      "provider": "deepgram",
      "api_key": "dg-...",
      "model": "nova-2"
    },
    "tts": {
      "provider": "deepgram",
      "api_key": "dg-...",
      "voice": "aura-asteria-en"
    }
  }'

Step 5 — Test the Agent

Use Voice Test in the dashboard to have a live conversation with your agent before connecting it to a phone number:

  • Open Voice Test in the sidebar and select Appointment Booking Agent
  • Say "I'd like to book an appointment for tomorrow at 2pm"
  • The agent checks availability via the Google Calendar tool
  • It confirms and creates the event if the slot is free
  • You'll see the tool calls logged in the transcript panel
💡

Watch the transcript panel — every tool call is logged with the function name, arguments, and response so you can debug the agent's behaviour.

Step 6 — Connect to a Phone Number (Optional)

To take real appointment calls, attach a phone number to the agent:

BASH
curl -X POST https://ultravoice.us.inc/api/v1/agents/$AGENT_ID/telephony \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "twilio",
    "phone_number": "+14155552671",
    "direction": "inbound"
  }'

Incoming calls to that number are now handled by the Appointment Booking Agent.

Example Conversation

TEXT
Agent:  Hi! I can help you book or manage your appointments. What would you like to do?

Caller: I'd like to book an appointment for Friday at 3pm.

[Tool call → check_availability(date="2025-06-13", time="15:00", duration_minutes=30)]
[Result → { "available": true }]

Agent:  Great, Friday the 13th at 3pm is available. May I have your name?

Caller: Sarah Johnson.

[Tool call → book_appointment(title="Appointment with Sarah Johnson", date="2025-06-13", time="15:00", duration_minutes=30)]
[Result → { "event_id": "abc123", "status": "confirmed" }]

Agent:  Done! I've booked your appointment for Friday June 13th at 3pm. Is there anything else?

Custom REST Tools

For any API not covered by a built-in connector, you can define a custom HTTP tool with full control over headers, auth, request body, and response extraction.

Create a Custom Tool

BASH
curl -X POST https://ultravoice.us.inc/api/v1/agents/{agent_id}/tools \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "get_weather",
    "description": "Get current weather for a given city. Use when the caller asks about weather.",
    "tool_type": "rest",
    "endpoint_url": "https://api.weatherapi.com/v1/current.json",
    "http_method": "GET",
    "auth_type": "query_param",
    "auth_token": "key=YOUR_WEATHERAPI_KEY",
    "parameters": {
      "type": "object",
      "properties": {
        "q": {
          "type": "string",
          "description": "City name, e.g. London or New York"
        }
      },
      "required": ["q"]
    },
    "response_path": "current.condition.text",
    "timeout_ms": 5000
  }'

Field Reference

TOOL FIELDS

name

Function name used in LLM tool calling. No spaces — use snake_case.

description

Shown to the LLM. Be specific about when to use this tool.

endpoint_url

Full URL of the external API endpoint.

http_method

GET, POST, PUT, or DELETE.

auth_type

"bearer", "api_key", "query_param", or "none".

parameters

JSON Schema object describing the tool's input parameters.

request_body

Template object for POST/PUT body. Supports {{param}} placeholders.

response_path

Dot-notation JSON path to extract from the response, e.g. "data.result".

timeout_ms

Max wait time in milliseconds. Default: 5000. Max: 20000.

How Tool Execution Works

  • The LLM signals a tool call with the function name and arguments
  • The pipeline extracts the arguments and calls the tool executor
  • The tool executor makes the HTTP request to endpoint_url
  • If response_path is set, only that field is extracted from the response
  • The result is injected back into the LLM context as a tool response
  • The LLM generates a natural language reply based on the tool result
⚠️

Tool execution has a 20-second maximum timeout. Keep tool responses small — only return the data the agent needs to answer the caller.

List, Update & Delete Tools

BASH
# List all tools on an agent
curl https://ultravoice.us.inc/api/v1/agents/{agent_id}/tools \
  -H "Authorization: Bearer $TOKEN"

# Update a tool
curl -X PUT https://ultravoice.us.inc/api/v1/agents/{agent_id}/tools/{tool_id} \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"description": "Updated description", "timeout_ms": 10000}'

# Delete a tool
curl -X DELETE https://ultravoice.us.inc/api/v1/agents/{agent_id}/tools/{tool_id} \
  -H "Authorization: Bearer $TOKEN"