Free setup on annual plans

Sign up today!
Book a Demo

Hooks

Home

> API Reference >

Endpoints >

Hooks

API Reference: Hooks endpoints

Hooks are named AnswerPal workflow events that can collect prompt documents and execute configured actions at a specific stage of a ticket or message flow. The API exposes hook-action configuration, hook prompt-document configuration and ticket-message runtime endpoints that execute or resolve hooks.

Overview and current endpoints

Hook configuration is customer-scoped. A hook action links a reusable action definition to a hook name and optional channel target. A hook document links a document to the same hook name so prompts can include event-specific instructions. At runtime, TicketMessages endpoints can resolve hook prompt documents or execute the configured action chain for a message.

HookActions

  • GET /api/HookActions – Bearer JWT
    List hook-action links. At least one filter is required: hookName or actionId. Query also supports pageNumber, pageSize, sortBy and sortOrder. pageNumber is normalized to at least 1; pageSize is clamped to 1-100.
  • POST /api/HookActions – Bearer JWT
    Create one hook-action link from HookActionCreateDTO. The server sets customer scope and stores hookName as the hook special topic. Duplicate combinations return 409 Conflict.
  • POST /api/HookActions/bulk – Bearer JWT
    Create multiple hook-action links. Existing combinations are skipped by the service; database errors return 500.
  • GET /api/HookActions/{id} – Bearer JWT
    Read one owned hook-action link. Records with no hook special topic, or specialTopic=All, are not treated as HookActions.
  • PUT /api/HookActions/{id} – Bearer JWT
    Update only the priority of an existing owned hook-action link.
  • DELETE /api/HookActions/{id} – Bearer JWT
    Delete one owned hook-action link.
  • GET /api/HookActions/wait-seconds – Bearer JWT
    Return the total wait time for active Wait actions matching channelId and hookName. Query: channelId and hookName.

HookDocuments

  • GET /api/HookDocuments/promptDocuments – TicketAccessOrPhoneAuth
    Return PromptDocumentDTO records for a hookName and optional channelId. Phone-auth requests are restricted to the token channel. Special placeholders in document content are replaced before return.
  • POST /api/HookDocuments – Bearer JWT
    Create a hook-document link using TopicDocumentCreateDTO. For hooks, topicID should be null and specialTopic should be the hook name. Duplicate links return 409 Conflict.

Ticket-message runtime endpoints

  • GET /api/TicketMessages/{id}/promptDocuments – TicketAccessOrPhoneAuth
    Return prompt documents for a message. Optional query hookName selects hook documents; topicId selects topic documents; onlyPromptDocuments skips historical ticket/end-user data.
  • POST /api/TicketMessages/{id}/execute-hook – TicketAccessOrPhoneAuth
    Execute all configured actions for query hookName against the ticket message. Phone-auth requests must match the message channel.
  • GET /api/TicketMessages/{id}/execute-single-action – TicketAccess
    Execute one action type manually for a message. Query: action and optional stage, defaulting to UserTriggered.

Supported hook names

Current HookName enum values:

  • PreSpam, PostSpam, PostTopicDetection
  • OnEscalate, PostEscalate, OnEscalateFailed
  • OnClose, UserTriggered
  • OnEndUserAdd, OnEndUserUpdate, OnEndUserDelete
  • OnPhonePickup, OnPhonePickupSay

Access and errors

  • Inbound authentication
    Protected AnswerPal API endpoints use JWT Bearer authentication. HookActions and HookDocuments creation require an authenticated customer context.
  • Phone-auth hook access
    GET /api/HookDocuments/promptDocuments, GET /api/TicketMessages/{id}/promptDocuments and POST /api/TicketMessages/{id}/execute-hook accept phone-auth context where configured. Phone-auth calls are rejected with 403 when the requested or message channel differs from the token channel.
  • 400 Bad Request
    GET /api/HookActions requires hookName or actionId. Ticket-message prompt documents can also return 400 when historical data is requested and the customer OpenAI API key is missing.
  • 404 Not Found
    Hook action, hook document, ticket message or customer was not found in the authenticated scope.
  • 409 Conflict
    Duplicate hook-action or hook-document combinations.
  • 500 Server Error
    Unexpected database errors during bulk hook-action creation or hook-document creation.

Fields and DTOs

HookAction fields

HookAction fields

  • hookActionID
    Response-only identifier mapped from TopicActionID.
  • hookName
    Required enum value on create and query filters. Must be a current HookName value.
  • actionID, actionName
    Action reference and response-only action display name. The action definition itself is managed through the Actions API.
  • channelID, channelName
    Optional specific channel target and response-only channel display name.
  • specialChannel
    Optional broad channel target such as All or a channel type. Runtime matching accepts the exact channelID, All, or the current channel type.
  • priority
    Execution ordering. Lower priority runs earlier. Update requests can change only this field.

HookAction query and response fields

  • pageNumber, pageSize, sortBy, sortOrder
    List pagination and sorting. Supported sort fields include ActionName, HookName, ChannelName, TopicName and Priority.
  • items, totalCount, totalPages
    PaginatedResult fields returned by HookActions list.
  • totalWaitSeconds
    Returned by HookWaitSecondsDTO from /api/HookActions/wait-seconds.

HookDocument and prompt fields

HookDocument link fields

  • topicDocumentID, customerID
    Response-only link identifier and customer scope when a hook document link is created.
  • topicID, specialTopic
    For hook documents, topicID should be null and specialTopic should be the hook name.
  • documentID, documentName
    Document being linked and response-only document display name.
  • channelID, channelName, specialChannel
    Optional channel-specific target. Runtime matching accepts exact channel, All, or channel type.

Prompt document fields

  • documentID, name, content, contentType
    Prompt document identity and content returned by hook document resolution.
  • includeInRealtimeInstructions, imageUrls
    Realtime inclusion flag and image URLs used by prompt construction.

Runtime response fields

PromptDocumentsExtendedDTO fields

  • promptDocuments
    PromptDocumentDTO list returned for a message.
  • endUsers, tickets
    Historical context lists included when onlyPromptDocuments is false.
  • onlyPromptDocuments
    Query flag. When false, the endpoint also loads historical data and requires the customer OpenAI API key to be configured.

Execute hook response fields

  • message
    Text summary such as Hook OnEscalate actions executed.
  • finished
    Boolean returned by the action execution service.
  • stage
    Optional query for execute-single-action, defaulting to UserTriggered.

Examples

List hook actions for a hook

GET /api/HookActions?hookName=PreSpam&pageNumber=1&pageSize=10&sortBy=Priority&sortOrder=asc
Authorization: Bearer <token>

Create a hook action

POST /api/HookActions
Authorization: Bearer <token>
Content-Type: application/json

{
  "hookName": "OnEscalate",
  "actionID": 123,
  "channelID": 5,
  "specialChannel": null,
  "priority": 10
}

Create a hook document link

POST /api/HookDocuments
Authorization: Bearer <token>
Content-Type: application/json

{
  "topicID": null,
  "specialTopic": "OnPhonePickup",
  "documentID": 501,
  "channelID": 5,
  "specialChannel": null
}

Resolve and execute a runtime hook

GET /api/TicketMessages/987/promptDocuments?hookName=OnPhonePickup&onlyPromptDocuments=true
Authorization: Bearer <token>

POST /api/TicketMessages/987/execute-hook?hookName=OnPhonePickup
Authorization: Bearer <token>

Calculate wait time for a phone hook

GET /api/HookActions/wait-seconds?channelId=5&hookName=OnPhonePickup
Authorization: Bearer <token>

Best practices

  • Use current HookName enum values exactly. Do not invent hook names outside the enum.
  • Use channelID for a specific channel and specialChannel for broad targeting such as All or a channel type. Avoid setting both unless the intended precedence is clear.
  • Keep hook priorities sparse enough to insert future steps without reordering every existing link.
  • For PostTopicDetection, runtime action lookup combines hook actions with actions attached to detected message topics.
  • Use /api/HookActions/wait-seconds before phone pickup/say flows when UI or telephony timing needs the total Wait duration.
  • Use HookDocuments for event-specific prompt instructions; use Documents and TopicDocuments pages for the full document-management model.

Detailed endpoint notes

HookActions list

GET /api/HookActions requires hookName or actionId. The endpoint returns only hook records with active actions and excludes specialTopic=All.

Create and bulk create

POST /api/HookActions and POST /api/HookActions/bulk map hookName to the hook special topic and set customer scope server-side.

Update, delete and wait seconds

PUT /api/HookActions/{id} updates only priority. GET /api/HookActions/wait-seconds sums active Wait actions after channel and hook matching.

HookDocuments

GET /api/HookDocuments/promptDocuments returns hook prompt documents. POST /api/HookDocuments creates a hook document link from the TopicDocumentCreateDTO shape.

Ticket-message runtime hooks

Use /api/TicketMessages/{id}/promptDocuments and /api/TicketMessages/{id}/execute-hook when a specific message is the runtime context for the hook.

Supported hook names

Current HookName enum values:

  • PreSpam, PostSpam, PostTopicDetection
  • OnEscalate, PostEscalate, OnEscalateFailed
  • OnClose, UserTriggered
  • OnEndUserAdd, OnEndUserUpdate, OnEndUserDelete
  • OnPhonePickup, OnPhonePickupSay

FAQ

A hook is a named workflow event such as PreSpam, PostTopicDetection, OnEscalate or OnPhonePickup. Hook actions and hook documents attach automation and prompt context to that event.

The reusable action definition lives in /api/Actions. /api/HookActions links that action to a hook name, channel target and priority.

They use the same topic-document link shape, but for hooks topicID is null and specialTopic contains the hook name.

Yes for endpoints that allow TicketAccessOrPhoneAuth, but the token channel must match the requested or message channel. Mismatches return 403 Forbidden.

Table of Contents

AnswerPal: AI-powered customer service solutions to elevate your support and communication effortlessly.

Quick Links

Contact

For all support, sales, and partnership inquiries, email us at info@answerpal.eu

AnswerPal
Bisschoppenhoflaan 380
2100 Antwerp
Belgium

+32.36416685

BE 0862.692.858

Social Icons