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

# Create Agent

> Creates a new Agent

This endpoint lets you create a new agent.

## Tool Input Types

When defining a tool's `api_schema`, every parameter (in `path_params`, `query_params`, `request_headers`, or `request_body`) takes an `input` object that tells the platform where the value should come from at call time.

There are two input types:

<AccordionGroup>
  <Accordion title="type: description (LLM-extracted)" icon="wand-magic-sparkles">
    The agent extracts the value from the conversation based on the description you provide.

    ```json theme={null}
    "message": {
      "type": "string",
      "input": {
        "type": "description",
        "description": "The exact message sent by the customer"
      }
    }
    ```
  </Accordion>

  <Accordion title="type: value (hardcoded)" icon="lock">
    Use a literal value, or a built-in template variable that gets substituted at call time. Template variables are written as `%VARIABLE_NAME%`.

    ```json theme={null}
    "phone_number": {
      "type": "string",
      "input": {
        "type": "value",
        "value": "%PHONE_NUMBER%"
      }
    }
    ```

    You can also pass any plain string (e.g. an API key, a fixed endpoint, a constant flag):

    ```json theme={null}
    "Authorization": {
      "type": "string",
      "input": {
        "type": "value",
        "value": "Bearer sk-live-..."
      }
    }
    ```
  </Accordion>
</AccordionGroup>

## Built-in Template Variables

When an `input` of `type: "value"` contains one of the following tokens, the platform replaces it with the appropriate runtime value before the tool is invoked:

| Variable         | Replaced with                                                                                                      |
| ---------------- | ------------------------------------------------------------------------------------------------------------------ |
| `%PHONE_NUMBER%` | The customer's WhatsApp phone number for the current session                                                       |
| `%IMAGE_URL%`    | The URL of the most recent image the customer sent (if the triggering message was an image)                        |
| `%CALLBACK_URL%` | A unique callback URL for this tool invocation — POST to it to send a follow-up message back into the conversation |

Tokens are substituted anywhere they appear inside a string value, so you can interpolate them into URLs, headers, query params, and request body fields.

### Example

A `forward_message` tool that posts the customer's phone number, message text, attached image, and a reply callback to your own webhook:

```json theme={null}
{
  "url": "https://your-app.example.com/webhooks/agent",
  "method": "POST",
  "path_params": {},
  "query_params": { "required": [], "properties": {} },
  "request_body": {
    "type": "object",
    "required": [],
    "properties": {
      "phone_number": {
        "type": "string",
        "input": { "type": "value", "value": "%PHONE_NUMBER%" }
      },
      "message": {
        "type": "string",
        "input": {
          "type": "description",
          "description": "The exact message sent by the customer"
        }
      },
      "image": {
        "type": "string",
        "input": { "type": "value", "value": "%IMAGE_URL%" }
      },
      "reply_callback": {
        "type": "string",
        "input": { "type": "value", "value": "%CALLBACK_URL%" }
      }
    }
  }
}
```

<Note>
  `%IMAGE_URL%` is only populated when the message that triggered the tool call was an image. For text-only messages the field is omitted from the outgoing request.
</Note>


## OpenAPI

````yaml /api-reference/openapi.json POST /api/v1/agents/
openapi: 3.0.3
info:
  title: Wassist API
  version: 1.0.0
  description: API for building WhatsApp AI agents
servers:
  - url: https://backend.wassist.app
    description: Production
  - url: http://localhost:8050
    description: Development
security: []
tags:
  - name: Agents
    description: Create and manage AI agents
  - name: Conversations
    description: Chat conversations and messages
  - name: WhatsApp
    description: WhatsApp Business account management
  - name: Contacts
    description: Contact management
  - name: Integrations
    description: Third-party integrations
paths:
  /api/v1/agents/:
    post:
      tags:
        - api
      description: |-
        ViewSet for managing agents (bots).

        Endpoints:
        - GET /agents/ - List all agents
        - POST /agents/ - Create a new agent
        - GET /agents/{id}/ - Get agent details
        - PUT /agents/{id}/ - Update agent with all sub-resources
        - DELETE /agents/{id}/ - Delete an agent
        - POST /agents/{id}/deploy/ - Deploy to WhatsApp number
        - POST /agents/{id}/share/ - Share with another user
        - POST /agents/{id}/unshare/ - Remove sharing
      operationId: api_v1_agents_create
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAgentInput'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Agent'
          description: ''
      security:
        - ApiKeyAuth: []
components:
  schemas:
    CreateAgentInput:
      type: object
      properties:
        name:
          type: string
          maxLength: 255
      required:
        - name
    Agent:
      type: object
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
        name:
          type: string
          maxLength: 255
        description:
          type: string
        systemPrompt:
          type: string
        firstMessage:
          type: string
        profilePicture:
          type: string
          readOnly: true
        icebreakers: {}
        tools:
          type: array
          items:
            $ref: '#/components/schemas/AgentTool'
          readOnly: true
        documents:
          type: array
          items:
            $ref: '#/components/schemas/AgentDocument'
          readOnly: true
        memoryKeys:
          type: array
          items:
            $ref: '#/components/schemas/AgentMemoryKey'
          readOnly: true
        wakeUpConfigs:
          type: array
          items:
            $ref: '#/components/schemas/AgentWakeUpConfig'
          readOnly: true
        outboundTriggers:
          type: array
          items:
            $ref: '#/components/schemas/AgentOutboundTrigger'
          readOnly: true
        websiteTools:
          type: array
          items:
            $ref: '#/components/schemas/AgentWebsiteTool'
          readOnly: true
        imageGenerateTools:
          type: array
          items:
            $ref: '#/components/schemas/AgentImageGenerateTool'
          readOnly: true
        handoffTools:
          type: array
          items:
            $ref: '#/components/schemas/AgentHandoffTool'
          readOnly: true
        mcpConfigs:
          type: array
          items:
            $ref: '#/components/schemas/AgentMcpConfig'
          readOnly: true
        paywallConfig:
          type: string
          readOnly: true
        adConfig:
          type: string
          readOnly: true
        creditSettings:
          type: string
          readOnly: true
        voiceCallConfig:
          type: string
          readOnly: true
        owner:
          type: string
          readOnly: true
        sharings:
          type: string
          readOnly: true
        phoneNumbers:
          type: array
          items:
            $ref: '#/components/schemas/AgentWhatsAppPhoneNumber'
          readOnly: true
        totalMessages:
          type: string
          readOnly: true
        totalSessions:
          type: string
          readOnly: true
        connectUrl:
          type: string
          readOnly: true
        ownerActive:
          type: string
          readOnly: true
        createdAt:
          type: string
          format: date-time
          readOnly: true
      required:
        - adConfig
        - connectUrl
        - createdAt
        - creditSettings
        - documents
        - firstMessage
        - handoffTools
        - id
        - imageGenerateTools
        - mcpConfigs
        - memoryKeys
        - name
        - outboundTriggers
        - owner
        - ownerActive
        - paywallConfig
        - phoneNumbers
        - profilePicture
        - sharings
        - systemPrompt
        - tools
        - totalMessages
        - totalSessions
        - voiceCallConfig
        - wakeUpConfigs
        - websiteTools
    AgentTool:
      type: object
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
        name:
          type: string
          maxLength: 255
        description:
          type: string
        apiSchema: {}
        active:
          type: boolean
        creditCost:
          type: integer
      required:
        - apiSchema
        - creditCost
        - description
        - id
        - name
    AgentDocument:
      type: object
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
        name:
          type: string
          maxLength: 255
        file:
          type: string
          readOnly: true
        status:
          type: string
          readOnly: true
      required:
        - file
        - id
        - name
        - status
    AgentMemoryKey:
      type: object
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
        key:
          type: string
          maxLength: 255
        type:
          type: string
          maxLength: 255
        initialValue:
          type: string
        whenToUpdate:
          type: string
      required:
        - id
        - initialValue
        - key
        - type
        - whenToUpdate
    AgentWakeUpConfig:
      type: object
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
        description:
          type: string
        enabled:
          type: boolean
        forceMessage:
          type: boolean
      required:
        - description
        - forceMessage
        - id
    AgentOutboundTrigger:
      type: object
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
        url:
          type: string
          readOnly: true
        secret:
          type: string
          maxLength: 255
        enabled:
          type: boolean
        templateId:
          type: string
        templateName:
          type: string
      required:
        - id
        - templateId
        - templateName
        - url
    AgentWebsiteTool:
      type: object
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
        url:
          type: string
          format: uri
          maxLength: 200
        prompt:
          type: string
        active:
          type: boolean
      required:
        - id
        - prompt
        - url
    AgentImageGenerateTool:
      type: object
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
        name:
          type: string
          maxLength: 255
        description:
          type: string
        prompt:
          type: string
        active:
          type: boolean
        creditCost:
          type: integer
      required:
        - creditCost
        - id
        - prompt
    AgentHandoffTool:
      type: object
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
        parentAgentId:
          type: string
          format: uuid
        childAgentId:
          type: string
          format: uuid
        childAgentName:
          type: string
          readOnly: true
        description:
          type: string
        active:
          type: boolean
      required:
        - childAgentId
        - childAgentName
        - description
        - id
        - parentAgentId
    AgentMcpConfig:
      type: object
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
        connectorId:
          type: string
          format: uuid
        connectorName:
          type: string
          readOnly: true
        toolWhitelist: {}
      required:
        - connectorId
        - connectorName
        - id
        - toolWhitelist
    AgentWhatsAppPhoneNumber:
      type: object
      properties:
        whatsappPhoneNumberId:
          type: string
        whatsappBusinessAccountId:
          type: string
          readOnly: true
        wabaId:
          type: string
          readOnly: true
        phoneNumber:
          type: string
          readOnly: true
      required:
        - phoneNumber
        - wabaId
        - whatsappBusinessAccountId
        - whatsappPhoneNumberId
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: API key authentication. Pass your API key in the X-API-Key header.

````