{
  "openapi": "3.0.0",
  "info": {
    "title": "Voice Archiving API",
    "description": "API for uploading voice call metadata including references to voice files",
    "contact": {
      "email": "all_enterprise_api@globalrelay.net"
    },
    "version": "1.1"
  },
  "servers": [
    {
      "url": "/"
    }
  ],
  "paths": {
    "/v2/voicedata": {
      "post": {
        "tags": [
          "voiceData"
        ],
        "summary": "Adds multiple voice records.",
        "description": "Send metadata, source transcription and voice records to the archive with an option of transcription being generated by Global Relay",
        "operationId": "sendVoiceData",
        "parameters": [
          {
            "name": "X-SubType",
            "in": "header",
            "required": true,
            "style": "simple",
            "explode": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/voiceData"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/apiResponse"
                }
              }
            }
          },
          "202": {
            "description": "Accepted",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/apiAcceptedResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/errorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Record Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/errorResponse"
                }
              }
            }
          },
          "429": {
            "description": "Rate Limit for this endpoint has been exceeded. Check headers for more information.",
            "headers": {
              "ratelimit-limit": {
                "description": "The total number of requests permitted per time period.",
                "schema": {
                  "type": "integer"
                }
              },
              "ratelimit-remaining": {
                "description": "The number of requests left on your account for the time window.",
                "schema": {
                  "type": "integer"
                }
              },
              "ratelimit-reset": {
                "description": "The number of seconds until the rate limit resets.",
                "schema": {
                  "type": "integer",
                  "format": "seconds"
                }
              }
            },
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string",
                  "example": "Limits exceeded"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "voiceData": {
        "required": [
          "callOverview",
          "requestInfo",
          "voiceRecords"
        ],
        "type": "object",
        "properties": {
          "requestInfo": {
            "$ref": "#/components/schemas/requestInfo"
          },
          "callOverview": {
            "$ref": "#/components/schemas/callOverview"
          },
          "voiceRecords": {
            "type": "array",
            "description": "Voice files, with additional information",
            "items": {
              "$ref": "#/components/schemas/voiceRecord"
            }
          },
          "extraFiles": {
            "type": "array",
            "description": "Additional files to be attached to generated email",
            "items": {
              "$ref": "#/components/schemas/fileInfo"
            }
          }
        },
        "description": "The top level voice data request."
      },
      "requestInfo": {
        "required": [
          "requestId"
        ],
        "type": "object",
        "properties": {
          "requestId": {
            "type": "string",
            "description": "Client generated uuid for tracking purposes",
            "example": "6124FC40-CA47-1000-B311-00DD010662DA"
          }
        },
        "description": "Information for routing the email to the archive."
      },
      "callOverview": {
        "required": [
          "callId",
          "owner"
        ],
        "type": "object",
        "properties": {
          "callId": {
            "type": "string",
            "description": "This will be used for threading across subtypes in A10.",
            "example": "123456789"
          },
          "owner": {
            "$ref": "#/components/schemas/user"
          },
          "callType": {
            "type": "string",
            "description": "the type of call.",
            "example": "intercom"
          },
          "direction": {
            "type": "string",
            "description": "direction of call",
            "example": "inbound",
            "enum": [
              "inbound",
              "outbound"
            ]
          },
          "stopReason": {
            "type": "string",
            "description": "reason for call ending.",
            "example": "owner_hangup",
            "enum": [
              "hangup",
              "owner_hangup",
              "remote_hangup",
              "forward",
              "unsuccessful",
              "unknown"
            ]
          },
          "deviceName": {
            "type": "string",
            "description": "the name of the device which made the call.",
            "example": "Office phone"
          },
          "isExternal": {
            "type": "boolean",
            "description": "Flag to comment on whether user is external or internal to the organisation",
            "example": true
          },
          "subjectOverride": {
            "maxLength": 998,
            "type": "string",
            "description": "If populated overrides the subject header of the email.",
            "example": "New Subject for email"
          },
          "callProperties": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/callProperty"
            }
          }
        }
      },
      "callProperty": {
        "required": [
          "name",
          "value"
        ],
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "Property name",
            "example": "Call Quality"
          },
          "value": {
            "type": "string",
            "description": "Property value",
            "example": "5.0"
          },
          "xheader": {
            "type": "boolean",
            "description": "Defines if a xheader is to be created in the Archive for this conversation property. The displayed header name will be prefixed with \"X-GR-OC-\"",
            "example": false,
            "default": false
          },
          "hidden": {
            "type": "boolean",
            "description": "Defines if the call property should be hidden from the call property table. This should be used in conjunction with the xheader property. If the xheader property is set to false and this is set to true, the call property will not be rendered in the email.",
            "example": true,
            "default": false
          }
        }
      },
      "voiceRecord": {
        "required": [
          "startTime"
        ],
        "type": "object",
        "properties": {
          "startTime": {
            "pattern": "^\\d{1,19}$",
            "type": "integer",
            "description": "Start time of call",
            "format": "int64",
            "example": 1621851918000
          },
          "stopTime": {
            "pattern": "^\\d{1,19}$",
            "type": "integer",
            "description": "End time of call",
            "format": "int64",
            "example": 1621851918000
          },
          "timeZone": {
            "type": "string",
            "description": "Time zone identifier",
            "example": "EST"
          },
          "participants": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/user"
            }
          },
          "recordingFile": {
            "$ref": "#/components/schemas/recordingFile"
          }
        }
      },
      "user": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "User name",
            "example": "Adam Smith"
          },
          "company": {
            "type": "string",
            "description": "Users company name",
            "example": "Wavelength Securities"
          },
          "detail": {
            "type": "string",
            "description": "Addition information about the user (role, location...)",
            "example": "Business Analyst"
          },
          "phone": {
            "type": "string",
            "description": "Phone number",
            "example": "555 012 2345"
          },
          "email": {
            "type": "string",
            "description": "Email address",
            "example": "adam.smith@wavelength.com"
          },
          "channel": {
            "type": "integer",
            "description": "Used to provide mapping between the user and channel",
            "example": 0,
            "default": 0
          },
          "joinTimeMS": {
            "pattern": "^\\d{1,19}$",
            "type": "integer",
            "description": "User join time",
            "format": "int64",
            "example": 1621851918000
          },
          "leaveTimeMS": {
            "pattern": "^\\d{1,19}$",
            "type": "integer",
            "description": "User leave time",
            "format": "int64",
            "example": 1621851918000
          },
          "identityType": {
            "type": "string",
            "description": "Indicates what type the user is",
            "example": "internal",
            "enum": [
              "internal",
              "external",
              "bot"
            ]
          }
        },
        "description": "One of the below identifiers (Email, Phone or Name) should be provided"
      },
      "recordingFile": {
        "type": "object",
        "properties": {
          "filename": {
            "type": "string",
            "description": "Name of the audio file",
            "example": "call1234.mp4"
          },
          "description": {
            "type": "string",
            "description": "Description of audio file",
            "example": "Morning call"
          },
          "fileKey": {
            "type": "string",
            "description": "Key used to store file on object store",
            "example": "morningcalls/call1234.mp4"
          }
        }
      },
      "fileInfo": {
        "type": "object",
        "properties": {
          "filename": {
            "type": "string",
            "description": "File name of additional file",
            "example": "attachment3.doc"
          },
          "fileKey": {
            "type": "string",
            "description": "Key used to store file on object store",
            "example": "attachments/attachment3.doc"
          },
          "fileHref": {
            "type": "string",
            "description": "Hyperlink for additional file",
            "example": "https://www.globalrelay.com/?"
          },
          "description": {
            "type": "string",
            "description": "File description",
            "example": "List of callers"
          },
          "isTranscript": {
            "type": "boolean",
            "description": "True if file represents a transcript, default is false.",
            "example": false,
            "default": false
          }
        }
      },
      "apiResponse": {
        "required": [
          "reconciliationId"
        ],
        "type": "object",
        "properties": {
          "reconciliationId": {
            "type": "string",
            "description": "Unique ID assigned by API service for each request.",
            "readOnly": true,
            "example": "60128f870f0d6e0d7a9ce772"
          }
        }
      },
      "apiAcceptedResponse": {
        "required": [
          "reconciliationId",
          "status"
        ],
        "type": "object",
        "properties": {
          "reconciliationId": {
            "type": "string",
            "description": "Unique ID assigned by API service for each request.",
            "readOnly": true,
            "example": "c1319852-5367-5958-9aee-98fffdc22493"
          },
          "status": {
            "type": "string",
            "description": "Status of the request, indicating if the request is a duplication of a previous request.",
            "readOnly": true,
            "example": "duplicate"
          }
        }
      },
      "errorResponse": {
        "type": "object",
        "properties": {
          "status": {
            "type": "integer",
            "description": "The HTTP status Error code",
            "example": 400
          },
          "message": {
            "type": "string",
            "description": "The HTTP Error message",
            "example": "Client Error"
          },
          "error": {
            "type": "string",
            "description": "Friendly Error Message",
            "example": "Bad Request. Request is not well-formed"
          },
          "timestamp": {
            "type": "string",
            "format": "date-time",
            "example": "2020-07-09T17:04:46.693654Z"
          },
          "correlationId": {
            "type": "string",
            "description": "The correlationId",
            "example": "6a4c4d44-dd28-474b-9eb9-a7c03d04b2e1"
          },
          "errors": {
            "type": "array",
            "description": "Detailed descriptions of a validation error by field",
            "items": {
              "$ref": "#/components/schemas/errorResponse_errors"
            }
          }
        }
      },
      "errorResponse_errors": {
        "type": "object",
        "properties": {
          "field": {
            "type": "string",
            "example": "Incorrect value"
          },
          "reason": {
            "type": "string",
            "description": "the validation error that applies to the field",
            "example": "Invallid direction"
          }
        }
      }
    },
    "responses": {
      "Error-429-Rate-Limit-Exceeded-3Scale": {
        "description": "Rate Limit for this endpoint has been exceeded. Check headers for more information.",
        "headers": {
          "ratelimit-limit": {
            "description": "The total number of requests permitted per time period.",
            "schema": {
              "type": "integer"
            }
          },
          "ratelimit-remaining": {
            "description": "The number of requests left on your account for the time window.",
            "schema": {
              "type": "integer"
            }
          },
          "ratelimit-reset": {
            "description": "The number of seconds until the rate limit resets.",
            "schema": {
              "type": "integer",
              "format": "seconds"
            }
          }
        },
        "content": {
          "text/plain": {
            "schema": {
              "type": "string",
              "example": "Limits exceeded"
            }
          }
        }
      }
    }
  }
}