While this is in preview, please contact us to enable this feature on your account.

​

Standard interfaces and protocol

The standard integration for chat uses an HTTP, JSON-based API endpoint that you provide. When running a simulation, Coval’s simulator, acting as a user, will connect to the endpoint to get responses from your agent. We support both OpenAI and MCP-style content fields. Query strings are not allowed in URLs.

• Chat Endpoint: A string with the URL to POST chat responses to

​

Initialization

An optional request can be made to an initialization endpoint that you provide with pre-set headers and body for authentication and chat initialization. If you specify an initialization endpoint, the response can optionally include a “sessionId” value, which will be included in all future requests for this chat to the main endpoint.

The Authorization field can be specified alone, without an endpoint, if you just want it to be included in chat messages but not make use of the initialization stage.

To enable this, configure your Simulation with:

• Initialization Endpoint: A string with the URL to POST the message to
• Authorization The value of the “Authorization” header field
• Body: A JSON dict with an authorization or identification keys, which could be configured per-agent.

This will be posted to your endpoint at the beginning of a call. The optional response in JSON should look like:

{
    "sessionId": "XXXX" // String
}

​

Chat messages

Your chat endpoint should be an HTTPS URL that will respond to POST requests with a JSON body. If an Authorization token was provided, it will be included in the headers. The initial request from Coval will look like:

{
    "sessionId": "XXXX" // If one was returned during chat initialization
    "messages": [
        {
            "role": "user",
            "content": "Initial reach out text"
        }
    ]
}

The response should be in json. If toolcalls were used they can be included in the response, either along with the content or in a separate message object with null content:

{
    "messages": [
        {
            "role": "assistant",
            "content": "Response to the initial text",
            "tool_calls": [...]
        }
    ]
}

​

Ending the chat

Either side can end the chat by setting a status field:

{
    "status": "ended",
    "messages": [...] // optional
}