Sign in

v1

latestOpenAPI 3.1.02026-07-26359254.7 MB
AI SDR Knowledge Bases

Create a reply handler

<Info> **Beta.** This endpoint is in beta. Behavior, parameters, and response shapes may change without notice. </Info>

<small>Requires the ai-sdr:write scope (or a broader one that includes it).</small>

Creates a new reply handler attached to a knowledge base.

Requires the AI SDR feature on the caller's team.

post/v3/ai-sdr/knowledge-bases/{knowledge_base_id}/reply-handlers

Path parameters

knowledge_base_idinteger required

Request body

typeOfQuestionstring required

Short label describing the type of incoming reply this handler covers

instructionsstring required

Instructions for how to handle replies of this type

sampleAnswerstring

Optional sample answer used as a few-shot example

toneOfVoice'confident' | 'persuasive' | 'witty' | 'straightforward' | 'empathetic'

Tone applied to generated replies and reengagement messages.

responseLength'superShort' | 'short' | 'medium' | 'long'

Target length of generated replies and reengagement messages.

linksstring[]

Reference URLs (max 10; each non-empty, max 256 chars)

deliveryMode'draft' | 'auto' | 'stopAndNotify'

How generated replies for this handler are delivered. Defaults to draft when omitted.

additionalNotificationEmailstring email nullable

Extra recipient notified when a reply is handled with stopAndNotify. Ignored for other delivery modes.

Example request

{
  "typeOfQuestion": "Pricing inquiry",
  "instructions": "Quote our published tiered pricing; offer a discovery call for enterprise.",
  "sampleAnswer": "Thanks for asking! Our tiered pricing starts at $X...",
  "toneOfVoice": "confident",
  "responseLength": "medium",
  "links": [
    "https://example.com/pricing"
  ],
  "deliveryMode": "draft"
}

Response

Reply handler created successfully

idstring uuid

Unique identifier for the reply handler

typeOfQuestionstring

Short label describing the type of incoming reply this handler covers

instructionsstring

Instructions for how to handle replies of this type

sampleAnswerstring

Optional sample answer used as a few-shot example

toneOfVoice'confident' | 'persuasive' | 'witty' | 'straightforward' | 'empathetic'

Tone applied to generated replies

responseLength'superShort' | 'short' | 'medium' | 'long'

Target length for generated replies

linksstring[]

Reference URLs the AI SDR can quote when generating a reply

deliveryMode'draft' | 'auto' | 'stopAndNotify'

How generated replies for this handler are delivered

additionalNotificationEmailstring nullable

Extra recipient notified when a reply is handled with stopAndNotify. Ignored for other delivery modes.

createdAtstring date-time

Timestamp when the reply handler was created

Example response

{
  "id": "9c1f8a7e-0b3a-4d11-9b9c-2c4f8a7e0b3a",
  "typeOfQuestion": "Pricing inquiry",
  "instructions": "Quote our published tiered pricing; offer a discovery call for enterprise.",
  "sampleAnswer": "Thanks for asking! Our tiered pricing starts at $X...",
  "toneOfVoice": "confident",
  "responseLength": "medium",
  "links": [
    "https://example.com/pricing"
  ],
  "media": [
    {
      "id": 12345,
      "fileName": "pricing-tiers.png",
      "size": 248
    }
  ],
  "deliveryMode": "draft",
  "additionalNotificationEmail": null,
  "createdAt": "2026-05-10T14:32:11Z"
}