> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vocobase.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Create a lifecycle hook
> Give the hook a source: either `toolSlug` plus `toolFn` for an integration, or `functionId` for one of your custom functions. Omit `position` to append it to the end of the stage.
These endpoints return a bare object (`{ "hook": … }`, `{ "hooks": [ … ] }`) and a bare `{ "error": … }` on failure, rather than the `success`/`data` envelope used elsewhere in this API. Validation failures return `422` with an `issues` array.
## OpenAPI
````yaml /openapi.json post /agents/{agentId}/lifecycle-hooks
openapi: 3.1.0
info:
title: Vocobase API
version: '2.0'
description: >-
API for managing voice AI agents, documents, and calls on the Vocobase
platform.
servers:
- url: https://api.vocobase.com/api/v2
description: Production
security:
- bearerAuth: []
tags:
- name: Config
description: >-
Read and update account configuration, webhook settings, and telephony
credentials.
- name: Agents
description: Create, read, update, and delete voice AI agents.
- name: Voices
description: >-
List voice tiers, available voices, and stream preview audio for agent
configuration.
- name: Documents
description: Upload, manage, and delete knowledge base documents.
- name: Agent Documents
description: Link and unlink documents to agents for knowledge base integration.
- name: Calls
description: Initiate outbound calls and view call history.
- name: Phone Numbers
description: >-
Import DIDs, assign agents for inbound routing, and re-sync carrier
Application bindings.
- name: Inbound Routing Policies
description: >-
Define pre-answer routing decisions for inbound calls before AI sessions
are created.
- name: Telephony Connections
description: Create, list, rename, and disconnect named V2 telephony connections.
- name: VoiceLink Management
description: Manage VoiceLink reseller clients, DID mapping, and readiness sync.
- name: Projects
description: Organize agents into projects. Every agent belongs to exactly one project.
- name: Dictionaries
description: Speech-recognition dictionary CRUD and agent attachment.
- name: Sessions
description: Browser-initiated WebRTC voice sessions for in-app voice agents.
- name: Campaigns
description: Batch outbound calling.
- name: Billing
description: Balance, transactions, and usage summaries.
- name: Custom Functions
description: HTTP endpoints the agent can call mid-conversation.
- name: Extraction Sets
description: Reusable sets of post-call extraction fields.
- name: Lifecycle Hooks
description: Automatic pre-call and post-call integration steps.
- name: Messaging
description: Bring-your-own WhatsApp sending.
- name: Integration Logs
description: Audit trail for integration calls.
- name: Connectors
description: Catalog of tools an agent can be connected to.
- name: Customers
description: B2B2B sub-tenants and their tool connections.
- name: Agent Tools
description: Binding connectors and connections to an agent.
paths:
/agents/{agentId}/lifecycle-hooks:
post:
tags:
- Lifecycle Hooks
summary: Create a lifecycle hook
description: >-
Give the hook a source: either `toolSlug` plus `toolFn` for an
integration, or `functionId` for one of your custom functions. Omit
`position` to append it to the end of the stage.
These endpoints return a bare object (`{ "hook": … }`, `{ "hooks":
[ … ] }`) and a bare `{ "error": … }` on failure, rather than the
`success`/`data` envelope used elsewhere in this API. Validation
failures return `422` with an `issues` array.
operationId: createLifecycleHook
parameters:
- name: agentId
in: path
required: true
schema:
type: string
format: uuid
description: Agent ID.
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- name
- stage
properties:
stage:
type: string
enum:
- PRE_CALL
- POST_CALL
description: Required.
name:
type: string
toolSlug:
type: string
description: Use with `toolFn` to call an integration.
toolFn:
type: string
functionId:
type: string
format: uuid
description: >-
Use instead of `toolSlug`/`toolFn` to call a custom
function.
input:
type: object
additionalProperties: true
exposeAs:
type: string
description: Pre-call only.
pattern: ^[a-z_][a-z0-9_]*$
required:
type: boolean
default: false
timeoutMs:
type: integer
default: 3000
minimum: 100
maximum: 30000
position:
type: integer
description: Omit to append to the end of the stage.
example:
stage: PRE_CALL
name: Look up lead
toolSlug: leadsquared
toolFn: lookup_lead
input:
phone: '{{to_number}}'
exposeAs: lead
responses:
'201':
description: Hook created.
content:
application/json:
schema:
type: object
properties:
hook:
$ref: '#/components/schemas/LifecycleHook'
example:
hook:
id: lh_2b3c4d5e-6f70-8192-a3b4-c5d6e7f80912
agentId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
stage: PRE_CALL
position: 0
toolSlug: leadsquared
toolFn: lookup_lead
functionId: null
name: Look up lead
input:
phone: '{{to_number}}'
exposeAs: lead
required: false
timeoutMs: 3000
enabled: true
createdAt: '2026-08-05T11:20:00.000Z'
updatedAt: '2026-08-05T11:20:00.000Z'
'400':
description: '`stage` missing or not one of the two allowed values.'
content:
application/json:
schema:
type: object
properties:
error:
type: string
example:
error: stage must be PRE_CALL or POST_CALL
'401':
$ref: '#/components/responses/Unauthorized'
'404':
description: Agent not found.
content:
application/json:
schema:
type: object
properties:
error:
type: string
example:
error: Agent not found
'422':
description: Validation failed. `issues` lists each problem field.
content:
application/json:
schema:
type: object
properties:
error:
type: string
const: VALIDATION_FAILED
issues:
type: array
items:
type: object
properties:
field:
type: string
code:
type: string
message:
type: string
example:
error: VALIDATION_FAILED
issues:
- field: exposeAs
code: DUPLICATE
message: exposeAs 'lead' is already used in PRE_CALL
'429':
$ref: '#/components/responses/RateLimitExceeded'
'500':
$ref: '#/components/responses/InternalError'
components:
schemas:
LifecycleHook:
type: object
properties:
id:
type: string
format: uuid
agentId:
type: string
format: uuid
stage:
type: string
enum:
- PRE_CALL
- POST_CALL
position:
type: integer
description: Run order within the stage, ascending.
toolSlug:
type: string
nullable: true
description: Integration slug, when the hook calls a connector.
toolFn:
type: string
nullable: true
description: Function on that integration, e.g. `lookup_lead`.
functionId:
type: string
format: uuid
nullable: true
description: >-
Custom function ID, when the hook calls one of your own functions
instead.
name:
type: string
description: Required. 1–200 characters.
input:
type: object
additionalProperties: true
description: >-
Substitution template. Values are filled from call variables and the
output of earlier hooks.
exposeAs:
type: string
nullable: true
description: >-
Name the result is published under in the variables map, so the
prompt can read `{{lead.FirstName}}`. Pre-call only, and unique per
agent within the stage.
pattern: ^[a-z_][a-z0-9_]*$
required:
type: boolean
description: >-
When `true`, a failure of this hook fails the call rather than being
skipped.
timeoutMs:
type: integer
default: 3000
minimum: 100
maximum: 30000
enabled:
type: boolean
description: Soft-disable without deleting, so ordering stays stable.
createdAt:
type: string
format: date-time
updatedAt:
type: string
format: date-time
ErrorResponse:
type: object
properties:
success:
type: boolean
const: false
error:
type: object
properties:
code:
type: string
message:
type: string
required:
- code
- message
required:
- success
- error
responses:
Unauthorized:
description: Missing or invalid API key.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
success: false
error:
code: UNAUTHORIZED
message: Invalid or missing API key
RateLimitExceeded:
description: Per-account rate limit exceeded. Retry after a short backoff.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
success: false
error:
code: RATE_LIMITED
message: Rate limit exceeded. Retry after 60 seconds.
InternalError:
description: Unexpected server error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
success: false
error:
code: INTERNAL_ERROR
message: An unexpected error occurred
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: >-
API key in format: `rg_live_xxxx`. Pass as a Bearer token in the
Authorization header.
````