Agent Integrations

Integration Request Types

Both request types include the same authentication headers. See Request Signing & Security.

Webhook Events

Call Start Webhook

When a call starts, a POST request is sent to the configured webhook URL.

Request Format (JSON-RPC 2.0)

{
  "id": "uuid",
  "jsonrpc": "2.0",
  "method": "webhook/lifecycle",
  "metadata": {},
  "params": {
    "event": "new_outbound_call",
    "timestamp": "2024-01-15T10:30:00.000Z",
    "metadata": {},
    "agent": {
      "id": "agent-uuid",
      "timezone": "America/New_York"
    },
    "call": {
      "id": "call-uuid",
      "status": "initializing",
      "direction": "outbound",
      "channel": "phone",
      "caller": "+1234567890",
      "callee": "+0987654321",
      "userPhoneNumber": "+0987654321",
      "personalization": {}
    }
  }
}

Request Fields

Custom Tool Calls

Configure a custom REST API tool or MCP tool in the agent settings. When the agent invokes it, VocoAgents sends the tool arguments together with the current integration context under metadata. REST tool arguments remain at the top level; metadata is a reserved top-level integration field.

REST API tool (POST, PUT, or DELETE)

{
  "customer_id": "CRM-12345",
  "action": "get_status",
  "metadata": {
    "source": "widget",
    "userAgent": "Mozilla/5.0 ...",
    "location": "https://example.com/pricing",
    "crm_contact_id": "CRM-12345"
  }
}

MCP tool (JSON-RPC 2.0 runtime shape)

{
  "id": "uuid",
  "jsonrpc": "2.0",
  "method": "lookup_customer",
  "metadata": {
    "source": "widget",
    "userAgent": "Mozilla/5.0 ...",
    "location": "https://example.com/pricing",
    "crm_contact_id": "CRM-12345"
  },
  "params": {
    "customer_id": "CRM-12345"
  }
}

Metadata

metadata is an object containing the effective session metadata. REST arguments remain at the top level, while MCP arguments remain under params. Metadata starts with metadata supplied with the engagement and is overlaid with metadata returned by the enrichment webhook. If both contain the same key, the webhook value wins. Metadata is pass-through context and may contain custom keys from your widget, campaign, or webhook. Do not define metadata as a REST tool parameter because the name is reserved for this integration context.

For a REST GET tool, the tool parameters remain URL query parameters because GET requests do not have a JSON request body. The same metadata is still available in the x-voco-session-metadata header.

Expected Response

The webhook should return a JSON response with a result object.

Response Format

{
  "result": {
    "personalization": {
      "first_name": "Joe",
      "sex": "unknown",
      "language": "en"
    },
    "additional_context": "## Customer\n- Plan: Pro\n- Open ticket #1234",
    "metadata": {
      "crm_id": "CRM-12345",
      "segment": "enterprise"
    }
  }
}

Response Fields

Implementation Examples

Ready-to-use starting points you can hand to a developer or automation partner. Each one receives the call-start request, reads the visitor id from params.call.id, and returns the personalization response shown above. Replace the example data with a lookup against your own CRM or database.

{
  "name": "VocoAgents Personalization Webhook",
  "nodes": [
    {
      "parameters": {
        "httpMethod": "POST",
        "path": "vocoagents-personalization",
        "responseMode": "responseNode",
        "options": {}
      },
      "name": "Webhook",
      "type": "n8n-nodes-base.webhook",
      "typeVersion": 2,
      "position": [
        260,
        300
      ],
      "webhookId": "vocoagents-personalization"
    },
    {
      "parameters": {
        "jsCode": "const id = $input.first().json.body?.params?.call?.id;\n// TODO: look up the visitor by id in your CRM / database\nreturn [{ json: { result: {\n  personalization: { first_name: 'Joe', sex: 'unknown', language: 'en' },\n  additional_context: '## Customer\\n- Plan: Pro\\n- Open ticket #1234'\n} } }];"
      },
      "name": "Build personalization",
      "type": "n8n-nodes-base.code",
      "typeVersion": 2,
      "position": [
        480,
        300
      ]
    },
    {
      "parameters": {
        "respondWith": "json",
        "responseBody": "={{ $json }}",
        "options": {}
      },
      "name": "Respond to Webhook",
      "type": "n8n-nodes-base.respondToWebhook",
      "typeVersion": 1,
      "position": [
        700,
        300
      ]
    }
  ],
  "connections": {
    "Webhook": {
      "main": [
        [
          {
            "node": "Build personalization",
            "type": "main",
            "index": 0
          }
        ]
      ]
    },
    "Build personalization": {
      "main": [
        [
          {
            "node": "Respond to Webhook",
            "type": "main",
            "index": 0
          }
        ]
      ]
    }
  }
}

{
  "name": "VocoAgents Personalization Webhook",
  "flow": [
    {
      "id": 1,
      "module": "gateway:CustomWebHook",
      "version": 1,
      "parameters": {
        "hook": null,
        "maxResults": 1
      },
      "mapper": {},
      "metadata": {
        "designer": {
          "x": 0,
          "y": 0
        }
      }
    },
    {
      "id": 2,
      "module": "gateway:WebhookRespond",
      "version": 1,
      "parameters": {},
      "mapper": {
        "status": "200",
        "headers": [
          {
            "key": "Content-Type",
            "value": "application/json"
          }
        ],
        "body": "{\n  \"result\": {\n    \"personalization\": {\n      \"first_name\": \"Joe\",\n      \"sex\": \"unknown\",\n      \"language\": \"en\"\n    },\n    \"additional_context\": \"## Customer\\n- Plan: Pro\\n- Open ticket #1234\"\n  }\n}"
      },
      "metadata": {
        "designer": {
          "x": 300,
          "y": 0
        }
      }
    }
  ],
  "metadata": {
    "version": 1,
    "scenario": {
      "roundtrips": 1,
      "maxErrors": 3,
      "autoCommit": true
    },
    "designer": {
      "orphans": []
    }
  }
}

// VocoAgents personalization webhook — minimal Express server
// Install:  npm i express
// Run:      node server.js
import express from 'express';

const app = express();
app.use(express.json());

app.post('/vocoagents/personalization', async (req, res) => {
  const id = req.body?.params?.call?.id;

  // TODO: look up the visitor by `id` in your CRM / database
  // const user = await db.findVisitor(id);

  res.json({
    result: {
      personalization: {
        first_name: 'Joe',
        sex: 'unknown',
        language: 'en'
      },
      additional_context: '## Customer\n- Plan: Pro\n- Open ticket #1234'
    }
  });
});

app.listen(3000, () => console.log('Webhook listening on :3000'));

Call End Webhook

When a call ends, the same webhook receives a call_ended event with full call details.

Request Format

{
  "id": "uuid",
  "jsonrpc": "2.0",
  "method": "webhook/lifecycle",
  "metadata": {},
  "params": {
    "event": "call_ended",
    "timestamp": "2024-01-15T10:35:00.000Z",
    "metadata": {
      "crm_id": "CRM-12345",
      "segment": "enterprise"
    },
    "agent": {
      "id": "agent-uuid",
      "timezone": "America/New_York"
    },
    "call": {
      "id": "call-uuid",
      "status": "ended",
      "direction": "outbound",
      "channel": "phone",
      "caller": "+1234567890",
      "callee": "+0987654321",
      "userPhoneNumber": "+0987654321",
      "personalization": { "language": "en" },
      "ended_at": "2024-01-15T10:35:00.000Z",
      "ended_by": "user",
      "duration": 300,
      "transcript": [
        { "role": "assistant", "text": "Hello, how can I help you today?" },
        { "role": "user", "text": "I have a question about my account." }
      ],
      "summary": "Customer inquired about account balance.",
      "recording_url": "https://storage.example.com/recordings/call.wav",
      "objective_met": true,
      "extraction_data": {
        "customer_sentiment": "positive",
        "issue_category": "billing"
      }
    }
  }
}

Additional Call End Fields