Chat Testing

How It Works

The HTTP webhook integration allows you to simulate conversations with your text-based agent. Bluejay sends messages to your agent via HTTP, and your agent responds through a configured webhook endpoint.

Simple
Technical

Tutorial

Create an Agent

Website
API

Go to the “Agents & Simulations” section in the sidebar. Click the ”+” button to create a new agent. Choose “Text/Chat” as the agent type and select “HTTP Webhook” as the integration. Make sure to enter your webhook URL in the designated field.

Use the Add Agent endpoint to create an agent programmatically and save the agent_id.

curl -X POST https://api.getbluejay.ai/v1/add-agent \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Customer Support Bot",
    "type": "INBOUND",
    "mode": "TEXT",
    "connection_type": "HTTP_WEBHOOK",
    "http_webhook": "https://your-server.com/webhook"
  }'

Create a Simulation

Website
API

Click the “Create new simulation” button.

Use the Create Simulation endpoint to create a simulation programmatically and save the simulation_id.

curl -X POST https://api.getbluejay.ai/v1/create-simulation \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "258",
    "name": "Customer Support Test",
    ...
  }'

Create Digital Humans

Website
API

After selecting the number of agents in the “Goal Adherence” section, click “Next”.

Use the Create Digital Human endpoint to create Digital Humans programmatically:

curl -X POST https://api.getbluejay.ai/v1/create-digital-human \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "simulation_id": "2154",
    "name": "Frustrated Customer",
    "scenario": "Customer waiting for refund for 2 weeks",
    "success_criteria": "Agent provides clear timeline and reference number",
    ...
  }'

You can create multiple Digital Humans with different scenarios.

Queue a Simulation Run

Website
API

Click “Create and start X chats” to queue a new simulation run. The “#ID” shown is the simulation_result_id that you’ll need for sending messages.

Use the Queue HTTP Text Simulation Run endpoint to start a simulation run. This initializes the simulation and returns the simulation_result_ids that you’ll need for sending messages.

curl -X POST https://api.getbluejay.ai/v1/queue-http-text-simulation-run \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "simulation_id": "2154"
  }'

Response:

{
    "simulation_run_id": "4434",
    "simulation_result_ids": [
        "13062"
    ],
    "agent_id": "258",
    "status": "success"
}

The response includes:

simulation_run_id: Unique identifier for this simulation run
simulation_result_ids: Array of result IDs, one per Digital Human in the simulation
agent_id: The agent being tested

Send Messages

Use the Send HTTP Text Message endpoint to send messages during the simulation. Each message should include the simulation_result_id from the previous step.

curl -X POST https://api.getbluejay.ai/v1/send-http-text-message \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "simulation_result_id": "13062",
    "message": "What operating system do you have?",
    "end_conversation": false,
    "end_turn":false,
    "message_id": "682098ae-2ec1-4d4f-8223-0cdd9580cff3"
}'

Request Parameters:

Parameter	Type	Required	Description
`message`	string	Yes (when `type="message"`)	The text message to send
`simulation_result_id`	string	Yes	ID of the simulation result
`type`	string	No	`"message"` (default) for conversation turns; `"tool_call"` to log a tool call
`end_conversation`	boolean	No	If `true`, ends and evaluates the conversation
`end_turn`	boolean	No	If `true` (default), processes the message immediately; if `false`, stacks it for later
`message_id`	string	No	Unique ID for deduplication
`name`	string	Yes (when `type="tool_call"`)	Name of the tool that was called
`parameters`	object	No	Input parameters passed to the tool
`output`	any	No	Return value or result from the tool

Logging Tool Calls Live

If your agent invokes tools during the conversation, you can log them in real time by sending a request with type="tool_call". This records the tool call against the simulation result for evaluation — it does not append anything to the conversation transcript or trigger a Digital Human response.

curl -X POST https://api.getbluejay.ai/v1/send-http-text-message \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "simulation_result_id": "13062",
    "type": "tool_call",
    "name": "lookup_order",
    "parameters": {"order_id": "ORD-2024-001"},
    "output": {"status": "shipped", "tracking_number": "1Z999AA1234567890"}
}'

Send one request per tool call, as close to when the tool runs as possible. Bluejay will automatically calculate the start_offset_ms from the conversation start time.

Tool call logs sent via type="tool_call" are available for evaluation immediately. You can mix regular messages and tool call logs freely — send them in whichever order they occur in your agent’s execution.

Receive Webhook Responses

Bluejay sends the Digital Human’s responses to your configured webhook URL. Your server should be ready to receive POST requests with the conversation messages.Webhook Payload:When a Digital Human responds, Bluejay will POST to your webhook URL with the following structure:

{
  "simulation_result_id": "13062",
  "message": "I can help you with that. Can you provide your order number?",
  "message_id": "15a481c1-asd2-s9322-9bac-788d52effdc8",
  "end_conversation": false
}

Webhook Request Headers:

Header	Description
`Content-Type`	`application/json`
`X-Bluejay-Signature`	HMAC-SHA256 signature for verification
`X-Simulation-Result-Id`	The simulation result ID for this conversation

Your webhook endpoint should:

Return a 200 OK status code to acknowledge receipt
Verify the X-Bluejay-Signature header (see Verifying Webhook Signatures section below)
Process the message and send follow-up messages using the Send HTTP Text Message endpoint

Verifying Webhook Signatures

To ensure webhook requests are genuinely from Bluejay, verify the signature included in each request. Bluejay signs the raw request body with HMAC-SHA256 using your signing key (generated in the agent’s Connection settings) and sends the hex digest in the X-Bluejay-Signature header. The signing key is created the first time an HTTP webhook is saved. Later updates, including ones that send http_webhook again, leave that key in place. Generate a new key from the agent’s Connection settings when you want to rotate it.

import hashlib
import hmac

def verify_signature(raw_body: bytes, signature_header: str, signing_key: str) -> bool:
    expected = hmac.new(signing_key.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature_header)

Compute the digest over the raw bytes of the body (before any JSON parsing) and compare it to the header with a constant-time comparison. Reject the request if they don’t match.

Getting Started

Key Concepts

Test

Monitor

Integrations

How It Works

Tutorial

Logging Tool Calls Live

Verifying Webhook Signatures

​How It Works

​Tutorial

​Logging Tool Calls Live

​Verifying Webhook Signatures

How It Works

Tutorial

Logging Tool Calls Live

Verifying Webhook Signatures