Connect Tools

Tools allow your agent to fetch or update external data during a call. Instead of the agent making things up, it can call your CRM, check your calendar, or query your database in real time.

---

Tool types

Type	Description
REST API	Call any HTTP endpoint mid-conversation
Salesforce	Look up contacts, accounts, cases, opportunities
HubSpot	Look up contacts, companies, deals, tickets
Shopify	Look up orders, customers, products
Google Calendar	Check availability and create events

---

How tools work

When the agent determines it needs external data, it:

1. Pauses generating its response
2. Calls the configured tool with the extracted parameters
3. Receives the tool's response (JSON)
4. Continues generating its response with the new context

The caller hears a brief natural pause — or a filler phrase if you configure one.

---

Configure a REST API tool

Tools are configured within an agent's tools array:

curl -X PATCH https://api.voisnap.ai/api/v1/agents/agt_01HXK8Z3MNPQRS \
  -H "Authorization: Bearer vsnp_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "tools": [
      {
        "name": "lookup_customer",
        "description": "Look up customer account information by phone number. Use this whenever the customer asks about their account, order history, or billing.",
        "type": "rest_api",
        "config": {
          "url": "https://api.acme.com/customers/lookup",
          "method": "GET",
          "headers": {
            "X-Api-Key": "acme_internal_key_here"
          },
          "queryParams": {
            "phone": "{{phone_number}}"
          }
        },
        "parameters": [
          {
            "name": "phone_number",
            "description": "The customer'\''s phone number in E.164 format",
            "type": "string",
            "required": true,
            "source": "caller_phone_number"
          }
        ],
        "responseMapping": {
          "customer_id": "$.id",
          "customer_name": "$.name",
          "account_tier": "$.tier",
          "open_tickets": "$.support.openTickets",
          "last_order": "$.orders[0].id"
        },
        "fillerPhrase": "Let me pull up your account.",
        "timeoutMs": 3000,
        "onError": "ignore"
      }
    ]
  }'

Parameter sources

Source	Description
caller_phone_number	Automatically populated from the caller's phone number
agent_extracted	The LLM extracts this from the conversation
session_metadata	From the session's metadata object
literal	A hardcoded value

---

Full CRM lookup example

This example shows a complete flow where the agent looks up a customer by phone number at the start of the call and personalizes the entire conversation.

System prompt

You are Aria, a support agent for Acme Corp.

## At the start of every call
Use the lookup_customer tool immediately to fetch the caller's account information. 
Do NOT ask the customer for their account number — you have their phone number.

After calling the tool:
- If found: Address them by first name. Note their tier (premium customers get priority).
- If not found: Proceed normally and ask for their name.

## Using tool results
Once you have the customer's info, reference it naturally:
- "I can see you have [X] open support tickets — would you like to discuss those?"
- "As a premium member, I can prioritize your case."
- "I see your last order was [order_id] — is this call related to that order?"

Agent configuration

tools = [
    {
        "name": "lookup_customer",
        "description": "Look up customer by phone number. Always call this at the start of the conversation.",
        "type": "rest_api",
        "config": {
            "url": "https://api.acme.com/customers/lookup",
            "method": "GET",
            "headers": {"X-Api-Key": "${ACME_API_KEY}"},
            "query_params": {"phone": "{{phone_number}}"}
        },
        "parameters": [
            {
                "name": "phone_number",
                "description": "Caller phone number",
                "type": "string",
                "required": True,
                "source": "caller_phone_number"
            }
        ],
        "response_mapping": {
            "customer_id": "$.id",
            "customer_name": "$.name",
            "tier": "$.subscriptionTier",
            "open_tickets": "$.support.openTicketCount",
            "recent_order_id": "$.orders[0].id"
        },
        "filler_phrase": "One moment, let me bring up your account.",
        "timeout_ms": 3000,
        "on_error": "ignore"
    },
    {
        "name": "get_order_status",
        "description": "Get the status of a specific order. Use when the customer asks about an order.",
        "type": "rest_api",
        "config": {
            "url": "https://api.acme.com/orders/{{order_id}}",
            "method": "GET",
            "headers": {"X-Api-Key": "${ACME_API_KEY}"}
        },
        "parameters": [
            {
                "name": "order_id",
                "description": "The order ID to look up (format: ORD-XXXXXX)",
                "type": "string",
                "required": True,
                "source": "agent_extracted"
            }
        ],
        "response_mapping": {
            "status": "$.status",
            "estimated_delivery": "$.shipping.estimatedDelivery",
            "tracking_number": "$.shipping.trackingNumber",
            "carrier": "$.shipping.carrier"
        },
        "filler_phrase": "Let me check on that order for you.",
        "timeout_ms": 3000,
        "on_error": "tell_user"
    }
]
 
client.agents.update(
    AGENT_ID,
    tools=tools
)

---

Built-in integrations

Salesforce

tools = [
    {
        "name": "lookup_salesforce_contact",
        "description": "Look up a Salesforce contact by phone number",
        "type": "salesforce",
        "config": {
            "integration_id": "sf_int_01HXABC...",  # set up in Console → Integrations
            "object": "Contact",
            "lookup_field": "Phone",
            "lookup_value_source": "caller_phone_number",
            "return_fields": ["Name", "Account.Name", "Account.Type", "OwnerId", "Open_Cases__c"]
        },
        "filler_phrase": "Let me look that up in our system."
    }
]

HubSpot

tools = [
    {
        "name": "lookup_hubspot_contact",
        "description": "Look up HubSpot contact by phone number",
        "type": "hubspot",
        "config": {
            "integration_id": "hs_int_01HXABC...",
            "object": "contacts",
            "lookup_by": "phone",
            "properties": ["firstname", "lastname", "company", "hs_lead_status", "num_associated_deals"]
        }
    }
]

Google Calendar

tools = [
    {
        "name": "check_availability",
        "description": "Check available appointment slots for a given date",
        "type": "google_calendar",
        "config": {
            "integration_id": "gcal_int_01HXABC...",
            "calendar_id": "support@acme.com",
            "slot_duration_minutes": 30
        },
        "parameters": [
            {
                "name": "date",
                "description": "The date to check availability for (YYYY-MM-DD)",
                "type": "string",
                "required": True,
                "source": "agent_extracted"
            }
        ]
    },
    {
        "name": "book_appointment",
        "description": "Book an appointment slot after confirming with the customer",
        "type": "google_calendar",
        "config": {
            "integration_id": "gcal_int_01HXABC...",
            "calendar_id": "support@acme.com",
            "action": "create_event",
            "event_title_template": "Support call with {{customer_name}}"
        },
        "parameters": [
            {"name": "datetime", "type": "string", "required": True, "source": "agent_extracted"},
            {"name": "customer_name", "type": "string", "required": True, "source": "agent_extracted"},
            {"name": "customer_phone", "type": "string", "required": True, "source": "caller_phone_number"}
        ]
    }
]

---

Monitor tool usage

Tool call completions fire the ToolCallCompleted webhook event and appear in the ToolCallCompleted conversation messages. Review tool performance in the Console under Agents → Tools → Analytics:

# Get tool call stats from conversations
convs = client.conversations.list(agent_id=AGENT_ID, date_from="2025-06-01")
for conv in convs:
    messages = client.conversations.messages(conv.id)
    tool_calls = [m for m in messages.messages if m.role == "tool"]
    if tool_calls:
        print(f"{conv.id}: {len(tool_calls)} tool calls")