> ## Documentation Index > Fetch the complete documentation index at: https://docs.contactbutton.com/llms.txt > Use this file to discover all available pages before exploring further. # Rate an Agent answer and return the current handoff state ## OpenAPI ````yaml /openapi.yaml post /public/agents/{agent}/conversations/{conversation}/feedback openapi: 3.1.0 info: title: Contact Button API version: 1.0.0-alpha.1 description: > API-first management and public agent actions for Contact Buttons and button.contact pages. API v1 is the first public contract. Existing private legacy API and browser workflows remain supported. contact: name: Contact Button url: https://learn.contactbutton.com servers: - url: https://api.contactbutton.com/v1 description: Production (canonical) - url: https://app.contactbutton.com/v1 description: Backwards-compatible application-domain alias security: - bearerAuth: [] tags: - name: Onboarding description: Human-verified agent onboarding. - name: Workspaces - name: Team - name: Pages - name: Agents description: Workspace Agent profile and behavior configuration. - name: Domains - name: Buttons - name: Forms - name: Surveys - name: Apps - name: Knowledge - name: Booking - name: Telephony description: >- Bring-your-own-Telnyx setup, call flows, phone numbers, and voice interactions. - name: Reviews description: >- Send consented review requests through workspace-owned email, SMS, and WhatsApp channels. - name: Commerce - name: Conversations description: >- Contact-centric threads and messages across chat, email, WhatsApp, and forms. - name: Engagement inbox - name: Public actions description: Public, rate-limited actions that may require human confirmation. paths: /public/agents/{agent}/conversations/{conversation}/feedback: post: tags: - Conversations summary: Rate an Agent answer and return the current handoff state operationId: ratePublicAgentAnswer parameters: - $ref: '#/components/parameters/PublicAgent' - $ref: '#/components/parameters/ConversationId' - $ref: '#/components/parameters/ConversationToken' requestBody: required: true content: application/json: schema: type: object required: - message_id - rating properties: message_id: type: string format: uuid rating: type: string enum: - helpful - not_helpful comment: type: - string - 'null' maxLength: 2000 responses: '200': $ref: '#/components/responses/HandoffData' '201': $ref: '#/components/responses/HandoffData' security: [] components: parameters: PublicAgent: name: agent in: path required: true schema: type: string format: uuid ConversationId: name: conversation in: path required: true schema: type: string format: uuid ConversationToken: name: X-Conversation-Token in: header required: true description: Opaque participant token returned only when the conversation is created. schema: type: string minLength: 32 maxLength: 128 responses: HandoffData: description: >- Successful data envelope containing the common hosted web, REST, MCP, and A2A handoff state. content: application/json: schema: allOf: - $ref: '#/components/schemas/DataResponse' - type: object properties: data: type: object properties: handoff: $ref: '#/components/schemas/AgentHandoffState' lead_capture: $ref: '#/components/schemas/AgentLeadCaptureState' follow_up: $ref: '#/components/schemas/AgentInactivityFollowUpState' analytics_events: type: array items: $ref: '#/components/schemas/AgentLifecycleEvent' protocol_contract: $ref: '#/components/schemas/AgentProtocolContract' schemas: DataResponse: type: object required: - data - meta properties: data: {} meta: type: object properties: request_id: type: string next_cursor: type: - string - 'null' AgentHandoffState: type: object additionalProperties: false required: - status - available - can_request properties: id: type: string format: uuid status: type: string enum: - unavailable - available - offered - waiting_for_human - human_joined available: type: boolean can_request: type: boolean trigger: type: string enum: - explicit_request - unsupported_answer - keywords - negative_feedback - inactivity - custom - agent_request reason: type: string review_url: type: string format: uri description: ContactButton-owned review URL returned to MCP and A2A callers only. offered_at: type: string format: date-time requested_at: type: string format: date-time joined_at: type: string format: date-time AgentLeadCaptureState: type: object required: - version - timing - fields - contact_requirement - state - input_schema properties: version: type: integer enum: - 1 timing: type: string enum: - required_before_chat - optional_before_chat - before_first_answer - after_first_reply fields: type: array items: type: string enum: - name - email - phone - consent contact_requirement: type: string enum: - either - email - phone - both default_phone_country: type: string request_message: type: string maxLength: 500 success_with_name: type: string maxLength: 500 success_without_name: type: string maxLength: 500 requires_consent: type: boolean consent_text: type: string maxLength: 1000 privacy_url: type: - string - 'null' format: uri state: type: string enum: - ready - optional - deferred - input_requested - input_required - complete captured: type: boolean success_message: type: - string - 'null' input_schema: type: object additionalProperties: true AgentInactivityFollowUpState: type: object required: - enabled - opted_out description: >- Safe polling state for the once-per-session hosted web follow-up. External REST, MCP, and A2A protocols never receive an unsolicited push. properties: enabled: type: boolean opted_out: type: boolean status: type: - string - 'null' enum: - scheduled - processing - delivered - cancelled - expired - failed - null AgentLifecycleEvent: type: object required: - id - name - protocol description: >- Privacy-safe lifecycle projection. It never includes prompts, outputs, contact data, OTPs, or internal database IDs. properties: id: type: string format: uuid name: type: string enum: - opened - conversation_started - question_sent - answer_completed - answer_failed - feedback - contact_captured - action_proposed - action_completed - action_failed - handed_off agent_id: type: - string - 'null' format: uuid capability_id: type: - string - 'null' maxLength: 100 protocol: type: string enum: - web - rest - mcp - a2a page_context: type: - string - 'null' maxLength: 80 AgentProtocolContract: type: object required: - version - protocol - states - review properties: version: type: string enum: - '2026-08-05' protocol: type: string enum: - web - rest - mcp - a2a states: type: object additionalProperties: type: array items: type: string review: type: object required: - contactbutton_owned - external_client_can_approve - external_client_receives_otp - material_actions_require_verification properties: contactbutton_owned: type: boolean external_client_can_approve: type: boolean external_client_receives_otp: type: boolean enum: - false material_actions_require_verification: type: boolean securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: Sanctum personal access token or OAuth 2.0 access token description: > A Contact Button scoped bearer key. Send `Authorization: Bearer `. Token abilities are enforced independently of workspace membership; both checks must pass. Interactive MCP clients use registered OAuth applications, Authorization Code + PKCE, audience-bound tokens, and explicit workspace grants. Personal Sanctum tokens remain supported. x-contact-button-token-abilities: workspaces:read: Read workspaces, teams, domains, settings, and connections. workspaces:write: >- Create and manage workspaces, teams, domains, settings, and connections. content:read: Read buttons, forms, lists, pages, booking types, and knowledge. content:write: Create, update, publish, and remove content. engagements:read: >- Read submissions, subscribers, bookings, callbacks, calls, reviews, and conversations. engagements:manage: Reply to and manage engagement records. actions:request: Request protected actions that can still require human confirmation. ````