> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tryhamsa.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Set Agent Functions and Macros

> Replaces the agent's functions and macros with this list. New ones start active, ones already assigned keep their switch, ones left out are removed. An empty list removes all. The change is saved in your own draft, like Update Voice Agent: a test call of the draft uses it, and callers get it when the draft is published. Only active ones reach calls. Editing a function or macro itself still applies to every agent right away.



## OpenAPI

````yaml /api-reference/openapi.json put /v2/voice-agents/{voiceAgentId}/functions-macros
openapi: 3.0.1
info:
  title: Hamsa API
  description: >-
    The Hamsa API: voice agents and their calls, phone numbers, batch calls and
    knowledge bases; speech to text, text to speech, voices and AI content.
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://api.tryhamsa.com
security: []
paths:
  /v2/voice-agents/{voiceAgentId}/functions-macros:
    put:
      summary: Set an agent's functions and macros
      description: >-
        Replaces the agent's functions and macros with this list. New ones start
        active, ones already assigned keep their switch, ones left out are
        removed. An empty list removes all. The change is saved in your own
        draft, like Update Voice Agent: a test call of the draft uses it, and
        callers get it when the draft is published. Only active ones reach
        calls. Editing a function or macro itself still applies to every agent
        right away.
      parameters:
        - in: path
          name: voiceAgentId
          required: true
          description: ID of the voice agent.
          schema:
            type: string
            format: uuid
            example: 3f6c8a1e-2b4d-4e7f-9a0b-1c2d3e4f5a6b
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - functionMacroIds
              properties:
                functionMacroIds:
                  type: array
                  items:
                    type: string
                    format: uuid
                  description: >-
                    IDs of the project's functions and macros the agent should
                    have. Empty: remove all.
            examples:
              set:
                summary: Assign functions and macros
                value:
                  functionMacroIds:
                    - 9c1d2e3f-4a5b-4c6d-8e7f-0a1b2c3d4e5f
                    - 2b3c4d5e-6f70-4812-9a3b-4c5d6e7f8091
              clear:
                summary: Remove all
                value:
                  functionMacroIds: []
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: success
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/FunctionMacroAssignment'
        '400':
          description: Invalid body, for example an ID that is not a UUID.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
        '401':
          description: 'Unauthorized: missing or invalid API key.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
        '403':
          description: >-
            Your API key or role does not have the `functions_macros:assign`
            permission.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
        '404':
          description: >-
            Voice agent not found (`VoiceAgentDoesNotExist`), or an ID is not a
            function or macro of this project (`DirectiveNotInProject`): nothing
            is changed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
        '500':
          description: Server Side Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
      security:
        - ApiKeyAuth: []
components:
  schemas:
    FunctionMacroAssignment:
      type: object
      properties:
        id:
          type: string
          format: uuid
          example: 9c1d2e3f-4a5b-4c6d-8e7f-0a1b2c3d4e5f
        projectId:
          type: string
          format: uuid
          example: fbb9e8b2-2dbb-40f9-a051-9404624e3247
        userId:
          type: string
          nullable: true
          example: b7d9e979-4a16-437b-8571-4ed92a94faa8
        createdBy:
          type: string
          description: ID of the member who created it.
          example: b7d9e979-4a16-437b-8571-4ed92a94faa8
        updatedBy:
          type: string
          nullable: true
          description: ID of the member who last changed it.
          example: null
        name:
          type: string
          minLength: 1
          maxLength: 255
          description: >-
            Unique among the project's functions and macros. A `HELPER` macro's
            name is how prompts call it: `{{ <name>(...) }}`.
          example: has_card_number
        notes:
          type: string
          maxLength: 2000
          nullable: true
          description: Your own notes. Not used on calls.
          example: Matches 13 to 19 digits in a row
        type:
          type: string
          enum:
            - JAVASCRIPT_FUNCTION
            - JINJA_MACRO
          description: >-
            `JAVASCRIPT_FUNCTION`: the body of `function (text, vars) { ... }`.
            `JINJA_MACRO`: a Jinja template with `text`, `vars` and `args` in
            scope, or a `{% macro <name>(...) %}` definition.
          example: JAVASCRIPT_FUNCTION
        usedAs:
          type: string
          enum:
            - CHECK
            - ACTION
            - HELPER
          description: >-
            `CHECK`: answers "does this text match?" (a guardrail's `lookFor`).
            `ACTION`: answers "what changes?" (a guardrail's `behaviour`): new
            text, or variables to set. `HELPER`: a macro prompts call by its
            name, as `{{ <name>(...) }}` (`JINJA_MACRO` only).
          example: CHECK
        code:
          type: string
          minLength: 1
          maxLength: 20000
          description: >-
            The code. A function is the body of `function (text, vars) { ... }`.
            A macro is a template, or a `{% macro <name>(...) %}` definition
            (always a definition named like the record for `HELPER`).
          example: return /\d{13,19}/.test(text.replace(/[\s-]/g, ''));
        params:
          type: array
          nullable: true
          maxItems: 20
          items:
            type: string
            maxLength: 64
            pattern: ^[A-Za-z_][A-Za-z0-9_]*$
          description: >-
            `HELPER` macros only: the parameters its `{% macro <name>(...) %}`
            definition declares, in order. `null` for `CHECK` and `ACTION`.
          example: null
        requiredParams:
          type: array
          nullable: true
          readOnly: true
          items:
            type: string
          example:
            - name
          description: >-
            `HELPER` macros only: the parameters without a default value, in
            order; a prompt must pass these. `{% macro greet(name, tone="warm")
            %}` gives `params` `[name, tone]` and `requiredParams` `[name]`.
            `null` for `CHECK` and `ACTION`.
        createdAt:
          type: string
          format: date-time
          example: '2026-10-20T09:15:00.000Z'
        updatedAt:
          type: string
          format: date-time
          example: '2026-10-20T09:15:00.000Z'
        isActive:
          type: boolean
          description: >-
            This agent's on/off switch. Only active ones reach the agent's
            calls.
          example: true
    ErrorSchema:
      type: object
      properties:
        code:
          type: integer
          description: >-
            Service error code: the HTTP status with a service prefix (for
            example `8404`). Missing when the service has no code for that
            status.
          example: 8404
        message:
          type: string
          description: >-
            What went wrong. Some services (calls and recordings) put the error
            key here, for example `CallNotFoundOrUnavailable`, and send no
            `messageKey`.
          example: Policy not found!
        messageKey:
          type: string
          description: >-
            Stable key for the error, safe to match on in code. Not returned by
            every service.
          example: PolicyNotFound
        params:
          type: object
          additionalProperties: true
          description: >-
            Details for some errors (for example `reason`). Not returned by
            every service.
          example:
            reason: NO_DRAFT
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: >-
        Pass the API key in the Authorization header, You need to put Token
        keyword before the API key. e.g. 'Authorization: Token <api-key>'

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.