openapi: 3.1.0
info:
  title: Chatbyte API
  version: 1.0.0
  description: >-
    Public API for Chatbyte.


    The current reference documents voice endpoints and webhooks.


    ## Authentication

    All API endpoints require a Bearer token. Include your API token in the
    Authorization header:

    ```

    Authorization: Bearer your_api_token

    ```


    ## Webhooks

    Configure webhook endpoints in your organization settings to receive
    real-time notifications about call events.

    Webhooks are signed with HMAC-SHA256 for verification.
tags:
  - name: Voice Outbound Calls
    description: Initiate outbound calls using your configured voice agents.
  - name: Voice Agents
    description: List and inspect voice agents in the authenticated organization.
  - name: Voice Phone Numbers
    description: List provisioned phone numbers and see which agent each number is
      assigned to.
  - name: Voice Webhooks
    description: Receive signed event payloads for call lifecycle and tool activity.
servers:
  - url: https://api.chatbyte.ai
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: Public API Token
  schemas:
    CallInitWebhookPayload:
      type: object
      properties:
        event:
          type: string
          enum:
            - voice.callInit
          description: Webhook event name.
        data:
          type: object
          properties:
            conversationId:
              type: string
              description: Chatbyte call ID for this call-init event.
            agentId:
              type: string
              description: ID of the voice agent handling the call
            callerNumber:
              type: string
              description: Phone number of the caller (E.164 format)
            calledNumber:
              type: string
              description: Phone number that was called (E.164 format)
            direction:
              type: string
              enum:
                - inbound
                - outbound
              description: Call direction
          required:
            - conversationId
            - agentId
            - callerNumber
            - calledNumber
            - direction
          description: Call initialization payload details.
      required:
        - event
        - data
    CallInitWebhookResponse:
      type: object
      properties:
        dynamicValues:
          type: object
          additionalProperties: {}
          description: Key-value pairs to inject into agent prompt variables
        additionalSystemPrompt:
          type: string
          description: Additional instructions to append to the agent system prompt
    CallCompletedWebhookPayload:
      type: object
      properties:
        event:
          type: string
          enum:
            - voice.postCall
          description: Webhook event name.
        data:
          type: object
          properties:
            conversationId:
              type: string
              description: Chatbyte call ID for this post-call event.
            agentId:
              type: string
              description: ID of the voice agent that handled the call
            callerNumber:
              type: string
              description: Phone number of the caller (E.164 format)
            calledNumber:
              type: string
              description: Phone number that was called (E.164 format)
            direction:
              type: string
              enum:
                - inbound
                - outbound
              description: Call direction
            durationSeconds:
              type: number
              description: Total call duration in seconds
            status:
              type: string
              enum:
                - completed
                - failed
              description: Normalized call outcome status.
            reason:
              type: string
              description: Normalized failure reason when status is `failed`, for example
                `not_picked_up`.
            providerReason:
              type: string
              description: Additional failure detail when available, for example `busy`.
          required:
            - conversationId
            - agentId
            - callerNumber
            - calledNumber
            - direction
            - durationSeconds
            - status
          description: Post-call payload details.
      required:
        - event
        - data
    ToolInvocationWebhookPayload:
      type: object
      properties:
        event:
          type: string
          enum:
            - voice.toolInvocation
          description: Webhook event name.
        data:
          type: object
          properties:
            timestamp:
              type: string
              format: date-time
              description: ISO-8601 timestamp when Chatbyte sent the webhook.
            toolInstanceId:
              type: string
              description: Chatbyte webhook tool instance ID.
            toolName:
              type: string
              description: Display name of the webhook tool instance.
            agentId:
              type: string
              description: Chatbyte voice agent ID that owned the invocation.
            callerNumber:
              type: string
              description: Caller phone number in E.164 format.
            calledNumber:
              type: string
              description: Called phone number in E.164 format.
            direction:
              type: string
              enum:
                - inbound
                - outbound
              description: Resolved call direction.
            agentNumber:
              type: string
              description: Platform phone number participating in the call in E.164 format.
            phoneNumberId:
              type: string
              description: Chatbyte phone number ID for the resolved platform number.
            parameters:
              type: object
              additionalProperties: {}
              description: Custom tool parameters collected by the agent plus configured
                constant values. Reserved system fields are excluded.
            dynamicValues:
              type: object
              additionalProperties:
                anyOf:
                  - type: string
                  - type: number
                  - type: boolean
              description: When enabled for the webhook tool, mirrored call-scoped dynamic
                values already associated with this conversation, for example
                via outbound initiation or the call-init webhook.
          required:
            - timestamp
            - toolInstanceId
            - toolName
            - agentId
            - callerNumber
            - calledNumber
            - direction
            - agentNumber
            - phoneNumberId
            - parameters
          description: Normalized tool invocation payload details.
      required:
        - event
        - data
    PaginationMeta:
      type: object
      properties:
        limit:
          type: integer
          description: Number of items requested per page.
        offset:
          type: integer
          description: Zero-based index of first returned item.
        total:
          type: integer
          description: Total number of items available.
        hasMore:
          type: boolean
          description: Whether additional pages are available.
      required:
        - limit
        - offset
        - total
        - hasMore
    AgentListItem:
      type: object
      properties:
        agentId:
          type: string
          description: Chatbyte voice agent ID
        label:
          type: string
          description: Display name for the agent
        language:
          type:
            - string
            - "null"
          description: Agent language (BCP-47)
        voiceId:
          type:
            - string
            - "null"
          description: Configured voice ID
        createdAt:
          type:
            - string
            - "null"
          format: date-time
          description: ISO-8601 timestamp when the agent was created.
      required:
        - agentId
        - label
        - language
        - voiceId
        - createdAt
    AgentDetail:
      allOf:
        - $ref: "#/components/schemas/AgentListItem"
        - type: object
          properties:
            maxCallDurationSecs:
              type:
                - integer
                - "null"
              description: Maximum call duration override (seconds)
            updatedAt:
              type:
                - string
                - "null"
              format: date-time
              description: ISO-8601 timestamp when the agent was last updated.
          required:
            - maxCallDurationSecs
            - updatedAt
    AgentListResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/AgentListItem"
          description: List of voice agents.
        pagination:
          allOf:
            - $ref: "#/components/schemas/PaginationMeta"
            - description: Pagination metadata for the list.
      required:
        - data
        - pagination
    AgentDetailResponse:
      type: object
      properties:
        data:
          allOf:
            - $ref: "#/components/schemas/AgentDetail"
            - description: Voice agent details.
      required:
        - data
    PhoneNumberListItem:
      type: object
      properties:
        phoneNumberId:
          type: string
          description: Chatbyte phone number ID
        phoneNumber:
          type: string
          description: Phone number in E.164 format (e.g., +14155550100)
        label:
          type:
            - string
            - "null"
          description: Optional label for the phone number
        provider:
          type: string
          enum:
            - SIP_TRUNK
            - TWILIO_EXTERN
            - TWILIO_INTERN
          description: Number source classification for this number.
        status:
          type: string
          enum:
            - ACTIVE
            - PENDING
            - ERROR
            - SUSPENDED
          description: Provisioning/status state for this number.
        countryCode:
          type:
            - string
            - "null"
          description: ISO-3166-1 alpha-2
        assignedAgent:
          type:
            - object
            - "null"
          properties:
            agentId:
              type: string
              description: Assigned agent ID.
            label:
              type: string
              description: Assigned agent display label.
          required:
            - agentId
            - label
          description: Agent currently assigned to this phone number, if any.
        outboundEnabled:
          type: boolean
          description: Whether outbound calls are supported
        createdAt:
          type:
            - string
            - "null"
          format: date-time
          description: ISO-8601 timestamp when the phone number was created.
      required:
        - phoneNumberId
        - phoneNumber
        - label
        - provider
        - status
        - countryCode
        - assignedAgent
        - outboundEnabled
        - createdAt
    PhoneNumberDetail:
      allOf:
        - $ref: "#/components/schemas/PhoneNumberListItem"
        - type: object
          properties:
            updatedAt:
              type:
                - string
                - "null"
              format: date-time
              description: ISO-8601 timestamp when the phone number was last updated.
          required:
            - updatedAt
    PhoneNumberListResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/PhoneNumberListItem"
          description: List of phone numbers.
        pagination:
          allOf:
            - $ref: "#/components/schemas/PaginationMeta"
            - description: Pagination metadata for the list.
      required:
        - data
        - pagination
    PhoneNumberDetailResponse:
      type: object
      properties:
        data:
          allOf:
            - $ref: "#/components/schemas/PhoneNumberDetail"
            - description: Phone number details.
      required:
        - data
  parameters: {}
paths:
  /v1/voice/outbound-calls/initiate:
    post:
      tags:
        - Voice Outbound Calls
      summary: Initiate outbound call
      operationId: initiateOutboundCall
      description: Initiate an outbound call using a voice agent. Use `mode=inline` to
        send call setup data in the API request, or `mode=deferred` to let
        Chatbyte resolve call setup during call initialization.
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                agentId:
                  type: string
                  minLength: 1
                  description: Chatbyte voice agent ID used for the outbound call.
                phoneNumberId:
                  type: string
                  minLength: 1
                  description: Chatbyte phone number ID used as the outbound caller ID.
                toNumber:
                  type: string
                  pattern: ^[+][1-9]\d{1,14}$
                  description: Destination phone number in E.164 format.
                mode:
                  type: string
                  enum:
                    - inline
                    - deferred
                  description: Outbound initiation mode. Use `inline` to send call setup data in
                    the API request. Use `deferred` to let Chatbyte resolve call
                    setup during call initialization.
                dynamicValues:
                  type: object
                  additionalProperties:
                    anyOf:
                      - type: string
                      - type: number
                      - type: boolean
                  description: Optional dynamic values for this outbound call. Only valid in
                    `inline` mode, where Chatbyte composes the final call setup
                    payload before starting the call. Reserved transport keys
                    such as caller/called numbers and the internal session id
                    cannot be overridden.
              required:
                - agentId
                - phoneNumberId
                - toNumber
              additionalProperties: false
      responses:
        "200":
          description: Call initiated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                    description: Indicates the call initiation was accepted.
                  conversationId:
                    type: string
                    description: Chatbyte conversation ID, when available.
                  callSid:
                    type: string
                    description: Legacy call reference, when available.
                required:
                  - success
        "400":
          description: Validation failed
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Machine-readable error code.
                  reason:
                    type: string
                    description: Human-readable explanation of the error.
                  hint:
                    type: string
                    description: Actionable hint to fix the request, when available.
                  issues:
                    type: array
                    items:
                      type: object
                      properties:
                        path:
                          type: string
                          description: Field path that failed validation.
                        message:
                          type: string
                          description: Validation failure message for this field.
                      required:
                        - path
                        - message
                    description: Field-level validation issues when request validation fails.
                required:
                  - error
        "401":
          description: Invalid or expired API token
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Machine-readable error code.
                  reason:
                    type: string
                    description: Human-readable explanation of the error.
                  hint:
                    type: string
                    description: Actionable hint to fix the request, when available.
                  issues:
                    type: array
                    items:
                      type: object
                      properties:
                        path:
                          type: string
                          description: Field path that failed validation.
                        message:
                          type: string
                          description: Validation failure message for this field.
                      required:
                        - path
                        - message
                    description: Field-level validation issues when request validation fails.
                required:
                  - error
        "402":
          description: Payment required
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Machine-readable error code.
                  reason:
                    type: string
                    description: Human-readable explanation of the error.
                  hint:
                    type: string
                    description: Actionable hint to fix the request, when available.
                  issues:
                    type: array
                    items:
                      type: object
                      properties:
                        path:
                          type: string
                          description: Field path that failed validation.
                        message:
                          type: string
                          description: Validation failure message for this field.
                      required:
                        - path
                        - message
                    description: Field-level validation issues when request validation fails.
                required:
                  - error
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Machine-readable error code.
                  reason:
                    type: string
                    description: Human-readable explanation of the error.
                  hint:
                    type: string
                    description: Actionable hint to fix the request, when available.
                  issues:
                    type: array
                    items:
                      type: object
                      properties:
                        path:
                          type: string
                          description: Field path that failed validation.
                        message:
                          type: string
                          description: Validation failure message for this field.
                      required:
                        - path
                        - message
                    description: Field-level validation issues when request validation fails.
                required:
                  - error
        "404":
          description: Agent or phone number not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Machine-readable error code.
                  reason:
                    type: string
                    description: Human-readable explanation of the error.
                  hint:
                    type: string
                    description: Actionable hint to fix the request, when available.
                  issues:
                    type: array
                    items:
                      type: object
                      properties:
                        path:
                          type: string
                          description: Field path that failed validation.
                        message:
                          type: string
                          description: Validation failure message for this field.
                      required:
                        - path
                        - message
                    description: Field-level validation issues when request validation fails.
                required:
                  - error
        "500":
          description: Server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Machine-readable error code.
                  reason:
                    type: string
                    description: Human-readable explanation of the error.
                  hint:
                    type: string
                    description: Actionable hint to fix the request, when available.
                  issues:
                    type: array
                    items:
                      type: object
                      properties:
                        path:
                          type: string
                          description: Field path that failed validation.
                        message:
                          type: string
                          description: Validation failure message for this field.
                      required:
                        - path
                        - message
                    description: Field-level validation issues when request validation fails.
                required:
                  - error
  /v1/voice/agents:
    get:
      tags:
        - Voice Agents
      summary: List voice agents
      description: List voice agents for the authenticated organization.
      security:
        - bearerAuth: []
      parameters: &a1
        - name: limit
          in: query
          required: false
          description: "Number of items to return (default: 25, max: 100)."
          schema:
            type: integer
            minimum: 1
            maximum: 100
          example: 25
        - name: offset
          in: query
          required: false
          description: Number of items to skip before returning results.
          schema:
            type: integer
            minimum: 0
          example: 0
      responses:
        "200":
          description: Voice agents retrieved successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AgentListResponse"
        "400":
          description: Invalid pagination parameters
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Machine-readable error code.
                  reason:
                    type: string
                    description: Human-readable explanation of the error.
                  hint:
                    type: string
                    description: Actionable hint to fix the request, when available.
                  issues:
                    type: array
                    items:
                      type: object
                      properties:
                        path:
                          type: string
                          description: Field path that failed validation.
                        message:
                          type: string
                          description: Validation failure message for this field.
                      required:
                        - path
                        - message
                    description: Field-level validation issues when request validation fails.
                required:
                  - error
        "401":
          description: Invalid or expired API token
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Machine-readable error code.
                  reason:
                    type: string
                    description: Human-readable explanation of the error.
                  hint:
                    type: string
                    description: Actionable hint to fix the request, when available.
                  issues:
                    type: array
                    items:
                      type: object
                      properties:
                        path:
                          type: string
                          description: Field path that failed validation.
                        message:
                          type: string
                          description: Validation failure message for this field.
                      required:
                        - path
                        - message
                    description: Field-level validation issues when request validation fails.
                required:
                  - error
        "500":
          description: Server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Machine-readable error code.
                  reason:
                    type: string
                    description: Human-readable explanation of the error.
                  hint:
                    type: string
                    description: Actionable hint to fix the request, when available.
                  issues:
                    type: array
                    items:
                      type: object
                      properties:
                        path:
                          type: string
                          description: Field path that failed validation.
                        message:
                          type: string
                          description: Validation failure message for this field.
                      required:
                        - path
                        - message
                    description: Field-level validation issues when request validation fails.
                required:
                  - error
  /v1/voice/agents/{agentId}:
    get:
      tags:
        - Voice Agents
      summary: Get voice agent
      description: Retrieve a single voice agent by ID.
      security:
        - bearerAuth: []
      parameters:
        - name: agentId
          in: path
          required: true
          description: Chatbyte voice agent ID
          schema:
            type: string
      responses:
        "200":
          description: Voice agent retrieved successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AgentDetailResponse"
        "401":
          description: Invalid or expired API token
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Machine-readable error code.
                  reason:
                    type: string
                    description: Human-readable explanation of the error.
                  hint:
                    type: string
                    description: Actionable hint to fix the request, when available.
                  issues:
                    type: array
                    items:
                      type: object
                      properties:
                        path:
                          type: string
                          description: Field path that failed validation.
                        message:
                          type: string
                          description: Validation failure message for this field.
                      required:
                        - path
                        - message
                    description: Field-level validation issues when request validation fails.
                required:
                  - error
        "403":
          description: Voice agent does not belong to this organization
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Machine-readable error code.
                  reason:
                    type: string
                    description: Human-readable explanation of the error.
                  hint:
                    type: string
                    description: Actionable hint to fix the request, when available.
                  issues:
                    type: array
                    items:
                      type: object
                      properties:
                        path:
                          type: string
                          description: Field path that failed validation.
                        message:
                          type: string
                          description: Validation failure message for this field.
                      required:
                        - path
                        - message
                    description: Field-level validation issues when request validation fails.
                required:
                  - error
        "404":
          description: Voice agent not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Machine-readable error code.
                  reason:
                    type: string
                    description: Human-readable explanation of the error.
                  hint:
                    type: string
                    description: Actionable hint to fix the request, when available.
                  issues:
                    type: array
                    items:
                      type: object
                      properties:
                        path:
                          type: string
                          description: Field path that failed validation.
                        message:
                          type: string
                          description: Validation failure message for this field.
                      required:
                        - path
                        - message
                    description: Field-level validation issues when request validation fails.
                required:
                  - error
        "500":
          description: Server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Machine-readable error code.
                  reason:
                    type: string
                    description: Human-readable explanation of the error.
                  hint:
                    type: string
                    description: Actionable hint to fix the request, when available.
                  issues:
                    type: array
                    items:
                      type: object
                      properties:
                        path:
                          type: string
                          description: Field path that failed validation.
                        message:
                          type: string
                          description: Validation failure message for this field.
                      required:
                        - path
                        - message
                    description: Field-level validation issues when request validation fails.
                required:
                  - error
  /v1/voice/phone-numbers:
    get:
      tags:
        - Voice Phone Numbers
      summary: List phone numbers
      description: List voice phone numbers for the authenticated organization.
      security:
        - bearerAuth: []
      parameters: *a1
      responses:
        "200":
          description: Phone numbers retrieved successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PhoneNumberListResponse"
        "400":
          description: Invalid pagination parameters
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Machine-readable error code.
                  reason:
                    type: string
                    description: Human-readable explanation of the error.
                  hint:
                    type: string
                    description: Actionable hint to fix the request, when available.
                  issues:
                    type: array
                    items:
                      type: object
                      properties:
                        path:
                          type: string
                          description: Field path that failed validation.
                        message:
                          type: string
                          description: Validation failure message for this field.
                      required:
                        - path
                        - message
                    description: Field-level validation issues when request validation fails.
                required:
                  - error
        "401":
          description: Invalid or expired API token
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Machine-readable error code.
                  reason:
                    type: string
                    description: Human-readable explanation of the error.
                  hint:
                    type: string
                    description: Actionable hint to fix the request, when available.
                  issues:
                    type: array
                    items:
                      type: object
                      properties:
                        path:
                          type: string
                          description: Field path that failed validation.
                        message:
                          type: string
                          description: Validation failure message for this field.
                      required:
                        - path
                        - message
                    description: Field-level validation issues when request validation fails.
                required:
                  - error
        "500":
          description: Server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Machine-readable error code.
                  reason:
                    type: string
                    description: Human-readable explanation of the error.
                  hint:
                    type: string
                    description: Actionable hint to fix the request, when available.
                  issues:
                    type: array
                    items:
                      type: object
                      properties:
                        path:
                          type: string
                          description: Field path that failed validation.
                        message:
                          type: string
                          description: Validation failure message for this field.
                      required:
                        - path
                        - message
                    description: Field-level validation issues when request validation fails.
                required:
                  - error
  /v1/voice/phone-numbers/{phoneNumberId}:
    get:
      tags:
        - Voice Phone Numbers
      summary: Get phone number
      description: Retrieve a single phone number by ID.
      security:
        - bearerAuth: []
      parameters:
        - name: phoneNumberId
          in: path
          required: true
          description: Chatbyte phone number ID
          schema:
            type: string
      responses:
        "200":
          description: Phone number retrieved successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PhoneNumberDetailResponse"
        "401":
          description: Invalid or expired API token
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Machine-readable error code.
                  reason:
                    type: string
                    description: Human-readable explanation of the error.
                  hint:
                    type: string
                    description: Actionable hint to fix the request, when available.
                  issues:
                    type: array
                    items:
                      type: object
                      properties:
                        path:
                          type: string
                          description: Field path that failed validation.
                        message:
                          type: string
                          description: Validation failure message for this field.
                      required:
                        - path
                        - message
                    description: Field-level validation issues when request validation fails.
                required:
                  - error
        "403":
          description: Phone number does not belong to this organization
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Machine-readable error code.
                  reason:
                    type: string
                    description: Human-readable explanation of the error.
                  hint:
                    type: string
                    description: Actionable hint to fix the request, when available.
                  issues:
                    type: array
                    items:
                      type: object
                      properties:
                        path:
                          type: string
                          description: Field path that failed validation.
                        message:
                          type: string
                          description: Validation failure message for this field.
                      required:
                        - path
                        - message
                    description: Field-level validation issues when request validation fails.
                required:
                  - error
        "404":
          description: Phone number not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Machine-readable error code.
                  reason:
                    type: string
                    description: Human-readable explanation of the error.
                  hint:
                    type: string
                    description: Actionable hint to fix the request, when available.
                  issues:
                    type: array
                    items:
                      type: object
                      properties:
                        path:
                          type: string
                          description: Field path that failed validation.
                        message:
                          type: string
                          description: Validation failure message for this field.
                      required:
                        - path
                        - message
                    description: Field-level validation issues when request validation fails.
                required:
                  - error
        "500":
          description: Server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Machine-readable error code.
                  reason:
                    type: string
                    description: Human-readable explanation of the error.
                  hint:
                    type: string
                    description: Actionable hint to fix the request, when available.
                  issues:
                    type: array
                    items:
                      type: object
                      properties:
                        path:
                          type: string
                          description: Field path that failed validation.
                        message:
                          type: string
                          description: Validation failure message for this field.
                      required:
                        - path
                        - message
                    description: Field-level validation issues when request validation fails.
                required:
                  - error
webhooks:
  voice.callInit:
    post:
      tags:
        - Voice Webhooks
      summary: Call initialization webhook
      description: >-
        Sent when a call is initiated, before the agent starts speaking.

        Use this to provide dynamic values or additional instructions based on
        caller context.


        **Headers sent with each request:**

        - `x-chatbyte-signature`: HMAC-SHA256 signature (`v1={hex}`)

        - `x-chatbyte-timestamp`: Unix timestamp (seconds)


        **Signature verification:** Compute HMAC-SHA256 of
        `{timestamp}.{raw_body}` using your webhook secret.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CallInitWebhookPayload"
      responses:
        "200":
          description: Return dynamic values and/or additional prompt instructions
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CallInitWebhookResponse"
  voice.postCall:
    post:
      tags:
        - Voice Webhooks
      summary: Post-call webhook
      description: >-
        Sent after a call ends or fails to connect with normalized outcome
        metadata.

        Use this to sync call data to your CRM, trigger follow-up workflows, or
        update records.


        **Forwarding scenarios:**

        - Completed calls are forwarded with `status = "completed"`. No `reason`
        or `providerReason` is included.

        - Failed connection attempts are forwarded with `status = "failed"`.
        Chatbyte adds a normalized `reason` such as `not_picked_up` when it can
        classify the failure, and includes `providerReason` when additional
        detail is available.

        - Duplicate audio-only events are not sent as separate customer
        `voice.postCall` webhooks.

        - If a failed-connection event is not emitted for an answered call,
        Chatbyte sends the completed post-call event when the final call summary
        is available.


        **Headers sent with each request:**

        - `x-chatbyte-signature`: HMAC-SHA256 signature (`v1={hex}`)

        - `x-chatbyte-timestamp`: Unix timestamp (seconds)


        **Signature verification:** Compute HMAC-SHA256 of
        `{timestamp}.{raw_body}` using your webhook secret.


        **Note:** This webhook is fire-and-forget. The response is not
        processed.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CallCompletedWebhookPayload"
      responses:
        "200":
          description: Acknowledge receipt (response body is ignored)
  voice.toolInvocation:
    post:
      tags:
        - Voice Webhooks
      summary: Tool invocation webhook
      description: >-
        Sent when a synced voice webhook tool is invoked and Chatbyte forwards
        the normalized payload to your configured webhook endpoint.

        Use this to implement custom actions against a stable Chatbyte contract.


        **Headers sent with each request:**

        - `x-chatbyte-signature`: HMAC-SHA256 signature (`v1={hex}`)

        - `x-chatbyte-timestamp`: Unix timestamp (seconds)


        **Signature verification:** Compute HMAC-SHA256 of
        `{timestamp}.{raw_body}` using your webhook secret.


        **Normalization rules:**

        - `agentId` and `phoneNumberId` are Chatbyte IDs.

        - Internal transport IDs are not forwarded.

        - Custom tool inputs are nested under `data.parameters`.

        - Return a 2xx response within 5 seconds. Retries are not attempted.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ToolInvocationWebhookPayload"
      responses:
        "200":
          description: Acknowledge receipt within 5 seconds (response body is ignored)
