{
  "openapi": "3.0.1",
  "info": {
    "title": "Conversation Archiving API",
    "description": "Seamlessly integrate with any messaging platform to securely capture your conversations in Global Relay Archive",
    "termsOfService": "https://globalrelay.com/company-info/terms-of-use",
    "contact": {
      "email": "all_enterprise_api@globalrelay.net"
    },
    "version": "1.6"
  },
  "servers": [
    {
      "url": "https://conversations.api.globalrelay.com/v2/conversations",
      "description": "Production Environment"
    }
  ],
  "security": [
    {
      "oAuth2ClientCredentials": []
    }
  ],
  "tags": [
    {
      "name": "Conversation",
      "description": "Send conversation data, e.g. instant messaging data, directly to Global Relay for archiving."
    }
  ],
  "paths": {
    "/v2/conversations": {
      "post": {
        "tags": [
          "Conversation"
        ],
        "summary": "POST a single conversation message",
        "description": "Represents conversation between several parties, eg.g IM messaging or threaded conversation over time",
        "operationId": "createConversation",
        "parameters": [
          {
            "name": "X-SubType",
            "in": "header",
            "required": true,
            "style": "simple",
            "explode": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "description": "Generate a conversation style message",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/createConversationPayload"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Successful Operation",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/createConversationResponse"
                }
              }
            }
          },
          "202": {
            "description": "Accepted",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/createConversationStatusResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request. Request is not well-formed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/errorResponse"
                },
                "example": {
                  "timestamp": "2023-01-15T01:00:00.000000Z",
                  "status": 400,
                  "error": "Client Error",
                  "message": "Bad Request",
                  "path": "api/v1/external/conversations"
                }
              }
            }
          },
          "405": {
            "description": "Method is not supported",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/errorResponse"
                },
                "example": {
                  "timestamp": "2023-01-15T01:00:00.000000Z",
                  "status": 405,
                  "error": "Method Not Allowed",
                  "message": "Method is not supported",
                  "path": "/api/v1/external/conversations"
                }
              }
            }
          },
          "413": {
            "description": "Request size exceeds the allowable limit",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/errorResponse"
                },
                "example": {
                  "timestamp": "2023-01-15T01:00:00.000000Z",
                  "status": 413,
                  "error": "Payload Too Large",
                  "message": "Request size exceeds the allowable limit",
                  "path": "/api/v1/conversations"
                }
              }
            }
          },
          "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",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/errorResponse"
                },
                "example": {
                  "timestamp": "2023-01-15T01:00:00.000000Z",
                  "status": 500,
                  "error": "Internal Server Error",
                  "message": "Internal Server Error",
                  "path": "/api/v1/external/conversations"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "createConversationPayload": {
        "required": [
          "conversationOverview",
          "requestInfo"
        ],
        "type": "object",
        "properties": {
          "requestInfo": {
            "$ref": "#/components/schemas/requestInfo"
          },
          "conversationOverview": {
            "$ref": "#/components/schemas/conversationOverview"
          },
          "conversationEvents": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/conversationEvent"
            }
          }
        },
        "description": "One conversation object that will be converted into one conversation style EML"
      },
      "requestInfo": {
        "required": [
          "requestId"
        ],
        "type": "object",
        "properties": {
          "requestId": {
            "type": "string",
            "description": "Client generated UUID for tracking purposes (A UUID specified by RFC4122).",
            "example": "c1319852-5367-5958-9aee-98fffdc22490"
          }
        },
        "description": "Top level information that must be included in every request payload."
      },
      "conversationOverview": {
        "required": [
          "conversationId",
          "initiatorEmail",
          "initiatorName"
        ],
        "type": "object",
        "properties": {
          "conversationId": {
            "type": "string",
            "description": "An unique ID for the conversation. Unique to the authorized application.",
            "example": "c1319852-5367-5958-9aee-98fffdc22491"
          },
          "initiatorName": {
            "type": "string",
            "description": "Name of the conversation initiator",
            "example": "Joe"
          },
          "initiatorEmail": {
            "type": "string",
            "description": "E-mail of the conversation initiator",
            "example": "joe@example.com"
          },
          "title": {
            "type": "string",
            "description": "Title of the conversation",
            "example": "Meeting using Personal Meeting ID"
          },
          "description": {
            "type": "string",
            "description": "Description of the conversation",
            "example": "Joe's meeting"
          },
          "isExternal": {
            "type": "boolean",
            "description": "Flag for internal/external status. External - including participants from other companies. Internal - no external participants. Internal users only.",
            "example": false
          },
          "isPrivate": {
            "type": "boolean",
            "description": "Flag for private/public status. Public - anyone can join the channel/chat Private - by invites only",
            "example": false
          },
          "initialParticipants": {
            "type": "array",
            "description": "IDs of all participants involved in the conversation during the downloading period. Including users has left the conversation.",
            "items": {
              "$ref": "#/components/schemas/eventUser"
            }
          },
          "conversationProperties": {
            "type": "array",
            "description": "Additional properties to describe the conversation.",
            "items": {
              "$ref": "#/components/schemas/conversationProperty"
            }
          },
          "subjectOverride": {
            "type": "string",
            "description": "Add a custom subject for the message header.",
            "example": "MS Teams for Green team channel"
          }
        },
        "description": "Meta information to the conversation thread. Can be used for EML header section."
      },
      "conversationEvent": {
        "type": "object",
        "properties": {
          "eventTime": {
            "pattern": "^\\d{1,19}$",
            "type": "integer",
            "description": "Time of the event in epoch milliseconds, must be between the year 1990 and current year + 1",
            "format": "int64",
            "example": 1742900713000
          },
          "eventType": {
            "type": "string",
            "description": "This indicates the type of event that occurred in the conversation",
            "example": "Message",
            "enum": [
              "File_transfer",
              "Invitation",
              "Message",
              "Admin_event",
              "User_joined",
              "User_left",
              "Message_edited",
              "Message_deleted",
              "User_removed",
              "User_event",
              "Reaction",
              "Meeting_event",
              "Context_reply"
            ]
          },
          "childEvents": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/conversationEvent"
            }
          },
          "participants": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/eventUser"
            }
          },
          "content": {
            "$ref": "#/components/schemas/Eventcontent"
          },
          "systemText": {
            "type": "string",
            "description": "Additional system text that was shown to conversation participants.",
            "example": "system text"
          },
          "files": {
            "type": "array",
            "example": {
              "filename": "meeting-video.mp4",
              "fileKey": "/default/example-corp/all-meetings/meeting-video.mp4",
              "isInlined": false,
              "isAvailable": true,
              "transcribable": true
            },
            "items": {
              "$ref": "#/components/schemas/fileInfo"
            }
          }
        },
        "description": "An array of events within a conversation. Items ranging from messages to join/leave events and other actions."
      },
      "eventUser": {
        "required": [
          "corporateEmail",
          "displayName"
        ],
        "type": "object",
        "properties": {
          "displayName": {
            "type": "string",
            "description": "User name",
            "example": "Joe Davies"
          },
          "corporateEmail": {
            "type": "string",
            "description": "User's corporate email",
            "example": "joe.davies@example.com"
          },
          "phone": {
            "type": "string",
            "description": "User's phone number",
            "example": "44123456789"
          },
          "companyName": {
            "type": "string",
            "description": "User's company name",
            "example": "Corp Company"
          },
          "userType": {
            "type": "string",
            "description": "Type of user. If not present then user is assumed to be recipient.",
            "example": "initiator",
            "default": "recipient",
            "enum": [
              "initiator",
              "initiatedOBO",
              "affectedUser",
              "recipient"
            ]
          },
          "identityType": {
            "type": "string",
            "description": "Identity of user",
            "example": "External",
            "default": "Internal",
            "enum": [
              "Internal",
              "External",
              "Bot"
            ]
          }
        }
      },
      "conversationProperty": {
        "required": [
          "name",
          "value"
        ],
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "Property name. Flexible field allowing metadata to be added.",
            "example": "IntID"
          },
          "value": {
            "type": "string",
            "description": "Property value",
            "example": "0-123-456-789"
          },
          "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": "If set to true the key value pair in the properties will not appear within the body of the EML.This property field should coincide with the xheader field set to true.",
            "example": false,
            "default": false
          }
        }
      },
      "Eventcontent": {
        "required": [
          "message"
        ],
        "type": "object",
        "properties": {
          "textType": {
            "type": "string",
            "description": "Text type for the association for the message",
            "example": "plain",
            "enum": [
              "plain",
              "html",
              "markdown"
            ]
          },
          "message": {
            "type": "string",
            "description": "Depending on 'textType', this can be html, plain text or markdown.",
            "example": "plain - What's the weather like? html - <p>What's the weather like?</p>"
          }
        }
      },
      "fileInfo": {
        "required": [
          "fileKey",
          "filename"
        ],
        "type": "object",
        "properties": {
          "filename": {
            "type": "string",
            "description": "Name of the file",
            "example": "file.txt"
          },
          "fileKey": {
            "type": "string",
            "description": "Id/key of the file used to create attachment.Should be the same fileKey as specified when sending to Files endpoint",
            "example": "example-corp/all-meetings/file.txt"
          },
          "fileHref": {
            "type": "string",
            "description": "HREF link to denote the external link to the file on the host provider platform",
            "example": "http://example-corp.s3.amazonaws.com/file.txt"
          },
          "isInlined": {
            "type": "boolean",
            "description": "Defines if attachment should be inlined in the Archived EML body",
            "example": false
          },
          "transcribable": {
            "type": "boolean",
            "description": "Flags video/voice file as requiring transcription downstream, if enabled for feed.",
            "example": true
          }
        }
      },
      "createConversationResponse": {
        "required": [
          "reconciliationId"
        ],
        "type": "object",
        "properties": {
          "reconciliationId": {
            "type": "string",
            "description": "Unique ID assigned by API service for each request which can be used for reconcilliation reporting",
            "nullable": false,
            "example": "c1319852-5367-5958-9aee-98fffdc22493"
          }
        },
        "description": "API responses"
      },
      "createConversationStatusResponse": {
        "required": [
          "reconciliationId",
          "status"
        ],
        "type": "object",
        "properties": {
          "reconciliationId": {
            "type": "string",
            "description": "Unique ID assigned by API service for each request which can be used for reconcilliation reporting",
            "nullable": false,
            "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",
            "nullable": false,
            "example": "duplicate"
          }
        },
        "description": "API responses"
      },
      "errorResponse": {
        "type": "object",
        "properties": {
          "timestamp": {
            "type": "string",
            "format": "date-time"
          },
          "status": {
            "type": "integer",
            "format": "int32"
          },
          "error": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "path": {
            "type": "string"
          }
        }
      }
    },
    "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"
            }
          }
        }
      }
    },
    "securitySchemes": {
      "oAuth2ClientCredentials": {
        "type": "oauth2",
        "description": "This API uses OAuth2 with the client credentials flow.",
        "flows": {
          "clientCredentials": {
            "tokenUrl": "https://iam-oauth2.globalrelay.com/oauth2/token",
            "scopes": {}
          }
        }
      }
    }
  }
}