> ## Documentation Index > Fetch the complete documentation index at: https://docs.revring.ai/llms.txt > Use this file to discover all available pages before exploring further. # Chat With an Agent > Type to the agent and get its reply, without a phone call. Each request returns the agent's next turn. The agent answers exactly as it does in a chat test: its own model tier, prompt, variables, knowledge base, custom tools and MCP tools. Phone actions (ending the call, transfers, keypad tones, handoffs) are simulated and listed in `toolCalls`; custom tools call your webhooks for real. The conversation is kept by you: send the messages so far (send none to get the agent's opening line) and the `state` from the previous reply. When `ended` is true the agent ended the conversation. Up to 60 messages of up to 4,000 characters each per request, and up to 60 requests per minute per organization. Test chats are billed like chat tests: at your listed per-minute rates, based on conversation length. Each test chat is recorded once in your call logs as a test call. Single-prompt agents only; use a voice test for conversation flow agents and agents on a custom model. ## OpenAPI ````yaml POST /agents/{id}/test-chat openapi: 3.1.0 info: title: RevRing Voice AI API description: >- RevRing Voice AI platform API for managing AI voice agents, phone calls, SIP trunks, and analytics. Build intelligent voice applications that can handle inbound and outbound phone calls with AI-powered conversational agents. version: 1.0.0 contact: name: RevRing Support url: https://revring.ai servers: - url: https://api.revring.ai/v1 description: Production API security: - apiKeyAuth: [] tags: - name: Messaging Connections description: Connect messaging providers so agents can send text messages - name: Messages description: Send text messages and read your message log - name: Conversations description: List and clear managed conversation threads - name: SIP Trunks description: Manage SIP trunks for connecting agents to the phone network - name: Agents description: Manage AI voice agents and their configuration - name: Agent Folders description: Organize agents into folders for dashboard navigation - name: Calls description: Manage and query phone calls - name: Analytics description: Get analytics and metrics about your calls - name: Knowledge Bases description: >- Manage knowledge bases and sources for agent retrieval-augmented generation - name: Test Suites description: Manage test suites, test cases, and test runs for agent evaluation - name: Voices description: Browse the voices available to your organization for agent speech - name: Webhooks description: Webhook delivery settings for your organization - name: Alerts description: Alert rules on call metrics, delivered to a webhook or Slack - name: Contacts description: What your agents remember about people - name: Integrations description: Calendars your agents book on paths: /agents/{id}/test-chat: parameters: - name: id in: path required: true description: Agent ID schema: type: string format: uuid post: tags: - Agents summary: Test Agent by Chat description: >- Type to the agent and get its reply, without a phone call. Each request returns the agent's next turn. The agent answers exactly as it does in a chat test: its own model tier, prompt, variables, knowledge base, custom tools and MCP tools. Phone actions (ending the call, transfers, keypad tones, handoffs) are simulated and listed in `toolCalls`; custom tools call your webhooks for real. The conversation is kept by you: send the messages so far (send none to get the agent's opening line) and the `state` from the previous reply. When `ended` is true the agent ended the conversation. Up to 60 messages of up to 4,000 characters each per request, and up to 60 requests per minute per organization. Test chats are billed like chat tests: at your listed per-minute rates, based on conversation length. Each test chat is recorded once in your call logs as a test call. Single-prompt agents only; use a voice test for conversation flow agents and agents on a custom model. operationId: testChatAgent requestBody: required: true content: application/json: schema: type: object required: - messages properties: messages: type: array maxItems: 60 items: type: object required: - role - content properties: role: type: string enum: - user - assistant description: 'Who said it: `user` is you, `assistant` is the agent' content: type: string maxLength: 4000 description: >- The conversation so far, oldest first. Empty for the agent's opening line; otherwise the last message is yours variables: type: object additionalProperties: true description: >- Variables for this test, as on a call (for example `{"first_name": "Sam"}`). Override the agent's default variables environment: type: string description: >- Version to test: `production` (the published version) or the name of one of the agent's environments. Omit to test the saved draft state: type: object description: >- Conversation state from the previous reply. Send it back unchanged with the next message so the conversation continues where it left off (the same test call, any handoff to another agent, and variables set by the pre-call webhook or by tools). Omit it, or send no messages, to start a new conversation. properties: callId: type: string description: >- The test call this conversation is recorded and billed on agentId: type: string description: >- The agent answering now. Differs from the agent in the path after a handoff environment: type: - string - 'null' handoffs: type: integer minimum: 0 variables: type: object additionalProperties: true description: Variables set during the conversation examples: opening: summary: Start a conversation value: messages: [] next: summary: Continue it value: messages: - role: assistant content: Hi, thanks for calling. How can I help? - role: user content: Can I book a table for two tonight? variables: first_name: Sam state: agentId: cm_agent_id environment: null handoffs: 0 variables: {} responses: '200': description: The agent's next turn content: application/json: schema: type: object properties: data: type: object properties: reply: type: string description: >- What the agent said. Empty when the agent waits for you to speak first toolCalls: type: array items: type: object properties: name: type: string description: >- Tool name, for example a custom tool's name, `end_call`, `transfer_to_number`, `play_keypad_touch_tone` or `hand_off_to_agent` arguments: type: object additionalProperties: true result: description: What the tool returned to the agent ok: type: boolean description: false when the tool failed description: Tools the agent used during this turn, in order ended: type: boolean description: true when the agent ended the conversation endReason: type: string enum: - end_call - transfer - voicemail description: How it ended, when `ended` is true state: type: object description: >- Conversation state from the previous reply. Send it back unchanged with the next message so the conversation continues where it left off (the same test call, any handoff to another agent, and variables set by the pre-call webhook or by tools). Omit it, or send no messages, to start a new conversation. properties: callId: type: string description: >- The test call this conversation is recorded and billed on agentId: type: string description: >- The agent answering now. Differs from the agent in the path after a handoff environment: type: - string - 'null' handoffs: type: integer minimum: 0 variables: type: object additionalProperties: true description: Variables set during the conversation '400': description: Invalid request, or the environment does not exist content: application/json: schema: type: object properties: error: type: string enum: - invalid_body - environment_not_found message: type: string '401': $ref: '#/components/responses/UnauthorizedError' '402': $ref: '#/components/responses/BillingInactiveError' '404': $ref: '#/components/responses/NotFoundError' '422': description: This agent can't be tested by chat; use a voice test content: application/json: schema: type: object properties: error: type: string enum: - test_chat_unsupported message: type: string '429': description: Too many test messages; retry after the `Retry-After` seconds content: application/json: schema: type: object properties: error: type: string enum: - rate_limited message: type: string '502': description: The agent could not reply; try again content: application/json: schema: type: object properties: error: type: string enum: - agent_reply_failed message: type: string '503': description: Chat testing is temporarily unavailable content: application/json: schema: type: object properties: error: type: string enum: - test_chat_unavailable message: type: string components: responses: UnauthorizedError: description: Authentication required or API key invalid content: application/json: schema: type: object properties: error: type: string example: unauthorized BillingInactiveError: description: Subscription inactive or billing issue content: application/json: schema: type: object properties: error: type: string example: billing_inactive NotFoundError: description: Resource not found content: application/json: schema: type: object properties: error: type: string example: not_found securitySchemes: apiKeyAuth: type: apiKey in: header name: x-api-key description: >- API key for authentication. Generate API keys from the RevRing dashboard. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.