Test agent (text chat)

Test an agent in text: send the conversation so far and get the agent's next reply, with tool calls simulated so nothing real is booked.

POST https://api.centerfy.ai/webhooks/inbound/agents/:id/test-chat

Headers

Header	Required	Value	Description
`x-api-key`	Yes	your sub-account API key (cfy_…)	Authenticates the request; or use Authorization: Bearer `<key>`.
`Content-Type`	Yes	application/json	The request body is JSON.

Path parameters

Name	Type	Required	Description
`id`	`string (uuid)`	Yes	The agent id. A non-uuid returns 400; an agent that does not exist in this sub-account returns 404.

Body parameters

Name	Type	Required	Default	Description
`messages`	`array of { role, content }`	Yes	—	The conversation so far, oldest first; 1–100 items. role is “user” (the customer) or “assistant” (the agent); content is a non-empty string (max 20,000 characters, 120,000 in total). The last message must be from the user — the agent replies to it.
`mock_tools`	`boolean`	No	—	Default true: every tool the agent decides to call is simulated — the model receives a canned success result (or your tool_results) and nothing is booked, sent or tagged. Set false to run the agent’s tools for real (then pass contact_id so tools that need a contact have one).
`tool_results`	`object`	No	—	With mock_tools on: the result to hand the model for a given tool name, as any JSON (e.g. { “book_appointment”: { “success”: false, “error”: “slot taken” } }). The key ”*” applies to every tool without its own entry. Up to 50 tools.
`contact_id`	`string (uuid)`	No	—	A contact in this sub-account to run the conversation as. Tools then see that contact’s details; the contact is never modified in mock mode.

Request body

{
  "messages": [
    {
      "role": "assistant",
      "content": "Hi, thanks for reaching out to Acme Clinic! How can I help?"
    },
    {
      "role": "user",
      "content": "I'd like to book a cleaning next Tuesday morning."
    }
  ],
  "mock_tools": true,
  "tool_results": {
    "book_appointment": {
      "success": true,
      "appointment_id": "appt_test_1",
      "start_time": "2026-10-20T09:30:00-04:00"
    }
  }
}

Example

curl -X POST "https://api.centerfy.ai/webhooks/inbound/agents/{id}/test-chat" \
  -H "x-api-key: $CENTERFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "messages": [
    {
      "role": "assistant",
      "content": "Hi, thanks for reaching out to Acme Clinic! How can I help?"
    },
    {
      "role": "user",
      "content": "I'\''d like to book a cleaning next Tuesday morning."
    }
  ],
  "mock_tools": true,
  "tool_results": {
    "book_appointment": {
      "success": true,
      "appointment_id": "appt_test_1",
      "start_time": "2026-10-20T09:30:00-04:00"
    }
  }
}'

import { CenterfyClient } from "@centerfy/sdk";

const centerfy = new CenterfyClient({ apiKey: process.env.CENTERFY_API_KEY! });

const result = await centerfy.agents.testChat("<agentId>", {
  "messages": [
    {
      "role": "assistant",
      "content": "Hi, thanks for reaching out to Acme Clinic! How can I help?"
    },
    {
      "role": "user",
      "content": "I'd like to book a cleaning next Tuesday morning."
    }
  ],
  "mock_tools": true,
  "tool_results": {
    "book_appointment": {
      "success": true,
      "appointment_id": "appt_test_1",
      "start_time": "2026-10-20T09:30:00-04:00"
    }
  }
});
console.log(result);

centerfy agents test-chat <agentId> '{"messages":[{"role":"assistant","content":"Hi, thanks for reaching out to Acme Clinic! How can I help?"},{"role":"user","content":"I'\''d like to book a cleaning next Tuesday morning."}],"mock_tools":true,"tool_results":{"book_appointment":{"success":true,"appointment_id":"appt_test_1","start_time":"2026-10-20T09:30:00-04:00"}}}'

MCP tool: centerfy_agents_test_chat (see MCP server)

Response

{
  "status": "success",
  "agent_id": "b2c3d4e5-3333-4abc-9def-000000000030",
  "agent_name": "Front Desk AI",
  "reply": "You're booked for a cleaning on Tuesday, October 20th at 9:30 AM. Is there anything else I can help you with?",
  "tool_calls": [
    {
      "name": "book_appointment",
      "arguments": {
        "date": "2026-10-20",
        "time": "09:30",
        "service": "cleaning"
      },
      "result": {
        "success": true,
        "appointment_id": "appt_test_1",
        "start_time": "2026-10-20T09:30:00-04:00"
      },
      "simulated": true
    }
  ],
  "tools_simulated": true,
  "contact_id": null,
  "llm": {
    "model": "gpt-4o",
    "key_source": "platform"
  },
  "usage": {
    "messages_received": 2,
    "tool_call_count": 1,
    "duration_ms": 2140
  }
}

Errors

200 — on success with the agent’s reply and every tool call it made (name, arguments, the result the model received, and whether it was simulated).
400 — if messages is missing, malformed, over the limits, or does not end with a user message, or if tool_results is sent with mock_tools=false.
404 — if the agent or contact_id is not in this sub-account.
502 — if the agent could not produce a reply (for example no LLM key is configured).

Notes

The reply is produced exactly like the live chat channels (web widget, SMS, email, social): same system prompt, knowledge bases, enabled tools and LLM. Nothing is persisted — no contact, conversation or message rows are written and no session survives the request, so you can replay or branch a transcript freely. Inactive agents can be tested. Billing: a reply that ran on the platform LLM key is billed like any other chatbot reply; replies on your own LLM key are not charged. Rate limits apply as usual and each call can take several seconds.