openapi: 3.0.3
info:
  title: Callbook AI - Call Trigger API
  description: |
    This API allows triggering calls to customers through Callbook AI's assistant system.
    Calls are initiated using an assistant ID and must include the phone number as a required field.
    After the call, Callbook AI can send results to a provided webhook URL.
  version: 1.0.0
  contact:
    name: Callbook AI Support
    email: support@callbook.ai
    url: https://callbook.ai

servers:
  - url: https://api.callbook.ai
    description: Production Server

tags:
  - name: Calls
    description: Endpoints for triggering and managing AI-driven calls.
  - name: Webhooks
    description: Endpoints for receiving call results or other notifications.

paths:
  /crm/webhook/new_call/api/{ASSISTANT_ID}:
    post:
      tags:
        - Calls
      summary: Trigger a new call
      description: |
        Initiates a new call using a specific assistant ID.
        The request body must contain at least a phone number.
        Optionally, a `callback_url` can be provided where Callbook AI will send call results after completion.
      security:
        - BearerAuth: []
      parameters:
        - name: ASSISTANT_ID
          in: path
          required: true
          description: The unique identifier of the assistant initiating the call.
          schema:
            type: string
            example: "assistant_123456"

      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                phone:
                  type: string
                  description: The customer's phone number (required).
                  example: "+14155552671"
                name:
                  type: string
                  description: The customer's name (optional but recommended).
                  example: "John Doe"
                callback_url:
                  type: string
                  format: uri
                  description: (Optional) A webhook URL where Callbook AI will send the call results after completion.
                  example: "https://yourserver.com/webhook/call_results"
                next_payment:
                  type: string
                  description: (Optional) The customer's next payment date.
                  example: "2025-02-10"
                last_purchase_date:
                  type: string
                  description: (Optional) The last date of purchase.
                  example: "2025-01-15"
                product_interest:
                  type: string
                  description: (Optional) The product or service the customer is interested in.
                  example: "Premium Plan"
                location:
                  type: string
                  description: (Optional) The customer's location.
                  example: "New York"

      responses:
        "200":
          description: Call successfully triggered.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: "success"
                  call_id:
                    type: string
                    example: "call_789456"
        "400":
          description: Bad request (missing required fields).
        "401":
          description: Unauthorized (invalid or missing JWT token).
        "500":
          description: Internal server error.

  /webhook/call_results:
    post:
      tags:
        - Webhooks
      summary: Receive call results
      description: |
        This endpoint should be implemented by clients to receive call results from Callbook AI.
        If a `callback_url` was provided when triggering the call, Callbook AI will send a `POST` request to it with the following structure.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                call_id:
                  type: string
                  description: The unique identifier of the call.
                  example: "call_789456"
                assistant_id:
                  type: string
                  description: The assistant that handled the call.
                  example: "assistant_123456"
                transcription:
                  type: array
                  description: The transcription of the conversation.
                  items:
                    type: object
                    properties:
                      speaker:
                        type: string
                        enum: [user, assistant]
                        description: The speaker of each message.
                        example: "user"
                      text:
                        type: string
                        description: The spoken text.
                        example: "Hello, I need help with my order."
                variables:
                  type: object
                  description: Key-value pairs with additional call metadata.
                  properties:
                    voicemail:
                      type: boolean
                      description: Whether the call reached voicemail.
                      example: true
                    call_duration:
                      type: integer
                      description: Duration of the call in seconds.
                      example: 45
                    custom_field_1:
                      type: string
                      description: (Optional) Any custom field related to the assistant's configuration.
                      example: "Custom Value"
                    custom_field_2:
                      type: string
                      description: (Optional) Another custom field related to the assistant's configuration.
                      example: "Another Value"
      responses:
        "200":
          description: Webhook received successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  phone_number:
                    type: string
                  country_code:
                    type: string
                  whole_number:
                    type: string
                  duration:
                    type: integer
                  status:
                    type: string
                  audio:
                    type: string
                  phone:
                    type: string
                  name:
                    type: string
                  voicemail:
                    type: string
                  user_asked_to_be_called_again:
                    type: string
              examples:
                mockExample:
                  summary: Example of a successful call result
                  value:
                    phone_number: "3151234567"
                    country_code: "57"
                    whole_number: "+573151234567"
                    duration: 5
                    status: "finished"
                    audio: "https://phoneai.s3.amazonaws.com/call_recordings/ca_55ba7a51-48a1-4564-8b5b-cab0b73c45a3.wav"
                    phone: "+573151234567"
                    name: "Carolina"
                    voicemail: "NO"
                    user_asked_to_be_called_again: ""
        "400":
          description: Bad request (invalid data).
        "500":
          description: Internal server error.

  /calls/client/{client_id}:
    get:
      tags:
        - Calls
      summary: Retrieve call statistics by client ID
      description: |
        Retrieves calls from the database for a given `client_id` inside `crm_data`.
        Returns the number of calls, total duration, and breakdown of statuses (e.g., finished, unanswered, failed).
      security:
        - BearerAuth: []
      parameters:
        - name: client_id
          in: path
          required: true
          description: The unique client ID associated with the calls.
          schema:
            type: string
            example: "ac8238ec-1689-40d0-8bd8-18af6141f5f5"

      responses:
        "200":
          description: Successfully retrieved call statistics.
          content:
            application/json:
              schema:
                type: object
                properties:
                  client_id:
                    type: string
                    description: The client ID queried.
                    example: "ac8238ec-1689-40d0-8bd8-18af6141f5f5"
                  total_calls:
                    type: integer
                    description: Total number of calls for this client.
                    example: 5
                  total_duration:
                    type: integer
                    description: Sum of all call durations (in seconds).
                    example: 350
                  status_counts:
                    type: object
                    properties:
                      finished:
                        type: integer
                        description: Number of completed calls.
                        example: 3
                      unanswered:
                        type: integer
                        description: Number of unanswered calls.
                        example: 1
                      failed:
                        type: integer
                        description: Number of failed calls.
                        example: 1
        "400":
          description: Bad request (missing client_id).
        "401":
          description: Unauthorized (invalid or missing Bearer token).
        "404":
          description: No calls found for the provided client ID.
        "500":
          description: Internal server error.

  /generate_voice_note:
    post:
      tags:
        - Voice Notes
      summary: Generate a new voice note
      description: |
        Generates a voice note based on the provided text and voice ID, returning an OGG file URL.
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                vid:
                  type: string
                  description: UUID of the voice.
                  example: "vid_6c859031-ed4c-4ed3-9134-6bdc6b69b90c"
                text:
                  type: string
                  description: The text to be converted into a voice note.
                  example: "Hello, welcome to Callbook AI."
                client_id:
                  type: string
                  description: UUID of the client requesting the voice note.
                  example: "ac8238ec-1689-40d0-8bd8-18af6141f5f5"
      responses:
        "200":
          description: Successfully generated the voice note.
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: The unique identifier of the generated voice note.
                    example: "vn_123456789"
                  path:
                    type: string
                    description: URL to the generated voice note.
                    example: "https://s3.amazonaws.com/voice_notes/vn_123456789.ogg"
                  duration:
                    type: integer
                    description: Duration of the generated voice note in seconds.
                    example: 10
                  client_id:
                    type: string
                    description: The client ID associated with the request.
                    example: "ac8238ec-1689-40d0-8bd8-18af6141f5f5"
        "400":
          description: Bad request (missing required fields).
        "401":
          description: Unauthorized (invalid or missing JWT token).
        "500":
          description: Internal server error.

  /list_voices:
    get:
      tags:
        - Voice Notes
      summary: Retrieve available voices
      description: |
        Retrieves a list of available voices that can be used to generate voice notes.
      responses:
        "200":
          description: Successfully retrieved the list of voices.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: "List of voices"
                  voices:
                    type: array
                    items:
                      type: object
                      properties:
                        country:
                          type: string
                          description: Country of the voice.
                          example: "MX"
                        gender:
                          type: string
                          description: Gender of the voice.
                          example: "female"
                        subDetail:
                          type: string
                          description: Additional details about the voice.
                          example: "1"
                        vid:
                          type: string
                          description: UUID of the voice.
                          example: "vid_6c859031-ed4c-4ed3-9134-6bdc6b69b90c"
        "500":
          description: Internal server error.

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT