Phone Numbers

6 actions. Each is callable by the agent as a tool, over HTTP via /api/invoke, and (usually) from a UI page.

`phone_numbers.list`

GET

List all phone numbers the workspace owns. Each is assignable to a human or agent actor.

AI tool: phone_numbers_list
API: GET /api/invoke/phone_numbers.list

Input

Field	Type	Required
`assignedToActorId`	string	—
`projectId`	string	—
`subjectId`	string	—

JSON Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "assignedToActorId": {
      "type": "string",
      "minLength": 1
    },
    "projectId": {
      "type": "string",
      "minLength": 1
    },
    "subjectId": {
      "type": "string",
      "minLength": 1
    }
  }
}

`phone_numbers.get`

GET

Get one phone number with its extensions.

AI tool: phone_numbers_get
API: GET /api/invoke/phone_numbers.get

Input

Field	Type	Required	Description
`id`	string	yes

JSON Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "minLength": 1
    }
  },
  "required": [
    "id"
  ]
}

`phone_numbers.inventory`

GET

List numbers available for provisioning from the upstream provider (Twilio). Use to pick a number before calling phone_numbers.allocate.

AI tool: phone_numbers_inventory
API: GET /api/invoke/phone_numbers.inventory

Input

Field	Type	Required	Description
`countryCode`	string	—
`areaCode`	union	—

JSON Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "countryCode": {
      "default": "US",
      "type": "string",
      "minLength": 2,
      "maxLength": 2
    },
    "areaCode": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "number"
        }
      ]
    }
  }
}

`phone_numbers.allocate`

POST · mutating

Allocate a phone number scoped to a project — provisions on Twilio when configured, otherwise records it as simulated. Assigns to the given actor.

AI tool: phone_numbers_allocate
API: POST /api/invoke/phone_numbers.allocate

Input

Field	Type	Required
`number`	string	yes
`provider`	"twilio" \| "voip-internal" \| "forward" \| "simulated"	—
`assignedToActorId`	string	—
`label`	string	—
`description`	string	—
`forwardToNumber`	string	—
`voipEnabled`	boolean	—
`inboundBehavior`	"answer-immediately" \| "ring-then-fallback" \| "voicemail-only" \| "ivr"	—
`smsAutoRespond`	boolean	—
`voiceAutoAnswer`	boolean	—
`projectId`	string	yes
`subjectId`	string	—

JSON Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "number": {
      "type": "string"
    },
    "provider": {
      "type": "string",
      "enum": [
        "twilio",
        "voip-internal",
        "forward",
        "simulated"
      ]
    },
    "assignedToActorId": {
      "type": "string",
      "minLength": 1
    },
    "label": {
      "type": "string"
    },
    "description": {
      "type": "string"
    },
    "forwardToNumber": {
      "type": "string"
    },
    "voipEnabled": {
      "type": "boolean"
    },
    "inboundBehavior": {
      "type": "string",
      "enum": [
        "answer-immediately",
        "ring-then-fallback",
        "voicemail-only",
        "ivr"
      ]
    },
    "smsAutoRespond": {
      "type": "boolean"
    },
    "voiceAutoAnswer": {
      "type": "boolean"
    },
    "projectId": {
      "type": "string",
      "minLength": 1
    },
    "subjectId": {
      "type": "string",
      "minLength": 1
    }
  },
  "required": [
    "number",
    "projectId"
  ]
}

`phone_numbers.update`

PATCH · mutating

Update a phone number — reassign, change behavior, toggle SMS auto-respond, etc.

AI tool: phone_numbers_update
API: PATCH /api/invoke/phone_numbers.update

Input

Field	Type	Required	Description
`id`	string	yes
`patch`	object	yes

JSON Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "minLength": 1
    },
    "patch": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "minLength": 1
        },
        "number": {
          "type": "string"
        },
        "provider": {
          "default": "simulated",
          "type": "string",
          "enum": [
            "twilio",
            "voip-internal",
            "forward",
            "simulated"
          ]
        },
        "providerRef": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "label": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "description": {
          "default": "",
          "type": "string"
        },
        "assignedToActorId": {
          "anyOf": [
            {
              "type": "string",
              "minLength": 1
            },
            {
              "type": "null"
            }
          ]
        },
        "forwardToNumber": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "voipEnabled": {
          "default": false,
          "type": "boolean"
        },
        "inboundBehavior": {
          "default": "answer-immediately",
          "type": "string",
          "enum": [
            "answer-immediately",
            "ring-then-fallback",
            "voicemail-only",
            "ivr"
          ]
        },
        "voicemailGreeting": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "smsAutoRespond": {
          "default": true,
          "type": "boolean"
        },
        "voiceAutoAnswer": {
          "default": false,
          "type": "boolean"
        },
        "config": {
          "default": {},
          "type": "object",
          "propertyNames": {
            "type": "string"
          },
          "additionalProperties": {}
        },
        "projectId": {
          "anyOf": [
            {
              "type": "string",
              "minLength": 1
            },
            {
              "type": "null"
            }
          ]
        },
        "subjectId": {
          "anyOf": [
            {
              "type": "string",
              "minLength": 1
            },
            {
              "type": "null"
            }
          ]
        },
        "active": {
          "default": true,
          "type": "boolean"
        },
        "createdAt": {},
        "updatedAt": {}
      }
    }
  },
  "required": [
    "id",
    "patch"
  ]
}

`phone_numbers.release`

DELETE · mutating

Release a phone number back to the provider (Twilio). Soft-deletes if simulated.

AI tool: phone_numbers_release
API: DELETE /api/invoke/phone_numbers.release

Input

Field	Type	Required	Description
`id`	string	yes

JSON Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "minLength": 1
    }
  },
  "required": [
    "id"
  ]
}