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

# Start a simulation chat with an agent

> Starts a new text conversation with the agent and returns its identifier, the messages so far (the agent's welcome message, if any) and the agent definition. The agent must belong to the same company as the API key. Use `toolMocking` to keep the agent's tools and sub-agents from triggering real actions on your systems during the chat.



## OpenAPI

````yaml POST /SimulationChat/start
openapi: 3.0.1
info:
  title: Starleads public API documentation
  description: >
    Welcome to the Starleads Public API documentation. This API provides public
    access to Starleads services, allowing developers and growth-hackers to
    interact with campaign-related data.

    ***

    ### Base endpoint

    ```https://api.starleads.co```

    ***

    ### Errors

    The API uses standard HTTP status codes to indicate the success or failure
    of the API call. In case of failure, the body of the response will be JSON
    in the following format:

    ```

    {
      "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
      "title": "Bad Request",
      "status": 400,
      "detail": "No campaign exists with campaignId : 11111111"
    }

    ```

    The ```type``` property is a link to a general description of the error
    type.

    ***

    ### Authentification

    Authentication for the API is handled with an API key that must be provided
    as a ```X-Api-Key``` header for every request.<br>

    **API keys are supposed to be a secret that only the client and server know.
    Please remember to not share them with anyone.**<br>

    You can find your API keys when authenticated in your Starleads profile
    :<br> ![Api key menu option](../images/api-menu-option-screenshot.png)
  version: v1
  x-logo:
    url: https://api.starleads.co/images/starleads-logo.png
servers: []
security: []
tags:
  - name: Agent
    description: >-
      Manage your AI agent's prompt. These endpoints allow you to read and
      update the prompt that drives your agent's behavior during calls.
  - name: CampaignField
    description: >-
      CampaignFields enables users to specify customizable fields within their
      campaigns. These fields serve as placeholders (e.g., ```{lastname}```)
      that can be dynamically filled with corresponding data when creating
      prompts, providing flexibility in tailoring campaign content based on
      specific variables.<br>**Those are the keys of the ```databag``` field of
      the request payload to add a new ```CampaignItem``` to a campaign.**
  - name: CampaignItem
    description: Represents prospects entries related to a campaign
  - name: Consumption
    description: >-
      Track your company's credit consumption. These endpoints expose your
      current balance, usage and billing period so you can build budget
      monitoring on top of the API.
  - name: Subscription
    description: >-
      Inspect your subscription contract: the plan you are on, your subscription
      status, the features currently active and your effective limits. No
      pricing information is exposed.
  - name: AgentTest
    description: >-
      Tests of your agents: simulation tests (a simulated user talks to the
      agent and each success criterion is judged) and classification tests (the
      agent must produce the expected tag for a conversation). A test belongs to
      one agent.
  - name: AgentTestExecution
    description: >-
      Executions of agent tests: launching a set of tests, following their
      progress and cancelling them. One execution groups the runs created
      together for a list of tests, each repeated up to 5 times.
  - name: AgentTestFolder
    description: >-
      Folders grouping the tests of an agent (flat, with a name, a color and a
      markdown body).
  - name: AgentTestRun
    description: >-
      Runs of agent tests: one run is one attempt of one test inside an
      execution. Results, history and cancellation.
  - name: SimulationChat
    description: >-
      Test an agent through a text chat, exactly as it would behave in a real
      conversation (prompt, fields and connected tools included). Start a chat,
      then exchange messages with the agent.
paths:
  /SimulationChat/start:
    post:
      tags:
        - SimulationChat
      summary: Start a simulation chat with an agent
      description: >-
        Starts a new text conversation with the agent and returns its
        identifier, the messages so far (the agent's welcome message, if any)
        and the agent definition. The agent must belong to the same company as
        the API key. Use `toolMocking` to keep the agent's tools and sub-agents
        from triggering real actions on your systems during the chat.
      operationId: StartSimulationChat
      parameters:
        - name: X-Api-Key
          in: header
          description: Api key to pass as a ```X-Api-Key``` request header.
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StartSimulationChatRequest'
          text/json:
            schema:
              $ref: '#/components/schemas/StartSimulationChatRequest'
          application/*+json:
            schema:
              $ref: '#/components/schemas/StartSimulationChatRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimulationChatResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '422':
          description: Client Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '502':
          description: Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
components:
  schemas:
    StartSimulationChatRequest:
      required:
        - agentId
      type: object
      properties:
        agentId:
          minLength: 1
          type: string
          description: ID of the agent to test
        dataBag:
          type: object
          additionalProperties:
            type: string
          description: >-
            Optional values for the agent's fields (the variables used in the
            prompt), e.g. { "firstName": "Marie" }
          nullable: true
        toolMocking:
          $ref: '#/components/schemas/PublicToolMocking'
      additionalProperties: false
    SimulationChatResponse:
      type: object
      properties:
        simulationChatId:
          type: string
          description: >-
            Identifier of the simulation chat (the conversation id). Pass it to
            SimulationChat/send-message.
          nullable: true
        messages:
          type: array
          items:
            $ref: '#/components/schemas/SimulationChatMessage'
          description: All the messages of the conversation so far, in chronological order
          nullable: true
        agent:
          $ref: '#/components/schemas/PublicAgent'
      additionalProperties: false
      description: >-
        State of a simulation chat, returned by SimulationChat/start and GET
        SimulationChat/{simulationChatId}
    ProblemDetails:
      type: object
      properties:
        type:
          type: string
          nullable: true
        title:
          type: string
          nullable: true
        status:
          type: integer
          format: int32
          nullable: true
        detail:
          type: string
          nullable: true
        instance:
          type: string
          nullable: true
      additionalProperties: {}
    PublicToolMocking:
      type: object
      properties:
        mockedTools:
          type: array
          items:
            $ref: '#/components/schemas/PublicMockedTool'
          description: >-
            Tools to mock, targeted by their id (see the agent's connected
            tools). Each one returns its `resultTemplate` instead of being
            executed.
          nullable: true
        mockAllTools:
          type: boolean
          description: >-
            Mocks every tool connected to the agent. Tools listed in
            `mockedTools` keep their own template; the others return a default
            response telling the agent the call succeeded. Sub-agents are not
            tools: see `mockAllSubAgents`. Default false.
        mockedSubAgents:
          type: array
          items:
            $ref: '#/components/schemas/PublicMockedSubAgent'
          description: >-
            Sub-agents to mock, targeted by their id. Each one answers with its
            `resultTemplate` and its conversation is never opened. The tools of
            a sub-agent cannot be mocked individually.
          nullable: true
        mockAllSubAgents:
          type: boolean
          description: >-
            Mocks every sub-agent connected to the agent. Sub-agents listed in
            `mockedSubAgents` keep their own template; the others return a
            default response telling the agent the call succeeded. Default
            false.
        mockCallTransfer:
          type: boolean
          description: >-
            Mocks the call transfer, so the simulation never transfers to a
            human. Independent of `mockAllTools`: a phone agent with call
            transfer enabled places a real transfer unless this is true. Default
            false.
      additionalProperties: false
      description: >-
        Which tools and sub-agents of the agent are mocked (not really executed)
        during a simulation. Every mock is opt-in: nothing is mocked unless
        asked for here, and `mockAllTools` implies neither `mockAllSubAgents`
        nor `mockCallTransfer`. The knowledge base retrieval always runs for
        real.
    SimulationChatMessage:
      type: object
      properties:
        role:
          type: string
          description: '"assistant" for the agent, "user" for the simulated contact'
          nullable: true
        text:
          type: string
          description: Message text
          nullable: true
        timestamp:
          type: string
          description: Message timestamp
          format: date-time
          nullable: true
        isConversationEnded:
          type: boolean
          description: True when the agent decided to end the conversation
        endReason:
          type: string
          description: Why the conversation ended, when it did
          nullable: true
      additionalProperties: false
      description: A message exchanged in a simulation chat
    PublicAgent:
      type: object
      properties:
        agentId:
          type: string
          description: Agent identifier
          nullable: true
        agentName:
          type: string
          description: Agent name
          nullable: true
        channel:
          type: string
          description: >-
            Channel the agent talks on: `Phone`, `SMS`, `Web` or `WhatsApp`.
            Phone and WhatsApp campaigns need a phone number; Web agents are
            reached through the web widget.
          nullable: true
        direction:
          type: string
          description: >-
            `Inbound`: the agent answers contacts who reach it. `Outbound`: the
            agent initiates, its campaign items are dialed or messaged.
          nullable: true
        language:
          type: string
          description: Language of the agent, as an ISO code such as `fr` or `en`
          nullable: true
        tags:
          type: array
          items:
            type: string
          description: >-
            Tags set on the agent in the interface, for organisation only. Not
            related to classification tags.
          nullable: true
        createdAt:
          type: string
          description: Creation date (UTC)
          format: date-time
        prompt:
          type: string
          description: Prompt of the agent
          nullable: true
        outboundWelcomeMessage:
          type: string
          description: >-
            First sentence the agent says when it initiates the conversation
            (outbound campaign items, callbacks). Placeholders such as
            `{firstName}` are replaced by the field values.
          nullable: true
        inboundWelcomeMessage:
          type: string
          description: >-
            First sentence the agent says when a contact reaches it (inbound
            call, message or web widget). Placeholders such as `{firstName}` are
            replaced by the field values.
          nullable: true
        fields:
          type: array
          items:
            $ref: '#/components/schemas/PublicAgentField'
          description: >-
            Variables the prompt expects. Pass their values as `dataBag` when
            creating or updating a campaign item or starting a simulation chat,
            and as `variables` of a simulation test. System fields are filled by
            the platform.
          nullable: true
        classificationTags:
          type: array
          items:
            $ref: '#/components/schemas/PublicClassificationTag'
          description: >-
            Tags the agent can assign to a conversation once it ends. A
            classification test expects one of these names in `tagExpected`, and
            campaign item results carry the assigned tag.
          nullable: true
        extractedValues:
          type: array
          items:
            $ref: '#/components/schemas/PublicExtractedValue'
          description: >-
            Values the agent extracts from a conversation once it ends, returned
            with the campaign item results
          nullable: true
        isCallTransferEnabled:
          type: boolean
          description: >-
            Whether the agent may transfer the call to a human. When true,
            `mockCallTransfer` is relevant in simulation tests.
        tools:
          type: array
          items:
            $ref: '#/components/schemas/PublicTool'
          description: Tools connected to the agent
          nullable: true
        subAgents:
          type: array
          items:
            $ref: '#/components/schemas/PublicSubAgent'
          description: >-
            Sub-agents the agent can delegate to. Their ids are the ones
            accepted by `mockedSubAgents` in simulation tests.
          nullable: true
        knowledgeBaseChatId:
          type: string
          description: >-
            Identifier of the knowledge base chat connected to the agent, if any
            (see `GET /Agent/{agentId}/chat`)
          nullable: true
      additionalProperties: false
      description: >-
        An agent: its identity and channel, its prompt, the variables it
        expects, how it classifies conversations, and what is connected to it
        (tools, sub-agents, knowledge base chat)
    PublicMockedTool:
      required:
        - toolId
      type: object
      properties:
        toolId:
          minLength: 1
          type: string
          description: ID of the tool to mock. It must be connected to the agent.
        resultTemplate:
          type: string
          description: >-
            Result handed back to the agent instead of the real one. Supports
            `{name}` placeholders resolved against the call parameters and the
            conversation variables. Empty: a default response telling the agent
            the call succeeded.
          nullable: true
        delaySeconds:
          maximum: 60
          minimum: 0
          type: number
          description: Simulated execution time, in seconds (0 to 60). Default 0.
          format: double
      additionalProperties: false
    PublicMockedSubAgent:
      required:
        - subAgentId
      type: object
      properties:
        subAgentId:
          minLength: 1
          type: string
          description: ID of the sub-agent to mock. It must be connected to the agent.
        resultTemplate:
          type: string
          description: >-
            Answer handed back to the agent instead of the sub-agent's one.
            Supports `{name}` placeholders resolved against the call parameters
            and the conversation variables. Empty: a default response telling
            the agent the call succeeded.
          nullable: true
        delaySeconds:
          maximum: 60
          minimum: 0
          type: number
          description: Simulated execution time, in seconds (0 to 60). Default 0.
          format: double
      additionalProperties: false
    PublicAgentField:
      type: object
      properties:
        name:
          type: string
          description: Name of the variable, the key to use in `dataBag` and `variables`
          nullable: true
        isMandatory:
          type: boolean
          description: Whether a value is required for the agent to run
        isSystem:
          type: boolean
          description: >-
            Filled by the platform (for example the phone number); no value
            needs to be passed
      additionalProperties: false
      description: A variable expected by the agent's prompt
    PublicClassificationTag:
      type: object
      properties:
        name:
          type: string
          description: >-
            Tag name, as found in campaign item results and expected by
            classification tests
          nullable: true
        definition:
          type: string
          description: When the agent assigns this tag
          nullable: true
        isSystem:
          type: boolean
          description: >-
            Provided by the platform (for example voicemail or no answer) rather
            than defined for this agent
      additionalProperties: false
      description: A tag the agent can assign to a conversation once it ends
    PublicExtractedValue:
      type: object
      properties:
        name:
          type: string
          description: Name of the value, as found in campaign item results
          nullable: true
        definition:
          type: string
          description: What the agent extracts
          nullable: true
        type:
          type: string
          description: 'Kind of value: `Text` (free text) or `Nom` (a person name)'
          nullable: true
      additionalProperties: false
      description: A value the agent extracts from a conversation once it ends
    PublicTool:
      type: object
      properties:
        id:
          type: string
          description: Tool identifier
          nullable: true
        name:
          type: string
          description: Human-readable tool name
          nullable: true
        technicalName:
          type: string
          description: Technical name (snake_case) used by the LLM to call the tool
          nullable: true
      additionalProperties: false
      description: A tool connected to an agent
    PublicSubAgent:
      type: object
      properties:
        id:
          type: string
          description: Sub-agent identifier
          nullable: true
        name:
          type: string
          description: Human-readable sub-agent name
          nullable: true
        technicalName:
          type: string
          description: Technical name used by the agent to delegate to it
          nullable: true
        description:
          type: string
          description: What the sub-agent does
          nullable: true
      additionalProperties: false
      description: A sub-agent an agent can delegate to

````