Reference

Templates API

CRUD operations for voice agent templates — create, list, update, and delete.

Overview

Templates define the conversational flow, system prompts, functions, and hooks for a voice agent. All template endpoints are RBAC-filtered — callers only see templates they have access to based on their role, reseller, and merchant scope.

Create template

POST /templates Create a new voice agent template.

Request Body

json

{
  "name": "appointment-reminder",
  "reseller_id": "res_001",
  "merchant_id": "mer_abc",
  "flow": {
    "initial_node": "greeting",
    "nodes": [
      {
        "node_name": "greeting",
        "task_messages": [
          {
            "role": "system",
            "content": "You are a friendly appointment reminder agent. Greet the customer and confirm their appointment on {appointment_date}."
          }
        ],
        "functions": [],
        "pre_actions": [],
        "post_actions": []
      }
    ]
  }
}

Response

json

{
  "id": "tpl_xyz789",
  "name": "appointment-reminder",
  "reseller_id": "res_001",
  "merchant_id": "mer_abc",
  "flow": { "..." },
  "created_at": "2025-01-15T10:30:00Z",
  "updated_at": "2025-01-15T10:30:00Z"
}

List templates

GET /templates Returns all templates visible to the authenticated caller. RBAC-filtered automatically.

Query Param	Type	Description
`reseller_id`	`string`	Filter by reseller (admin/reseller roles)
`merchant_id`	`string`	Filter by merchant

Get template by ID

GET /templates/{id} Returns the full template object including flow definition, functions, and hooks.

Update template

PUT /templates/{id} Update an existing template. Replaces the entire definition.

GET → Edit → PUT Contract

Always GET the template first, modify the returned object, and PUT the entire modified object back. The API replaces the full document — partial updates are not supported.

Request Body

json

{
  "id": "tpl_xyz789",
  "name": "appointment-reminder-v2",
  "reseller_id": "res_001",
  "merchant_id": "mer_abc",
  "flow": {
    "initial_node": "greeting",
    "nodes": [
      {
        "node_name": "greeting",
        "task_messages": [
          {
            "role": "system",
            "content": "You are a friendly appointment reminder agent. Greet the customer by name and confirm their appointment."
          }
        ],
        "functions": [],
        "pre_actions": [],
        "post_actions": []
      }
    ]
  }
}

Delete template

DELETE /templates/{id} Delete a template by ID.

Deletion Constraint

A template cannot be deleted if it is referenced by any existing leads. Cancel or remove the associated leads first.

Error responses

Status	Meaning	Common Cause
`400`	Bad Request	Invalid flow structure or missing required fields
`404`	Not Found	Template ID does not exist or is not accessible
`409`	Conflict	Cannot delete — template is referenced by active leads

Was this helpful?

Edit on GitHub