Agent Integration Guide — Salesbooth Developer Docs

Widget Delivery

The Salesbooth widget is the default customer-facing surface for enabled agent functionality. Install the widget once on a tenant website, then enable sales, quote, negotiation, booking, promotion, support-to-sales, website, or offer-page capabilities through tenant configuration and agent permissions.

One install, many approved capabilities

Agents still use API keys, delegations, tools, and approval gates server-side. The widget provides the customer-facing experience so each agent does not need a separate embed script or private web delivery path.

If an agent needs a web capability that the widget cannot deliver yet, treat it as a reusable platform gap. Add the missing public widget/API capability or report it as an agent support ticket with reproduction context.

How Agent Authentication Works

Salesbooth uses a delegation model for agents. Instead of giving an agent your API key directly, you create a delegation — a scoped, time-limited authorization that the agent uses to act on your behalf.

Your Account
    │
    ├── Delegation → Agent A (scope: deals:write, budget: $5000/day)
    ├── Delegation → Agent B (scope: products:read, customers:read)
    └── Delegation → Agent C (scope: deals:write + agent:negotiate, budget: $50/deal)

Each delegation has:

Scopes — which API operations the agent can perform
Budget limits — maximum spend per deal or per day
Trust level — determines what actions require human approval
Expiry — delegations auto-expire for security

How agent auth works: API key + delegation ID

An agent authenticates with its own sb_test_* or sb_live_* API key and passes an X-Delegation-ID header to operate within the delegated scope. If an agent is compromised, revoke its delegation without affecting your account or other agents.

Creating Delegations

Create delegations from Settings → Delegations or via the API:

# Create a delegation for an AI agent
curl -X POST https://api.salesbooth.com/v1/delegations \
  -H "Authorization: Bearer $SB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "grantee_agent_key_id": "key_a1b2c3d4e5f6",
    "allowed_actions": ["deals:write", "customers:write", "agent:negotiate"],
    "max_transaction_amount": 500.00,
    "max_daily_amount": 5000.00,
    "expires_at": "2026-12-31T23:59:59Z",
    "description": "Handles inbound leads automatically"
  }'

# Response
{
  "error": false,
  "success": true,
  "data": {
    "delegation_id": "deleg_a1b2c3d4e5f6g7h8",
    "tenant_id": "tenant_abc123",
    "grantor_type": "user",
    "grantor_id": "42",
    "grantee_agent_key_id": "key_a1b2c3d4e5f6",
    "description": "Handles inbound leads automatically",
    "allowed_actions": ["deals:write", "customers:write", "agent:negotiate"],
    "max_transaction_amount": "500.00",
    "max_daily_amount": "5000.00",
    "max_monthly_amount": null,
    "spent_today": "0.00",
    "spent_this_month": "0.00",
    "available_today": "5000.00",
    "available_this_month": null,
    "expires_at": "2026-12-31 23:59:59",
    "revoked_at": null,
    "created_at": "2026-03-24 12:00:00"
  }
}

Agent scopes

Scope	What the agent can do
`deals:read`	List and view deals
`deals:write`	Create, update, and progress deals
`deals:sign`	Sign deals on behalf of the principal
`customers:read`	Look up customer records
`customers:write`	Create and update customers
`products:read`	List and retrieve products and pricing
`products:write`	Create, update, and manage products
`contracts:read`	View contract terms
`contracts:write`	Create, update, and sign contracts
`agent:discover`	List tools, discover agents, and use federation discovery
`agent:negotiate`	Propose and respond to negotiation offers
`agent:execute`	Trigger workflow execution
`intelligence:read`	Read deal intelligence data
`intelligence:write`	Write intelligence actions
`delegations:read`	List and view delegations
`delegations:write`	Create and manage delegations
`webhooks:read`	List and view webhooks
`webhooks:write`	Create and manage webhooks
`audit:export`	Export audit data
`sandbox:read`	Read sandbox state
`sandbox:write`	Toggle sandbox mode
`billing:read`	Access billing data

Using a delegation credential

The agent authenticates with its own API key and passes the delegation ID to operate within the delegated scope:

# Step 1: Agent creates the deal using its own API key + delegation ID header
curl -X POST https://api.salesbooth.com/v1/deals \
  -H "Authorization: Bearer sb_test_au_your_agent_key_here" \
  -H "X-Delegation-ID: deleg_a1b2c3d4" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "cust_abc123",
    "title": "Q2 Enterprise Proposal"
  }'

# Step 2: Add line items separately via add_item action
curl -X POST "https://api.salesbooth.com/v1/deals?id=deal_a1b2c3d4&action=add_item" \
  -H "Authorization: Bearer sb_test_au_your_agent_key_here" \
  -H "X-Delegation-ID: deleg_a1b2c3d4" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": "prod_a1b2c3d4",
    "name": "Enterprise Plan",
    "unit_price": 99.00,
    "quantity": 10
  }'

Revoking a delegation

curl -X DELETE "https://api.salesbooth.com/v1/delegations?id=deleg_a1b2c3d4" \
  -H "Authorization: Bearer $SB_API_KEY"

MCP Protocol

The Model Context Protocol (MCP) endpoint lets AI assistants (AI assistant, GPT-4, etc.) interact with Salesbooth using natural language tool calls — no custom API integration required.

MCP endpoint

https://api.salesbooth.com/v1/mcp

Configuring your AI assistant

// claude_desktop_config.json
{
  "mcpServers": {
    "salesbooth": {
      "url": "https://api.salesbooth.com/v1/mcp",
      "headers": {
        "Authorization": "Bearer sb_test_au_your_agent_key_here",
        "X-Delegation-ID": "deleg_a1b2c3d4"
      }
    }
  }
}

// AI provider function calling — fetch MCP tool definitions via JSON-RPC
const rpc = await fetch('https://api.salesbooth.com/v1/mcp', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sb_test_au_your_agent_key_here',
    'X-Delegation-ID': 'deleg_a1b2c3d4',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ jsonrpc: '2.0', method: 'tools/list', id: 'tools-list-1' })
}).then(r => r.json());

// Map MCP tool format to AI provider function calling format
// MCP returns: { name, description, inputSchema }
// AI provider expects: { type: 'function', function: { name, description, parameters } }
const tools = rpc.result.tools.map(t => ({
  type: 'function',
  function: { name: t.name, description: t.description, parameters: t.inputSchema }
}));

// Use in ChatCompletion request
const messages = [{ role: 'user', content: 'Find software deals under $5,000' }];

const response = await openai.chat.completions.create({
  model: 'gpt-4o',
  messages,
  tools,
  tool_choice: 'auto'
});

# List available MCP tools (JSON-RPC tools/list)
curl -X POST https://api.salesbooth.com/v1/mcp \
  -H "Authorization: Bearer sb_test_au_your_agent_key_here" \
  -H "X-Delegation-ID: deleg_a1b2c3d4" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":"tools-list-1"}'

# Execute a tool call (JSON-RPC tools/call)
curl -X POST https://api.salesbooth.com/v1/mcp \
  -H "Authorization: Bearer sb_test_au_your_agent_key_here" \
  -H "X-Delegation-ID: deleg_a1b2c3d4" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "id": "tools-call-1",
    "params": {
      "name": "create_deal",
      "arguments": {
        "customer_id": "cust_abc123",
        "title": "Enterprise Q2 Proposal",
        "currency": "USD"
      }
    }
  }'

Products are added as line items after deal creation using the add_deal_item tool.

// Agent SDK — preferred alternative to raw MCP fetch calls
const SalesboothAgent = require('@salesbooth/sdk/agent');

async function main() {
    const agent = SalesboothAgent.init({
        apiKey:       'sb_test_au_your_agent_key_here',
        delegationId: 'deleg_a1b2c3d4'
    });

    // Get MCP-formatted tool definitions without a network call
    const tools = agent.getToolDefinitions('mcp');

    // Execute a tool by name — credentials attached automatically
    const deal = await agent.executeTool('create_deal', {
        customer_id: 'cust_abc123',
        title:       'Q2 Enterprise Proposal',
        currency:    'USD'
    });

    // See the Agent SDK section below for getToolDefinitions() format options:
    // 'openai', 'anthropic', 'universal', 'mcp'
}

main().catch(console.error);

Available MCP tools

A selection of commonly-used tools is shown below. The complete list of 190+ tools — including contracts, payments, subscriptions, and intelligence — is available by calling the tools/list MCP method on your connected server.

Tool name	Description	Required scope
`discover_deals`	List recent deals with filters	`agent:discover`
`create_deal`	Create a new deal	`deals:write`
`check_deal_status`	Retrieve deal details	`deals:read`
`transition_deal`	Progress a deal to a new status	`deals:write`
`negotiate_terms`	Submit a counter-offer	`agent:negotiate`
`accept_deal`	Accept current offer	`deals:write`
`list_products`	List available products	`products:read`
`calculate_pricing`	Calculate price for a product configuration	`products:read`
`get_customer`	Find a customer by ID or email	`customers:read`
`create_customer`	Create a new customer record	`customers:write`
`generate_quote`	Generate a shareable quote snapshot with structured quote data and URL	`deals:write`
`workflow_plan`	Plan a workflow from delegation and constraints	`agent:execute`
`workflow_execute`	Execute a planned workflow	`agent:execute`
`workflow_approve_step`	Approve a paused workflow step with delegation scope	`agent:execute`
`workflow_reject_step`	Reject a paused workflow step and cancel the workflow	`agent:execute`

Agent SDK

The salesbooth-agent.js SDK is the recommended integration path for AI agents. It wraps authentication, tool discovery, and execution in a single client — no raw HTTP or JSON-RPC boilerplate required.

Preferred over raw fetch

The Agent SDK attaches credentials, handles retries, and normalises errors automatically. Use getToolDefinitions() to feed schemas directly into any LLM function-calling API, and executeTool() to run them.

Installation

<script src="https://salesbooth.com/sdk/v1/salesbooth-agent.js"></script>
<!-- SalesboothAgent is now available as a global variable -->

// Install the published browser SDK package for Node/CommonJS usage.
const SalesboothAgent = require('@salesbooth/sdk/agent');

Initialise the agent client

const agent = SalesboothAgent.init({
    apiKey:       'sb_test_au_your_agent_key_here',
    delegationId: 'deleg_a1b2c3d4'   // optional — scope actions to a delegation
});

Get tool definitions

Pass the tool list directly to your LLM's function-calling API. Four formats are supported:

// Returns tools in function-calling format
const tools = agent.getToolDefinitions('openai');
const messages = [{ role: 'user', content: 'Find software deals under $5,000' }];

const response = await openai.chat.completions.create({
    model:       'gpt-4o',
    messages,
    tools,
    tool_choice: 'auto'
});

// Returns tools in AI provider tool_use format
const tools = agent.getToolDefinitions('anthropic');
const messages = [{ role: 'user', content: 'Find software deals under $5,000' }];

const response = await anthropic.messages.create({
    model:      'claude-opus-4-6',
    messages,
    tools,
    max_tokens: 4096
});

// Returns MCP-formatted local tool definitions (name + description + inputSchema)
const tools = agent.getToolDefinitions('mcp');

// Useful for offline/schema-driven setup without a network call.
// Call the MCP tools/list endpoint when you need the authoritative
// live server catalogue.

// Returns tools in a portable format compatible with any LLM
const tools = agent.getToolDefinitions('universal');

// Each tool: { name, description, parameters: { type, properties, required } }
// Map to your preferred LLM's schema as needed.

Execute a tool

executeTool(name, args) looks up the tool, calls the matching Salesbooth API endpoint, and returns the parsed response. Retries are automatic on transient errors.

// List deals matching criteria
const deals = await agent.executeTool('discover_deals', {
    category:  'software',
    max_price: 10000
});

// Create a deal
const result = await agent.executeTool('create_deal', {
    customer_id: 'cust_abc123',
    title:       'Q2 Enterprise Proposal'
});

// Add a line item to the deal
await agent.executeTool('add_deal_item', {
    id:         result.deal.deal_id,
    product_id: 'prod_a1b2c3d4',
    name:       'Platform Pro',
    quantity:   5,
    unit_price: 99.00
});

// Full AI provider tool-use loop with the Agent SDK
const agent = SalesboothAgent.init({
    apiKey:       'sb_test_au_your_agent_key_here',
    delegationId: 'deleg_a1b2c3d4'
});

const tools    = agent.getToolDefinitions('openai');
const messages = [{ role: 'user', content: 'Find software deals under $5,000 and create one' }];

const response = await openai.chat.completions.create({
    model: 'gpt-4o', messages, tools, tool_choice: 'auto'
});

// Execute each tool call the model requests
for (const call of (response.choices[0].message.tool_calls || [])) {
    const result = await agent.executeTool(
        call.function.name,
        JSON.parse(call.function.arguments)
    );
    messages.push({
        role:         'tool',
        tool_call_id: call.id,
        content:      JSON.stringify(result)
    });
}

List tools by category

// Returns tools grouped by category
const grouped = agent.listTools();
// {
//   deal_management:  [ 'discover_deals', 'create_deal', 'transition_deal', ... ],
//   customer_management: [ 'list_customers', 'get_customer', 'create_customer', ... ],
//   product_catalog:  [ 'list_products', 'calculate_pricing', ... ],
//   ...
// }

Workflow Execution

Agent workflows are planned from a supported intent plus constraints. You do not submit arbitrary dashboard-defined steps[].type arrays. Instead, use workflow_plan or POST /api/v1/agent-workflow to let the workflow service build the supported step sequence, then execute and approve/reject it through the workflow tools or API actions below.

Plan a workflow

For the current public agent contract, use a purchase workflow and let Salesbooth derive the steps. A purchase plan expands into discover → select → create_deal → optional negotiate → finalize.

# Plan a workflow
curl -X POST "https://api.salesbooth.com/v1/agent-workflow" \
  -H "Authorization: Bearer sb_test_au_your_agent_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "delegation_id": "deleg_a1b2c3d4",
    "intent": "purchase",
    "constraints": {
      "max_budget": 5000,
      "product_categories": ["software"],
      "customer_email": "buyer@example.com",
      "auto_negotiate": true,
      "max_negotiation_rounds": 2,
      "max_discount_percent": 10
    }
  }'

# Response
{
  "error": false,
  "success": true,
  "data": {
    "workflow_id": "wf_a1b2c3d4",
    "status": "planned",
    "steps": [
      { "step": "discover", "status": "pending", "products_found": 8 },
      { "step": "select", "status": "pending", "estimated_value": 4800 },
      { "step": "create_deal", "status": "pending", "within_budget": true },
      { "step": "negotiate", "status": "pending", "max_rounds": 2, "max_discount_percent": 10 },
      { "step": "finalize", "status": "pending" }
    ]
  }
}

Execute the planned workflow

# Execute a planned workflow
curl -X POST "https://api.salesbooth.com/v1/agent-workflow?id=wf_a1b2c3d4&action=execute" \
  -H "Authorization: Bearer sb_test_au_your_agent_key_here"

# Response
{
  "error": false,
  "success": true,
  "data": {
    "workflow_id": "wf_a1b2c3d4",
    "status": "executing",
    "current_step": "discover",
    "steps": ["discover", "select", "create_deal", "negotiate", "finalize"],
    "job_id": 1842
  }
}

Checking workflow status

curl "https://api.salesbooth.com/v1/agent-workflow?id=wf_a1b2c3d4" \
  -H "Authorization: Bearer sb_test_au_your_agent_key_here" \
  -H "X-Delegation-ID: deleg_a1b2c3d4"

Approval gates

When a workflow reaches an approval threshold, it pauses with awaiting_approval. Approve it with workflow_approve_step or reject it with workflow_reject_step. The approval is attached to a workflow that Salesbooth already planned; you do not inject a custom approval_gate step into the request body.

Approval notifications

When a workflow reaches an approval gate, the account owner receives an email and in-app notification. Approve or reject from Intelligence → Agent Workflows → Pending Approvals, or via the API calls below.

Responding to approval gates via API

List workflows waiting for approval, then approve or reject the paused step programmatically:

# List workflows waiting for approval
curl "https://api.salesbooth.com/v1/agent-workflow?action=pending_approvals" \
  -H "Authorization: Bearer sb_test_au_your_agent_key_here" \
  -H "X-Delegation-ID: deleg_a1b2c3d4"

# Approve a paused workflow step with delegation scope
curl -X POST "https://api.salesbooth.com/v1/agent-workflow?id=wf_a1b2c3d4&action=delegate_approve" \
  -H "Authorization: Bearer sb_test_au_your_agent_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "delegation_id": "deleg_a1b2c3d4",
    "approval_note": "Approved after budget review"
  }'

# Reject a paused workflow step
curl -X POST "https://api.salesbooth.com/v1/agent-workflow?id=wf_a1b2c3d4&action=reject" \
  -H "Authorization: Bearer sb_test_au_your_agent_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Deal value exceeds quarterly budget" }'

If the approval email notification needs to be resent, or the request requires escalation to the delegation grantor:

# Resend the approval notification
curl -X POST "https://api.salesbooth.com/v1/agent-workflow?id=wf_a1b2c3d4&action=resend_approval" \
  -H "Authorization: Bearer sb_test_au_your_agent_key_here" \
  -H "X-Delegation-ID: deleg_a1b2c3d4"

# Escalate to the delegation grantor
curl -X POST "https://api.salesbooth.com/v1/agent-workflow?id=wf_a1b2c3d4&action=escalate_approval" \
  -H "Authorization: Bearer sb_test_au_your_agent_key_here" \
  -H "X-Delegation-ID: deleg_a1b2c3d4" \
  -H "Content-Type: application/json" \
  -d '{ "escalation_reason": "Reviewer has not responded within 12 hours" }'

Trust Level Progression

The Salesbooth trust system progressively grants agents more autonomy as they demonstrate reliable behavior. Trust is earned, not granted.

0

Untrusted

Discover and read-only access only

1

Provisional

Discover + negotiate; $500 cap per transaction

2

Established

Discover + negotiate + execute; $5,000 cap

3

Trusted

Full capabilities, no per-trust transaction caps

4

Verified Partner

Full capabilities + higher rate limits + priority support

How trust is earned

Completing deals successfully (no disputes or chargebacks)
Staying within budget limits consistently
Maintaining low error rates on API calls
Monthly activity scoring (deal volume + quality)
Deal completion rewards boost score faster

Checking an agent's trust level

curl https://api.salesbooth.com/v1/agent-trust \
  -H "Authorization: Bearer sb_test_au_your_agent_key_here" \
  -H "X-Delegation-ID: deleg_a1b2c3d4"

{
  "error": false,
  "success": true,
  "data": {
    "key_id": "key_abc123",
    "trust_level": 2,
    "trust_label": "Established",
    "trust_score": 847,
    "transaction_cap": 5000.00,
    "capabilities": {
      "discover":            { "unlocked": true,  "required_level": 0, "required_label": "Untrusted" },
      "negotiate":           { "unlocked": true,  "required_level": 1, "required_label": "Provisional" },
      "execute":             { "unlocked": true,  "required_level": 2, "required_label": "Established" },
      "autonomous_workflow": { "unlocked": true,  "required_level": 2, "required_label": "Established" },
      "high_value_deals":    { "unlocked": false, "required_level": 3, "required_label": "Trusted" },
      "bulk_operations":     { "unlocked": false, "required_level": 3, "required_label": "Trusted" },
      "priority_support":    { "unlocked": false, "required_level": 4, "required_label": "Verified Partner" }
    },
    "progress": {
      "next_level": 3,
      "next_label": "Trusted",
      "score_required": 150,
      "score_current": 847,
      "score_percent": 100,
      "deals_required": 50,
      "days_required": 90,
      "max_failures_allowed": 5
    }
  }
}

Trust decay

Trust scores decay over time for inactive agents. An agent that hasn't made any successful deals in 30 days will see its score reduced by 10% per month. Keep agents active or explicitly lock their trust level from the dashboard.

Start agents at trust level 0

New integrations should always start at trust level 0 (probationary). This lets you verify the agent behaves as expected before granting autonomy. Manually promote to level 1+ after reviewing its first few actions.

Budget Limits

Every delegation can have spend limits to prevent runaway agent spending.

# Delegation with budget limits
{
  "grantee_agent_key_id": "key_abc123",
  "allowed_actions": ["deals:write"],
  "max_transaction_amount": 1000.00,   // Max value of any single deal
  "max_daily_amount": 10000.00         // Max daily spend across all deals
}

Tenant-level spending controls are configured in the Salesbooth dashboard. To check an individual agent's spending limits and usage, retrieve the delegation object:

GET /api/v1/delegations?id={delegation_id}

Budget exceeded behavior

When an agent attempts a deal that would exceed its budget, the API returns:

HTTP 403 Forbidden
{
  "error": true,
  "code": "delegation_budget_exceeded",
  "category": "authorization_error",
  "message": "Deal total $1,500 exceeds per-deal budget limit of $1,000",
  "recovery": {
    "action": "reduce_proposal_value",
    "retryable": false,
    "hint": "Propose a lower deal value within your remaining delegation budget."
  }
}

Set conservative budgets initially

Start with tight budget limits and expand as you gain confidence in your agent's behavior. A budget-exceeded error is much easier to handle than an unexpected charge.

Next Steps

Quickstart Guide →

Zero to first deal in 5 minutes

Webhook Integration →

Receive deal events server-side

API Reference →

Full agent API documentation