openapi: 3.2.0
info:
  title: Sonetel Ai Service API
  version: '2.0'
  description: 'Operations tagged Ai Service across 2 of this provider''s published API definitions: 12_ai_services.yaml, sonetel-ai-services-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://public-api.sonetel.com
  description: Production
security:
- grant_type: []
tags:
- name: Ai Service
paths:
  /ai-service/business-description:
    post:
      summary: Write business description
      description: 'Request the AI services to create a business description.

        You may request a business description by providing the business website URL. You may also optionally have an existing description re-written by specifying the text_id for it and providing user feedback on it.


        The business description is created in the same language as that of the website URL.


        To write a business description, specify the `url`.


        To re-write a business description, specify the `text_id` of the business description and `user_input`.


        `account_id` is optional. The API automatically uses the authentication token to get your account\_id. `account_id` must only be specified if you have a partner account with Sonetel and are requesting a service on behalf of a sub-account.

        `business_id` is optional and is used to automatically get details of the business (such as the `url`) if the details are not provided in the request.


        `business_id` and `user_id` are not set in the service instance if they are not passed.'
      operationId: post-ai-service-business-description
      requestBody:
        $ref: '#/components/requestBodies/Post-business-description'
      responses:
        '202':
          $ref: '#/components/responses/Post-service-response'
      security:
      - grant_type: []
      servers:
      - url: https://public-api.sonetel.com
        description: Production
      tags:
      - Ai Service
    servers:
    - url: https://public-api.sonetel.com
      description: Production
  /ai-service/blog-title-list:
    post:
      summary: Generate blog titles
      description: 'Request the AI service to generate a list of blog titles based on a business description.

        Business description may be specified by passing the `text_id` of the business description in the inputs. If this isn''t provided, the business description corresponding to the `business_id` in the account context is used.'
      operationId: post-ai-service-blog-title-list
      requestBody:
        $ref: '#/components/requestBodies/Post-blog-title-list'
      responses:
        '202':
          $ref: '#/components/responses/Post-service-response'
      security:
      - grant_type: []
      servers:
      - url: https://public-api.sonetel.com
        description: Production
      tags:
      - Ai Service
    servers:
    - url: https://public-api.sonetel.com
      description: Production
  /ai-service/blog:
    post:
      summary: Write a blog
      description: Request the AI service to write a blog article given an input such as a title of the blog, or an existing blog with feedback for re-writing.
      operationId: post-ai-service-blog
      requestBody:
        $ref: '#/components/requestBodies/Post-blog'
      responses:
        '202':
          $ref: '#/components/responses/Post-service-response'
      security:
      - grant_type: []
      servers:
      - url: https://public-api.sonetel.com
        description: Production
      tags:
      - Ai Service
    servers:
    - url: https://public-api.sonetel.com
      description: Production
  /ai-service/meeting-minutes:
    post:
      summary: Write meeting minutes
      description: Request the AI service to write meeting minutes given file with the meeting recording.
      operationId: post-ai-service-meeting-minutes
      requestBody:
        $ref: '#/components/requestBodies/Post-meeting-minutes'
      responses:
        '200':
          $ref: '#/components/responses/Post-service-response'
      security:
      - grant_type: []
      servers:
      - url: https://public-api.sonetel.com
        description: Production
      tags:
      - Ai Service
    servers:
    - url: https://public-api.sonetel.com
      description: Production
  /ai-service/vm-summary:
    post:
      summary: Write voicemail summary
      description: Request the AI service to write a summary from a voicemail audio file
      operationId: post-ai-service-vm-summary
      requestBody:
        $ref: '#/components/requestBodies/Post-vm-summary'
      responses:
        '200':
          $ref: '#/components/responses/Post-service-response'
      security:
      - grant_type: []
      servers:
      - url: https://public-api.sonetel.com
        description: Production
      x-internal: true
      tags:
      - Ai Service
    servers:
    - url: https://public-api.sonetel.com
      description: Production
  /ai-service/call-summary:
    post:
      summary: Write call summary
      description: Request a call summary
      operationId: post-ai-service-call-summary
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                account:
                  $ref: '#/components/schemas/Account-context'
                inputs:
                  type: object
                  properties:
                    file:
                      $ref: '#/components/schemas/File-input'
                    call_details:
                      type: object
                      properties:
                        direction:
                          type: string
                          enum:
                          - inbound
                          - outbound
                          - internal
                        intent:
                          type: string
                        company_name:
                          type: string
                        caller_first_name:
                          type: string
                        caller_last_name:
                          type: string
                        caller_role:
                          type: string
                        caller_country:
                          type: string
                        callee_first_name:
                          type: string
                        callee_last_name:
                          type: string
                        callee_role:
                          type: string
                        callee_country:
                          type: string
      responses:
        '200':
          $ref: '#/components/responses/Get-service-by-id'
      security:
      - grant_type: []
      servers:
      - url: https://public-api.sonetel.com
        description: Production
      tags:
      - Ai Service
    servers:
    - url: https://public-api.sonetel.com
      description: Production
  /ai-service/{service_id}:
    get:
      summary: Get Service instance
      description: Fetch a service instance and it status
      operationId: get-ai-service-status
      parameters:
      - name: service_id
        in: path
        description: The Id of the service instance
        required: true
        schema:
          type: string
      responses:
        '200':
          $ref: '#/components/responses/Get-service-by-id'
      security:
      - grant_type: []
      servers:
      - url: https://public-api.sonetel.com
        description: Production
      tags:
      - Ai Service
    servers:
    - url: https://public-api.sonetel.com
      description: Production
  /ai-service:
    get:
      summary: List service instances
      description: Fetch a list of service instances based on criteria
      operationId: get-ai-service
      parameters:
      - name: account_id
        in: query
        description: List services for this account_id
        schema:
          type: string
      - name: business_id
        in: query
        description: List services for this business_id
        schema:
          type: string
      - name: user_id
        in: query
        description: List services with this user-Id
        schema:
          type: string
      - name: service_type
        in: query
        description: List services of this type
        schema:
          type: string
          enum:
          - business-description
          - blog-title-list
          - blog
          - meeting-minutes
          examples:
          - blog
      - name: status
        in: query
        description: List services with this status
        schema:
          type: string
          enum:
          - not_started
          - in_progress
          - completed
          - failed
      - name: create_date
        in: query
        description: Filter create date with operators `*__gte*` (Greater than or equal to), `*__lte*` (Less than or equal to), or `*=*`
        schema:
          type: string
      - name: update_date
        in: query
        description: Filter update date with operators `*__gte*` (Greater than or equal to), `*__lte*` (Less than or equal to), or `*=*`
        schema:
          type: string
      responses:
        '200':
          $ref: '#/components/responses/Get-service-list'
      security:
      - grant_type: []
      servers:
      - url: https://public-api.sonetel.com
        description: Production
      tags:
      - Ai Service
    servers:
    - url: https://public-api.sonetel.com
      description: Production
components:
  schemas:
    Service-object:
      type: object
      title: Service-object
      description: A service object along with its status
      properties:
        service_id:
          type: string
          description: The service Id of the service instance
        account:
          $ref: '#/components/schemas/Account-context'
        text_id:
          type: string
          description: The text_id where the services writes the output text
        status:
          $ref: '#/components/schemas/Service-status'
          description: The status of the service instance
        create_date:
          type: string
          description: The date/time this service started
          format: date-time
        update_date:
          type: string
          description: The last modified date/time
          format: date-time
        error:
          type: object
          description: Error details, if service instance has failed
          properties:
            code:
              type: string
              description: Error code (details to be specified)
            description:
              type: string
              description: A descriptive text of the error
    Blog-title-list-inputs:
      type: object
      title: Blog-title-list-inputs
      description: Inputs to service for generating blog title list
      properties:
        business_description:
          type: object
          description: Specify the text_id of the business description to generate a list of titles based on that
          properties:
            text_id:
              type: string
              description: Text Id of the business description for which the blog titles must be generated
              examples:
              - xGn3j7Jhy
        language:
          type: string
          description: Language in which blog titles should be returned. [2 char ISO](https://en.wikipedia.org/wiki/ISO_639-1) or [IETF language tags](https://en.wikipedia.org/wiki/IETF_language_tag)
    Meeting-minutes-inputs:
      type: object
      title: Meeting-minutes-inputs
      description: Inputs for meeting minutes
      properties:
        file:
          type: object
          description: Audio/video file details such as `file_id`, `name` and `create_date`.
          properties:
            file_id:
              type: string
              description: Unique file_id of the meeting recording for generating meeting minutes
              format: uuid
              examples:
              - e52672c0-fe41-498c-b4b5-a18504f4d147
            name:
              type: string
              description: Name of the meeting
            create_date:
              type: string
              description: The date and time of the meeting.
              format: date-time
              examples:
              - '2025-06-24T10:37:59.140Z'
          required:
          - file_id
          - create_date
    Blog-post-process:
      type: object
      title: Blog-post-process
      description: Optional settings and functions to be used while generating a Blog title list
      properties:
        photos:
          type: object
          properties:
            add_photos:
              type: boolean
        links:
          type: object
          description: Specify web links that must be automatically added to blog text automatically
          properties:
            internal:
              type: boolean
              description: Text related to the business (such as company name, company product names) are made clickable links
            external:
              type: boolean
              description: Text that has publicly available information on wikipedia and similar sites are makde clicable links (e.g. "Contact center" or "Virtual number")
    Account-context:
      type: object
      title: Account-context
      description: Account, user and business information
      properties:
        account_id:
          type: string
          description: Sonetel account Id
          examples:
          - 4hNj7651d
        business_id:
          type: string
          description: Optional business Id
          examples:
          - 9iuj53hggys-65
        user_id:
          type: string
          description: Optional user Id
          examples:
          - bv3hy09kkj6
    Business-description-inputs:
      type: object
      title: Business-description-inputs
      description: Inputs to service for generating a business description
      properties:
        url:
          type: string
          description: The URL of the business website
          format: uri-reference
          examples:
          - www.sonetel.com
        name:
          type: string
          description: The name of the business
        language:
          type: string
          description: Language in which business description should be created. If this is not specified, the language is automatically set based on the inputs provided (e.g. the language of the text on the website). [2 char ISO](https://en.wikipedia.org/wiki/ISO_639-1) or [IETF language tags](https://en.wikipedia.o
        user_input:
          type: string
          description: User input guidelines or feedback for the business description. The feedback can only be provided on an existing description to have it re-written
        text_id:
          type: string
          description: Text_Id of the business description. This must be provided if the business description is to be re-written.
    Blog-inputs:
      type: object
      title: Blog-inputs
      description: Inputs to service for generating a blog.
      properties:
        blog_title:
          type: object
          description: To use a generated title list stored in the [textmgr](13_ai_textmanager.yaml/paths,/~1textmgr~1text~1{text_id}~1blog-title-list), specify the text_id of the title list and the title_id fr of the title from the list
          properties:
            text_id:
              type: string
              description: The text Id of the blog title
              examples:
              - bg3hgy5
            title_id:
              type: string
              description: The title in the blog title list
              examples:
              - rbhg1lki
            version:
              type: number
              description: The version number of the blog title. If unspecified, this points to the latest version of the blog title
              minimum: 1
              examples:
              - 2
        blog:
          type: object
          description: Specify this if a blog should be re-written
          properties:
            text_id:
              type: string
              description: Text_id of the blog that must be re-written
              examples:
              - dnb167
        user_input:
          type: string
          description: User input guidelines or feedback for re-writing a blog. The feedback may only be provided on an existing blog to have it re-written.
          examples:
          - The blog must be adapted to primarily address an African consumer audience
    Service-status:
      type: object
      title: Service-status
      description: The service status information including an overall status and progress information
      properties:
        status:
          type: string
          enum:
          - not_started
          - in_progress
          - completed
          - failed
          description: The status of the service instance
        steps_total:
          type: integer
          description: Total steps that the service instance should execute
          examples:
          - 3
        steps_done:
          type: integer
          description: Total steps completed by the service instance
          examples:
          - 2
        last_step_time:
          type: string
          description: The date/time when the last step was completed
          format: date-time
      required:
      - status
    File-input:
      type: object
      title: File-input
      description: File either as a `file_id` or a file URL
      oneOf:
      - type: object
        properties:
          file_id:
            type: string
            description: Unique file_id of a file managed by the [File managemer](reference/15_ai_filemanager.yaml)
      - type: object
        properties:
          file_url:
            type: string
            description: File URL of a file
            format: uri
  responses:
    Get-service-by-id:
      description: A service instance
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Service-object'
        application/xml:
          schema:
            type: object
    Post-service-response:
      description: Information about service instance created and references where text and file output is available
      content:
        application/json:
          schema:
            type: object
            properties:
              service_id:
                type: string
                description: Id of the service instance created
              text_id:
                type: string
                description: Text_id where the generated text would be available
              ai_credit_balance:
                type: integer
                description: AI credits remaining in the account
                format: int32
                readOnly: true
                examples:
                - 125
    Get-service-list:
      description: List of service instances
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: '#/components/schemas/Service-object'
  requestBodies:
    Post-vm-summary:
      description: Voicemail summary request
      content:
        application/json:
          schema:
            type: object
            properties:
              account:
                $ref: '#/components/schemas/Account-context'
              input:
                type: object
                properties:
                  file:
                    $ref: '#/components/schemas/File-input'
                    description: The voicemail audio file
                  caller_name:
                    type: string
                    description: 'The name of the caller.

                      Caller name maybe optionally provided in case it is known to the service requesting the summary

                      In case it is provided, the AI service uses it while generating the voicemail summary'
                  company_name:
                    type: string
                    description: 'The company name of the caller.

                      The company name of the caller can be provided optionally, if known to the service requesting the AI service'
                required:
                - file
            required:
            - account
    Post-business-description:
      description: Request to write a business description. The URL must be provided
      content:
        application/json:
          schema:
            type: object
            properties:
              account:
                $ref: '#/components/schemas/Account-context'
              inputs:
                $ref: '#/components/schemas/Business-description-inputs'
            required:
            - inputs
    Post-blog-title-list:
      description: Request to generate a blog title list
      content:
        application/json:
          schema:
            type: object
            properties:
              account:
                $ref: '#/components/schemas/Account-context'
              inputs:
                $ref: '#/components/schemas/Blog-title-list-inputs'
    Post-meeting-minutes:
      description: Request to create meeting minutes
      content:
        application/json:
          schema:
            type: object
            properties:
              account:
                $ref: '#/components/schemas/Account-context'
              input:
                $ref: '#/components/schemas/Meeting-minutes-inputs'
    Post-blog:
      description: Request to write a blog
      content:
        application/json:
          schema:
            type: object
            properties:
              account:
                $ref: '#/components/schemas/Account-context'
              input:
                $ref: '#/components/schemas/Blog-inputs'
              post_process:
                $ref: '#/components/schemas/Blog-post-process'
  securitySchemes:
    grant_type:
      type: oauth2
      flows:
        password:
          refreshUrl: ''
          tokenUrl: ''
          scopes: {}
x-refined-from:
- 12_ai_services.yaml
- sonetel-ai-services-openapi.yml