> ## 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. # Get a simulation chat > Returns the messages exchanged so far. The agent is only returned by SimulationChat/start (`agent` is null here). A chat is forgotten after 30 minutes of inactivity. ## OpenAPI ````yaml GET /SimulationChat/{simulationChatId} 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.
**API keys are supposed to be a secret that only the client and server know. Please remember to not share them with anyone.**
You can find your API keys when authenticated in your Starleads profile :
![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.
**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/{simulationChatId}: get: tags: - SimulationChat summary: Get a simulation chat description: >- Returns the messages exchanged so far. The agent is only returned by SimulationChat/start (`agent` is null here). A chat is forgotten after 30 minutes of inactivity. operationId: GetSimulationChat parameters: - name: X-Api-Key in: header description: Api key to pass as a ```X-Api-Key``` request header. required: true schema: type: string - name: simulationChatId in: path description: ID of the simulation chat. required: true schema: type: string 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' '502': description: Server Error content: application/json: schema: $ref: '#/components/schemas/ProblemDetails' components: schemas: 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: {} 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) 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 ````