openapi: 3.1.0
info:
  title: Webhooks
  version: 0.9.3
servers:
  - url: https://{yourserver}
security:
  - basicAuth: []
paths:
  /webhooks/call:
    post:
      operationId: callHookPost
      summary: New Call
      description: This webhook is sent when a new call is created on the platform, it is configured at the appplication level
      requestBody:
        description: Information about a new call
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CallHook'
      responses:
        '200':
          description: Return a 200 containing a JSON payload consisting of an array of verbs
    get:
      operationId: callHookGet
      summary: New Call
      description: This webhook is sent when a new call is created on the platform, it is configured at the appplication level
      parameters:
        - name: call_sid
          in: query
          required: true
          schema:
              $ref: '#/components/schemas/CallHook/properties/call_sid'
        - name: application_sid
          in: query
          required: true
          schema:
              $ref: '#/components/schemas/CallHook/properties/application_sid'
        - name: account_sid
          in: query
          required: true
          schema:
              $ref: '#/components/schemas/CallHook/properties/account_sid'
        - name: direction
          in: query
          required: true
          schema:
            $ref: '#/components/schemas/CallHook/properties/direction'
        - name: from
          in: query
          required: true
          schema:
              $ref: '#/components/schemas/CallHook/properties/from'
        - name: to
          in: query
          required: true
          schema:
              $ref: '#/components/schemas/CallHook/properties/to'
        - name: caller_name
          in: query
          required: true
          schema:
              $ref: '#/components/schemas/CallHook/properties/caller_name'
        - name: call_status
          in: query
          required: true
          schema:
            $ref: '#/components/schemas/CallHook/properties/call_status'        
        - name: sip_status
          in: query
          required: true
          schema:
            $ref: '#/components/schemas/CallHook/properties/sip_status' 
      responses:
        '200':
          description: Return a 200 containing a JSON payload consisting of an array of verbs
  /webhooks/auth:
    post:
      operationId: registrationHookPost
      summary: Client Authentication
      description: This webhook is sent when a SIP client tries to authenticate, it is configured at the account level
      requestBody:
        description: |
          provides details of the authentication request.  The receiving server is responsible for authenticating the 
          request as per [RFC 2617](https://tools.ietf.org/html/rfc2617)
        content:
          application/json:
            schema:
              required:
                - method
                - realm
                - username
                - expires
                - nonce
                - uri
                - response
              type: object
              properties:
                method:
                  type: string
                  description: sip request method
                  example: REGISTER
                realm:
                  type: string
                  description: sip realm
                  example: mycompany.com
                username:
                  type: string
                  description: sip username provided
                  example: daveh
                expires:
                  type: number
                  description: expiration requested, in seconds
                  example: 3600
                scheme:
                  type: string
                  description: encryption protocol
                  example: digest
                nonce:
                  type: string
                  description: nonce value
                  example: InFriVGWVoKeCckYrTx7wg=="
                uri:
                  type: string
                  format: uri
                  description: sip uri in request
                  example: sip:mycompany.com
                algorithm:
                  type: string
                  description: encryption algorithm used, default to MD5 if not provided
                  example: MD5
                qop:
                  type: string
                  description: qop value
                  example: auth
                cnonce:
                  type: string
                  description: cnonce value
                  example: 6b8b4567
                nc:
                  type: string
                  description: nc value
                  example: 1
                response:
                  type: string
                  description: digest value calculated by the client
                  example: be641cf7951ff23ab04c57907d59f37d
      responses:
        '200':
          description: |
            Your callback should return this HTTP status code in all cases.
            if the request was authenticated and you wish to admit 
            the client to the network, this is indicated by setting the 'status' 
            attribute in the body to 'ok'
          content:
            application/json:
              schema:
                type: object
                required:
                  - status
                properties:
                  status:
                    type: string
                    description: indicates whether the request was successfully authenticated
                    enum:
                      - ok
                      - fail
                    example: ok
                  message:
                    type: string
                    description: a human-readable message
                    example: authentication granted
                  application_sid:
                    type: string
                    format: uuid
                    description: sid of application to invoke when this device places a call
                  expires:
                    type: number
                    description: |
                      The expires value to grant to the requesting user.
                      If not provided, the expires value in the request is observed.
                      If provided, must be less than the requested expires value.
                  blacklist:
                    type: number
                    description: |
                      If provided, represents a period in seconds during which the source IP 
                      address should be blacklisted by the platform (0 means forever).
  /webhooks/tool:
    post:
      operationId: toolHookPost
      summary: New Client Tool Request
      requestBody:
        description: The details of the tool request
        content:
          application/json:
            schema:
              required:
                - tool_call_id
                - name
              properties:
                tool_call_id:
                  type: string
                  example: "chatcmpl-tool-4a231898ff8a4d24bce8146124c3bf5e"
                  description: a unique identifier for the tool request.
                name:
                  type: string
                  example: client-get-time
                  description: The unique name of the client tool being requested
                args:
                  type: object
                  description: Object containing key/value pairs of the parameters specified in the client tool
      responses:
        '200':
          description: |
            Your callback should return this HTTP status code in all cases.
          content:
            application/json:
              schema:
                type: object
                required:
                  - result
                properties:
                  result:
                    type: object
                    description: contains data to be retrurned to the LLM, can contain either a string or an object.
                    
        
components:
  schemas:
    CallHook:
      required:
        - call_sid
        - application_sid
        - account_sid
        - direction
        - from
        - to
        - caller_name
        - call_status
        - sip_status
        - call_id
        - sip_reason
      properties:
        call_sid:
          type: string
          example: "d2515c3b-b79a-41a2-971a-445e769c823c"
          description: a unique identifier for the call.
        call_id:
          type: string
          example: "d2515c3b-b79a-41a2-971a-445e769c823c"
          description: the call id in our server.
        application_sid:
          type: string
          example: "72c5c38f-9bba-40ce-aa83-aaa6be55e1b5"
          description: a unique identifier for the jambonz application controlling this call
        account_sid:
          type: string
          example: "bad98250-b34d-459d-9e90-f97dfb9bc519"
          description: a unique identifier for the jambonz account associated with the application
        direction:
          type: string
          enum: [inbound, outbound ]
          description: >
            the direction of the call:
              * `inbound` - The call was originated outside jambonz
              * `outbound` - The call was originated by jambonz
        from:
          example: "+12125551212"
          type: string
          description: the calling party number
        to:
          example: "+14155551234"
          type: string
          description: the called party number
        caller_name:
          type: string
          example: "John Doe"
          description: the caller name, if known
        sip_status:
          type: number
          example: 100
          description: the most recent sip status code received or generated for the call
        sip_reason:
          type: string
          example: "Trying"
          description: >
            the reason phrase from the SIP status LINE of the last response
            (e.g. `Trying`, `OK`, `Busy Here`). This is not the RFC 3326
            `Reason` header - see `sip_reason_header`.
        sip_reason_header:
          type: string
          example: "Q.850;cause=18"
          description: >
            the RFC 3326 `Reason` header of the SIP message that caused this
            status change, if it carried one; omitted otherwise.


            Carriers fronting ISDN/E1 PRI trunks put the authoritative
            disconnect cause here rather than in the status line, and the same
            SIP status can carry different causes - a `503` may be `cause=38`
            (network out of order) or `cause=41` (temporary failure) - so the
            status code alone cannot classify the outcome of a call. A `408`
            with `Q.850;cause=18` ("no user responding") is a call nobody
            answered, not a platform fault.


            Present on whichever event observed it: a final failure response, a
            `BYE` on an answered call, or a `CANCEL` from a caller who gave up.
            The `CANCEL` case matters most, because the `487` and its
            `Request Terminated` phrase are generated by jambonz itself - so
            without this header every abandoned inbound call looks identical,
            and `SIP;cause=200;text="Call completed elsewhere"` is what
            distinguishes a forked branch losing the race from a caller who
            hung up.


            Two parsing caveats: the header is re-serialized in transit, which
            normalizes the optional whitespace RFC 3326 allows around `;`, so a
            carrier's `Q.850 ;cause=18` arrives as `Q.850;cause=18` - parse
            tolerantly rather than string-matching. And a message may carry more
            than one `Reason` header, in which case they arrive comma-separated;
            split on commas outside quotes, since a `text="..."` value may
            contain one.
        call_status:
          type: string
          enum: [trying, ringing, early-media, in-progress, completed, failed, busy, no-answer ]
          description: >
            current status of the call:
              * `trying` - a new incoming call has arrived or an outbound call has just been sent
              * `ringing` - a 180 Ringing response has been sent or received
              * `early-media` - an early media connection has been established prior to answering the call (183 Session Progress)
              * `in-progress` - call has been answered
              * `completed` - an answered call has ended
              * `failed` - a call attempt failed
              * `busy` - a call attempt failed because the called party returned a busy status
              * `no-answer` - a call attempt failed because it was not answered in time
        sbc_callid:
          type: string
          description: the orignal call ID of the call when it arrived at jambonz
          example: 2025052317511700005@2900-0601-0284-93
        originating_sip_ip:
          type: string
          description: The IP address that send the call to jambonz
          example: 192.0.2.1
        originating_sip_trunk_name:
          type: string
          description: The name of the carrier in Jambonz that recieved the call
          example: MyCarrier
        local_sip_address:
          type: string
          description: Internal Address of the Feature Server handling the call
          example: 172.20.11.38:5060
        service_provider_sid:
          type: string
          description: The ID of the service provider the account handling the call belongs to
          example: 6072f617-6151-4c15-8eb9-74a4967ab701
        sip:
          description: The SIP request for the call
          $ref: '#/components/schemas/sipRequest'
        env_vars:
          description: Application Environment Variables configured for the applicaiton
          type: object
        
    sipRequest:
      required:
        - raw
        - headers
        - body
        - method
        - version
        - uri
        - payload
      properties:
        raw:
          type: string
          description: the complete SIP request as a single string.
        headers:
          type: object
          description: each of the SIP headers as a key/value object
        body:
          type: string
          description: the body of the request, containing SDP
        method:
          type: string
          description: The SIP method
          example: INVITE
        version:
          type: string
          description: the SIP version
          example: 2.0
        uri:
          type: string
          description: The SIP URI of the request
          example: sip:12125551212@sip.jambonz.cloud
        payload:
          type: object
          description: the body of the request
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic