Chat Testing

Test text-based chat agents using HTTP webhooks for bidirectional messaging

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

1. Create an Agent

   Website

   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.

   

   API

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

   curl -X POST https://api.getbluejay.ai/v1/agents \
     -H "X-API-Key: your-api-key" \
     -H "Content-Type: application/json" \
     -d '{
       "name": "Customer Support Bot",
       "webhook_url": "https://your-server.com/webhook",
       ...
     }'
   
2. Create a Simulation

   Website

   Click the “Create new simulation” button.

   

   API

   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",
       ...
     }'
   
3. Create Digital Humans

   Website

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

   

   API

   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.

4. Queue a Simulation Run

   Website

   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.

   

   API

   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
5. 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.

6. 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:

   1. Return a 200 OK status code to acknowledge receipt
   2. Verify the X-Bluejay-Signature header (see Verifying Webhook Signatures section below)
   3. 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, you should verify the signature included in each request. Bluejay signs the request body using HMAC-SHA256 and includes the signature in the X-Bluejay-Signature header.