openapi: 3.2.0 info: title: Auto Compose API description: 'Autocompose API to suggest the next agent message. Suggestions are based on the conversation history, conversation metadata, and the in-progress message text the agent has already typed into the composer.' version: 0.0.3 servers: - url: https://api.sandbox.asapp.com - url: https://api.test.asapp.com tags: - name: AutoCompose description: Improve agent productivity with AutoCompose API x-displayName: AutoCompose paths: /autocompose/v1/conversations/{conversationId}/suggestions: parameters: - $ref: '#/components/parameters/conversationId' post: tags: - AutoCompose operationId: getSuggestions summary: Generate suggestions description: 'Get suggestions for the next agent message in the conversation. There are several times when this should be called: - when an agent joins the conversation, - after a message is sent by either the customer or the agent, - and as the agent is typing in the composer (to enable completing the agent''s in-progress message). Optionally, add a message to the conversation.' requestBody: description: The parameters for getting suggestions for the next agent message. content: application/json: schema: $ref: '#/components/schemas/SuggestionsRequest' responses: '200': description: Successfully fetched suggestions for the conversation content: application/json: schema: $ref: '#/components/schemas/Suggestions' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '413': $ref: '#/components/responses/RequestEntityTooLarge' '422': $ref: '#/components/responses/UnprocessableEntity' '429': $ref: '#/components/responses/TooManyRequests' '503': $ref: '#/components/responses/ServiceUnavailable' default: $ref: '#/components/responses/DefaultError' security: - API-ID: [] API-Secret: [] /autocompose/v1/profanity/evaluation: post: tags: - AutoCompose operationId: getEvaluation summary: Evaluate profanity description: Get an evaluation of a text to verify if it contains profanity, obscenity or other unwanted words. This service should be called before sending a message to prevent the agent from sending profanities in the chat. requestBody: description: The parameters for getting a evaluation result of the text typed by the user. content: application/json: schema: type: object properties: text: description: text to be checked for profanity type: string example: text: This is a perfectly decent sentence. responses: '200': description: Successfully fetched a evaluation result of the sentence. content: application/json: schema: $ref: '#/components/schemas/ProfanityResult' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '413': $ref: '#/components/responses/RequestEntityTooLarge' '422': $ref: '#/components/responses/UnprocessableEntity' '429': $ref: '#/components/responses/TooManyRequests' '503': $ref: '#/components/responses/ServiceUnavailable' default: $ref: '#/components/responses/DefaultError' security: - API-ID: [] API-Secret: [] /autocompose/v1/spellcheck/correction: post: tags: - AutoCompose operationId: getSpellingCorrection summary: Check for spelling mistakes description: 'Get spelling correction for a message as it is being typed, if there is a misspelling. Only the current word will be corrected, once it''s fully typed (so it is recommended to call this endpoint after space characters).' requestBody: description: The parameters for getting a spelling correction as a message is being typed. required: true content: application/json: schema: $ref: '#/components/schemas/SpellcheckQuery' responses: '200': description: Successfully checked for a spelling mistake. content: application/json: schema: $ref: '#/components/schemas/SpellcheckCorrection' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '413': $ref: '#/components/responses/RequestEntityTooLarge' '422': $ref: '#/components/responses/UnprocessableEntity' '429': $ref: '#/components/responses/TooManyRequests' '503': $ref: '#/components/responses/ServiceUnavailable' default: $ref: '#/components/responses/DefaultError' security: - API-ID: [] API-Secret: [] /autocompose/v1/analytics/message-sent: post: tags: - AutoCompose operationId: createMessageSentEvent summary: Create a MessageSent analytics event description: 'Create a MessageSent analytics event describing the agent''s usage of AutoCompose augmentation features while composing a message' requestBody: description: The parameters for creating a MessageSent event content: application/json: schema: $ref: '#/components/schemas/MessageSentEvent' responses: '200': description: Successfully created a MessageSent event content: {} '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '413': $ref: '#/components/responses/RequestEntityTooLarge' '422': $ref: '#/components/responses/UnprocessableEntity' '429': $ref: '#/components/responses/TooManyRequests' '503': $ref: '#/components/responses/ServiceUnavailable' default: $ref: '#/components/responses/DefaultError' security: - API-ID: [] API-Secret: [] /autocompose/v1/conversations/{conversationId}/message-analytic-events: parameters: - $ref: '#/components/parameters/conversationId' post: tags: - AutoCompose operationId: createMessageAnalyticEvent summary: Create a message analytic event description: 'To improve the performance of ASAPP suggestions, provide information about the actions performed by the agent while composing a message by creating `message-analytic-events`. These analytic events indicate which AutoCompose functionality was used or not. This information along with the conversation itself is used to optimize our models, resulting in better results for the agents. We track the following types of message analytic events: - suggestion-1-inserted: The agent selected the first of the `suggestions` from a `Suggestion` API response. - suggestion-2-inserted: The agent selected the second of the `suggestions` from a `Suggestion` API response. - suggestion-3-inserted: The agent selected the third of the `suggestions` from a `Suggestion` API response. - phrase-completion-accepted: The agent selected the `phraseCompletion` from a `Suggestion` API response. - spellcheck-applied: A correction provided in a `SpellcheckCorrection` API response was applied automatically. - spellcheck-undone: A correction provided in a `SpellcheckCorrection` API response was undone by clicking the undo button. - custom-response-drawer-inserted: The agent inserted one of their custom responses from the custom response drawer. - custom-panel-inserted: The agent inserted a response from their custom response list in the custom response panel. - global-panel-inserted: The agent inserted a response from the global response list in the global response panel. Some of the event types have a corresponding event object to provide details.' requestBody: description: The parameters for reporting the analytic event content: application/json: schema: $ref: '#/components/schemas/MessageAnalyticEvent' examples: Create a suggestion-inserted event.: value: type: suggestion-1-inserted suggestionsId: 4d2fd982640c311394008259594399a1 Create a spellcheck-applied event.: value: type: spellcheck-applied suggestionsId: 4d2fd982640c311394008259594399a1 spellcheckApplied: correctionId: 75bc8912c66842594375bc8912c66842 Create a spellcheck-undone event.: value: type: spellcheck-undone suggestionsId: 4d2fd982640c311394008259594399a1 spellcheckUndone: correctionId: 75bc8912c66842594375bc8912c66842 Create a custom-response-drawer-inserted event.: value: type: custom-response-drawer-inserted suggestionsId: 4d2fd982640c311394008259594399a1 customResponseDrawerInserted: query: Hi text: Hi, I'm Alice. How can I help you today? Create a custom-panel-inserted event.: value: type: custom-panel-inserted suggestionsId: 4d2fd982640c311394008259594399a1 customPanelInserted: text: Hi, I'm Alice. How can I help you today? Create a global-panel-inserted event.: value: type: global-panel-inserted suggestionsId: 4d2fd982640c311394008259594399a1 globalPanelInserted: text: How can I help you today? responses: '200': description: Successfully reported selected suggestion content: {} '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '413': $ref: '#/components/responses/RequestEntityTooLarge' '422': $ref: '#/components/responses/UnprocessableEntity' '429': $ref: '#/components/responses/TooManyRequests' '503': $ref: '#/components/responses/ServiceUnavailable' default: $ref: '#/components/responses/DefaultError' security: - API-ID: [] API-Secret: [] /autocompose/v1/settings: parameters: - $ref: '#/components/parameters/agentId' get: tags: - AutoCompose operationId: getSettings summary: Get settings for AutoCompose clients description: 'Get settings for AutoCompose clients, such as whether any features should not be used. It may be desirable to disable some features in high-latency scenarios.' responses: '200': description: Settings for AutoCompose clients content: application/json: schema: $ref: '#/components/schemas/Settings' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '413': $ref: '#/components/responses/RequestEntityTooLarge' '422': $ref: '#/components/responses/UnprocessableEntity' '429': $ref: '#/components/responses/TooManyRequests' '503': $ref: '#/components/responses/ServiceUnavailable' default: $ref: '#/components/responses/DefaultError' security: - API-ID: [] API-Secret: [] /autocompose/v1/responses/globals: get: tags: - AutoCompose summary: List the global responses description: Get the global responses and folder organization for a company. Responses are sorted by text, and folders are sorted by name. operationId: getGlobalResponses parameters: - in: query name: folderId schema: type: string required: false description: Optional identifier for the ID of the folder containing responses to be retrieved. If this is omitted, all global responses are returned. Data format is expected to be UUID. The special value '__root' can also be used to retrieve top level folders/responses. - in: query name: resourceType schema: type: string enum: - folders - responses - all default: all required: false description: Optional identifier for the ID of the type of responses to be retrieved. A value of 'folders' will return only folder information describing the way responses are organized. A value of 'responses' will return only responses. A value of 'all' will return a mix of folders and responses. Note that if the folderId parameter is specified as well, only the resource type identified here that exists within the specified folder will be returned. If this is omitted, all resources are returned. - in: query name: searchTerm schema: type: string required: false description: Search term to search for global responses. This will search for matching folder names, response text or both, depending on the resourceType parameter value. example: greetings - in: query name: pageToken description: This service responds with a set of global responses. These are divided into pages, with maxPerPage items in each page. This parameter is the page token returned in the call prior to this one. If this is the first call being made, this field should be omitted. The server will respond with global responses following the one previously sent. required: false schema: type: string example: '3' - in: query name: maxPerPage description: The maximum number of custom responses the client can handle within one page required: false schema: type: integer default: 1000 responses: '200': description: The global responses for this company content: application/json: schema: $ref: '#/components/schemas/GlobalResponsesWithVersion' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '413': $ref: '#/components/responses/RequestEntityTooLarge' '422': $ref: '#/components/responses/UnprocessableEntity' '429': $ref: '#/components/responses/TooManyRequests' '503': $ref: '#/components/responses/ServiceUnavailable' default: $ref: '#/components/responses/DefaultError' security: - API-ID: [] API-Secret: [] /autocompose/v1/responses/customs: parameters: - $ref: '#/components/parameters/agentId' get: tags: - AutoCompose summary: Get custom responses description: Get custom responses for an agent. Responses are sorted by title, and folders are sorted by name. operationId: getCustomResponseCollection parameters: - in: query name: folderId schema: type: string required: false description: Optional identifier for the ID of the folder containing responses to be retrieved. If this is omitted, all custom responses are returned. Data format is expected to be UUID. The special value '__root' can also be used to retrieve top level folders/responses. - in: query name: resourceType schema: type: string enum: - folders - responses - all default: all required: false description: Optional identifier for the ID of the type of responses to be retrieved. A value of 'folders' will return only folder information describing the way responses are organized. A value of 'responses' will return only responses. A value of 'all' will return a mix of folders and responses. Note that if the folderId parameter is specified as well, only the resource type identified here that exists within the specified folder will be returned. If this is omitted, all resources are returned. - in: query name: searchTerm schema: type: string required: false description: Search term to search for custom responses. This will search for matching folder names, response text or both, depending on the resourceType parameter value. example: greetings - in: query name: pageToken description: This service responds with a set of custom responses. These are divided into pages, with maxPerPage items in each page. This parameter is the page token returned in the call prior to this one. If this is the first call being made, this field should be omitted. The server will respond with custom responses following the one previously sent. required: false schema: type: string example: '3' - in: query name: maxPerPage description: The maximum number of custom responses the client can handle within one page required: false schema: type: integer default: 1000 responses: '200': description: A collection of custom response lists for this customer, sorted by agent ID content: application/json: schema: $ref: '#/components/schemas/Responses' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '413': $ref: '#/components/responses/RequestEntityTooLarge' '422': $ref: '#/components/responses/UnprocessableEntity' '429': $ref: '#/components/responses/TooManyRequests' '503': $ref: '#/components/responses/ServiceUnavailable' default: $ref: '#/components/responses/DefaultError' security: - API-ID: [] API-Secret: [] /autocompose/v1/responses/customs/folder: parameters: - $ref: '#/components/parameters/agentId' post: tags: - AutoCompose summary: Create a response folder description: Add a single folder for an agent operationId: addCustomResponseFolder requestBody: description: The folder to be added content: application/json: schema: $ref: '#/components/schemas/Folder' required: true responses: '200': description: Acknowledgement that the folder was successfully added content: application/json: schema: $ref: '#/components/schemas/Folder' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '413': $ref: '#/components/responses/RequestEntityTooLarge' '422': $ref: '#/components/responses/UnprocessableEntity' '429': $ref: '#/components/responses/TooManyRequests' '503': $ref: '#/components/responses/ServiceUnavailable' default: $ref: '#/components/responses/DefaultError' security: - API-ID: [] API-Secret: [] /autocompose/v1/responses/customs/response: parameters: - $ref: '#/components/parameters/agentId' post: tags: - AutoCompose summary: Create a custom response description: Add a single custom response for an agent operationId: addCustomResponse requestBody: description: The custom response to be added content: application/json: schema: $ref: '#/components/schemas/NewCustomResponse' required: true responses: '200': description: Acknowledgement that the response was successfully added content: application/json: schema: $ref: '#/components/schemas/Response' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '413': $ref: '#/components/responses/RequestEntityTooLarge' '422': $ref: '#/components/responses/UnprocessableEntity' '429': $ref: '#/components/responses/TooManyRequests' '503': $ref: '#/components/responses/ServiceUnavailable' default: $ref: '#/components/responses/DefaultError' security: - API-ID: [] API-Secret: [] /autocompose/v1/responses/customs/response/{responseId}: parameters: - $ref: '#/components/parameters/agentId' - $ref: '#/components/parameters/responseId' put: tags: - AutoCompose summary: Update a custom response description: Update a specific custom response for an agent operationId: updateCustomResponse requestBody: description: The custom response to be updated content: application/json: schema: $ref: '#/components/schemas/NewCustomResponse' required: true responses: '200': description: Acknowledgement that the custom response was successfully updated content: {} '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '413': $ref: '#/components/responses/RequestEntityTooLarge' '422': $ref: '#/components/responses/UnprocessableEntity' '429': $ref: '#/components/responses/TooManyRequests' '503': $ref: '#/components/responses/ServiceUnavailable' default: $ref: '#/components/responses/DefaultError' security: - API-ID: [] API-Secret: [] delete: tags: - AutoCompose summary: Delete a custom response description: Delete a specific custom response for an agent operationId: deleteCustomResponse responses: '200': description: Acknowledgement that the custom response was successfully deleted content: {} '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '413': $ref: '#/components/responses/RequestEntityTooLarge' '422': $ref: '#/components/responses/UnprocessableEntity' '429': $ref: '#/components/responses/TooManyRequests' '503': $ref: '#/components/responses/ServiceUnavailable' default: $ref: '#/components/responses/DefaultError' security: - API-ID: [] API-Secret: [] /autocompose/v1/responses/customs/folder/{folderId}: parameters: - $ref: '#/components/parameters/agentId' - $ref: '#/components/parameters/folderId' put: tags: - AutoCompose summary: Update a response folder description: Update a folder for an agent operationId: updateFolder requestBody: description: The folder to be updated content: application/json: schema: $ref: '#/components/schemas/Folder' required: true responses: '200': description: Acknowledgement that the folder was successfully updated content: {} '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '413': $ref: '#/components/responses/RequestEntityTooLarge' '422': $ref: '#/components/responses/UnprocessableEntity' '429': $ref: '#/components/responses/TooManyRequests' '503': $ref: '#/components/responses/ServiceUnavailable' default: $ref: '#/components/responses/DefaultError' security: - API-ID: [] API-Secret: [] delete: tags: - AutoCompose summary: Delete a response folder description: Delete a folder for an agent operationId: deleteFolder responses: '200': description: Acknowledgement that the custom response was successfully deleted content: {} '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '413': $ref: '#/components/responses/RequestEntityTooLarge' '422': $ref: '#/components/responses/UnprocessableEntity' '429': $ref: '#/components/responses/TooManyRequests' '503': $ref: '#/components/responses/ServiceUnavailable' default: $ref: '#/components/responses/DefaultError' security: - API-ID: [] API-Secret: [] /autocompose/v1/autopilot/greetings: parameters: - $ref: '#/components/parameters/agentId' get: tags: - AutoCompose summary: Get autopilot greetings description: Get autopilot greetings for an agent operationId: getAutopilotGreetings responses: '200': description: The autopilot greetings for this agent content: application/json: schema: $ref: '#/components/schemas/AutopilotGreeting' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '413': $ref: '#/components/responses/RequestEntityTooLarge' '422': $ref: '#/components/responses/UnprocessableEntity' '429': $ref: '#/components/responses/TooManyRequests' '503': $ref: '#/components/responses/ServiceUnavailable' default: $ref: '#/components/responses/DefaultError' security: - API-ID: [] API-Secret: [] put: tags: - AutoCompose summary: Update autopilot greetings description: Update autopilot greetings for an agent operationId: updateAutopilotGreetings requestBody: description: The updated autopilot greetings content: application/json: schema: $ref: '#/components/schemas/AutopilotGreeting' required: true responses: '200': description: Acknowledgement that the greetings were successfully updated content: application/json: schema: $ref: '#/components/schemas/AutopilotGreeting' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '413': $ref: '#/components/responses/RequestEntityTooLarge' '422': $ref: '#/components/responses/UnprocessableEntity' '429': $ref: '#/components/responses/TooManyRequests' '503': $ref: '#/components/responses/ServiceUnavailable' default: $ref: '#/components/responses/DefaultError' security: - API-ID: [] API-Secret: [] /autocompose/v1/autopilot/greetings/status: parameters: - $ref: '#/components/parameters/agentId' get: tags: - AutoCompose summary: Get autopilot greetings status description: Get autopilot greetings status for an agent operationId: getAutopilotGreetingsStatus responses: '200': description: The autopilot greetings status for this agent content: application/json: schema: $ref: '#/components/schemas/AutopilotStatus' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '413': $ref: '#/components/responses/RequestEntityTooLarge' '422': $ref: '#/components/responses/UnprocessableEntity' '429': $ref: '#/components/responses/TooManyRequests' '503': $ref: '#/components/responses/ServiceUnavailable' default: $ref: '#/components/responses/DefaultError' security: - API-ID: [] API-Secret: [] put: tags: - AutoCompose summary: Update autopilot greetings status description: Update autopilot greetings status for an agent operationId: updateAutopilotGreetingsStatus requestBody: description: The updated autopilot greetings status content: application/json: schema: $ref: '#/components/schemas/AutopilotStatus' required: true responses: '200': description: Acknowledgement that the greetings status was successfully updated content: application/json: schema: $ref: '#/components/schemas/AutopilotStatus' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '413': $ref: '#/components/responses/RequestEntityTooLarge' '422': $ref: '#/components/responses/UnprocessableEntity' '429': $ref: '#/components/responses/TooManyRequests' '503': $ref: '#/components/responses/ServiceUnavailable' default: $ref: '#/components/responses/DefaultError' security: - API-ID: [] API-Secret: [] components: schemas: PhraseCompletion: description: Completion of the phrase the agent is currently typing, to be displayed inline in the composer type: object properties: text: type: string description: Phrase completion text for the agent (this may be empty if the model does not have a confident prediction for how to complete the message) example: Hello, how can I help you? AutopilotGreeting: type: object description: Autopilot greetings for an agent properties: greetingGeneric: type: string description: Generic greeting, without any template data greetingCustomerName: type: string description: Greeting with template for customer name required: - greetingGeneric - greetingCustomerName example: greetingGeneric: Welcome! greetingCustomerName: Welcome {NAME}! MessageSentEvent: description: 'Analytics event describing the agent''s usage of AutoCompose features while composing a message (we sometimes refer to these as augmentation features, because they augment the agent''s work). Note that many of the fields are not technically required according to this spec. This does not mean that they can omitted arbitrarily. They should all be set, when they relevant for AutoCompose features a particular ASAPP customer is using and the data is available. For some use cases, some fields are not relevant (for example, phraseAutocompletePresentedCt is only relevant if phrase completions are being used). In other cases, the field may relevant but the data might not be avaialble (for example, if the request for suggestions returns too late, it might not be possible set initialSuggestionsId). The customer should try to fill in all relevant fields when they can; this information enables ASAPP to report on the performance of our features and to improve their perforamnce over time. When a field is omitted, it will take on a default value in the event data. String fields default to empty string and numeric fields default to 0.' type: object required: - conversationId - messageId - augmentationType example: conversationId: 01G1167H5FFQ47SMSRYGKBW7HM messageId: 01BX5ZZKBKACTAV9WEVGEMMVS1 augmentationType: - AUTOSUGGEST properties: conversationId: description: The ASAPP conversation id for the conversation. type: string example: 01G1167H5FFQ47SMSRYGKBW7HM messageId: description: 'The ASAPP ID of the message that was sent. This is required for every event, to enable correlating the analytics event with the message that was sent. ' type: string example: 01BX5ZZKBKACTAV9WEVGEMMVS1 augmentationType: description: 'Types of AutoCompose augmentation features used for composing the message. Ordering of augmentations and repeated uses of an augmentation type are preserved. This is required, so that the usage of AutoCompose features can be measured. ' type: array items: type: string enum: - FREEHAND - AUTOSUGGEST - AUTOCOMPLETE - PHRASE_AUTOCOMPLETE - CUSTOM_DRAWER - CUSTOM_INSERT - GLOBAL_INSERT - FLUENCY_APPLY - FLUENCY_UNDO example: - AUTOSUGGEST - PHRASE_AUTOCOMPLETE - FLUENCY_APPLY numEdits: description: 'Number of keystrokes of editing the agent did after selecting a full-message suggestions (one of the suggestions in the suggestions array, not phraseCompletion). Selecting a full-message suggestion resets the counter. Accepting a phrase completion by hitting tab or right arrow increments the counter just like other keystrokes. The idea is to have a rough idea of how much editing the agent had to do after selecting a full-message suggestion (in the ideal case, the message was satisfactory to send as-is and numEdits equals 0). ' type: integer example: 2 selectedSuggestionText: description: 'If the agent used a full-message suggestion to compose this message, this is the text of the suggestion ' type: string example: How can I help you today? selectedSuggestionsId: description: 'If the agent used a full-message suggestion to compose this message, this is the ID of the set of suggestions that the suggestion came from. This helps ASAPP assoicate the MessageSent event with events emitted by AutoCompose internally. If the agent did not use a full-message suggestion, this field can left blank. ' type: string example: 4d2fd982640c311394008259594399a1 selectedSuggestionIndex: description: 'If the agent used a full-message suggestion to compose this message, this is the index of the selected suggestion in the set of suggestions that the agent used, starting from 1 for the top suggestion, 2 for the second from the top, and so on. This should be omitted if no suggestion was selected, but it is required if the agent selected a suggestion, to enable identifying which of the suggestions was used. ' type: integer example: 1 initialSuggestionsId: description: 'The ID for the first set of suggestions the agent saw while composing this message. This is required for every event, if suggestions were shown to the agent. If for some reason suggestions were not available, it can be omitted. ' type: string example: 5e9491b203e6ecccfef964e26fb1a5d3 timeToAction: description: "Number of seconds between the agent sending their previous\nmessage and their first action for composing this message.\nAn agent action is when one of the following occur:\n - Typing in the composer\n - Selecting a suggestion\n - Using a phrase completion\n - Inserting a custom or global response from the library\n - Pasting a text into the composer\n" type: number example: 1.891412 craftingTime: description: 'Number of seconds between the agent''s first action and last action for composing this message. ' type: number example: 10.9472 dwellTime: description: 'Number of seconds between the agent''s last action for composing this message and the message being sent. ' type: number example: 4.132985 phraseAutocompletePresentedCt: description: 'Number of phrase autocomplete suggestions presented to the agent. ' type: integer example: 3 phraseAutocompleteSelectedCt: description: 'Number of phrase autocomplete suggestions selected by the agent. ' type: integer example: 1 ConflictResponse: description: Conflict response type: object properties: error: $ref: '#/components/schemas/DefaultErrorDetails' example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 409-01 message: Conflict Responses: type: object description: A set of responses and folders for an agent properties: responsesList: type: array description: the list of responses with their associated metadata items: $ref: '#/components/schemas/Response' folderList: type: array description: the list of folders items: $ref: '#/components/schemas/Folder' pageToken: type: string description: the token to the next page if there is one, otherwise empty AutopilotMessage: description: Recommended message for the agent to autopilot send. type: object properties: text: type: string description: Text of the message example: Hello John, how can I help you? templateText: type: string description: Text of the message with placeholders for metadata instead of the values filled in example: Hello {NAME}, how can I help you? title: type: string description: The title of the message example: Greeting delaySeconds: type: integer description: Delay before the message is sent to the customer, during which a preview of the message is shown to the agent and they can choose to cancel it example: 5 triggerAfterSeconds: type: integer description: Delay before showing the preview and starting the countdown to send the message example: 0 SpellcheckCorrection: type: object properties: id: description: ID for the spelling correction that was returned (to be used in analytics events) type: string example: 01BX5ZZKBKACTAV9WEVGEMMVS1 misspelledText: description: misspelling that needs to be replaced with the corrected text type: string example: tihs correctedText: type: string description: correction for the misspelling example: this position: type: integer description: position where the misspelling starts example: 7 Settings: type: object properties: suggestionsWhileTypingDisabled: type: boolean description: if true, suggestions endpoint should not be called while agent is typing phraseCompletionsDisabled: type: boolean description: if true, phraseCompletion from suggestions endpoint should not be shown to the agent spellcheckDisabled: type: boolean description: if true, spelling corrections endpoint should not be called while agent is typing autopilotGreetingsDisabled: type: boolean description: if true, autopilot greetings should not be available for configuration autocomposeDisabled: type: boolean description: 'if true, all AutoCompose features should be disabled (regardless of the other settings); this is intended for use in A/B tests in which a control group of agents is not exposed to AutoCompose ' SuggestionsRequest: description: A suggestions request with an optional message to add to the conversation type: object properties: query: description: text the agent has already entered into the composer type: string message: $ref: '#/components/schemas/Message' example: query: Hello, how can message: text: Hello, I would like to upgrade my internet plan to GOLD. sender: role: customer externalId: customer-x timestamp: '2023-06-01T19:16:55.706Z' TooManyRequestsResponse: description: Too Many Requests response type: object properties: error: $ref: '#/components/schemas/DefaultErrorDetails' example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 429-01 message: Too Many Requests Suggestion: description: Suggestion type: object properties: text: type: string description: Suggestion text for the agent example: Hello John, how can I help you? templateText: type: string description: Suggestion text with placeholders for metadata instead of the values filled in example: Hello {NAME}, how can I help you? title: type: string description: The title of the response example: Greeting MessageAnalyticEvent: description: 'Analytics event reporting actions the agent performed while composing a message. ' type: object required: - type - suggestionsId example: type: suggestion-1-inserted suggestionsId: 4d2fd982640c311394008259594399a1 properties: type: type: string example: suggestion-1-inserted enum: - suggestion-1-inserted - suggestion-2-inserted - suggestion-3-inserted - phrase-completion-accepted - spellcheck-applied - spellcheck-undone - custom-response-drawer-inserted - custom-panel-inserted - global-panel-inserted description: 'The type of message analytic event. ' suggestionsId: description: 'For suggestion-1-inserted, suggestion-2-inserted, suggestion-3-inserted, phrase-completion-accepted, this is the `id` from the Suggestions API response that the agent interacted with. This allows ASAPP to connect the event with additional information (e.g., the text of the suggestion that was inserted). For spellcheck-undone, custom-response-drawer-inserted, custom-panel-inserted, and global-panel-inserted, this is the `id` of the most recent Suggestions API response in this conversation. In all of these cases, providing the Suggestions `id` allows ASAPP to associate the event with the message the agent is composing. During the normal flow of using the AutoCompose API, the Suggestions API will always have been called at least once since the previous agent message by the time a message analytic event occurs, and each time the Suggestions API is called, ASAPP records the ID of the previous agent message. Thus, the Suggestions `id` in the analytic event links back to the previous agent message. This permits the analytic event to later be linked to the new message the agent is composing, even though the event occurs before the message is sent. ' type: string example: 4d2fd982640c311394008259594399a1 spellcheckApplied: type: - object - 'null' description: 'The details about the spellcheck applied analytic event ' properties: correctionId: description: The ID of the spellcheck correction API response type: string example: 75bc8912c66842594375bc8912c66842 required: - correctionId spellcheckUndone: type: - object - 'null' description: 'The details about the spellcheck undone analytic event ' properties: correctionId: description: The ID of the spellcheck correction API response type: string example: 75bc8912c66842594375bc8912c66842 required: - correctionId customResponseDrawerInserted: type: - object - 'null' description: The details about the custom response drawer inserted analytic event properties: query: description: 'The query the agent typed to search in the custom response drawer ' type: string example: Hi text: description: 'The text of the custom response the agent inserted from the custom response drawer ' type: string example: Hi, I'm Alice. How can I help you today? required: - query - text customPanelInserted: type: - object - 'null' description: The details about the custom panel inserted analytic event properties: text: description: 'The text of the custom response the agent inserted using the custom response panel ' type: string example: Hi, I'm Alice. How can I help you today? required: - text globalPanelInserted: type: - object - 'null' description: The details about the global panel inserted analytic event properties: text: description: 'The text of the custom response the agent inserted using the global response panel ' type: string example: How can I help you today? required: - text UnprocessableEntity: description: Unprocessable Entity response type: object properties: error: $ref: '#/components/schemas/DefaultErrorDetails' example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 422-01 message: Unprocessable Entity ProfanityResult: description: ProfanityResult type: object properties: hasProfanity: description: A boolean value describing if the text contains a curse word. type: boolean example: false Message: description: Represents a single message within a conversation. type: object properties: text: type: string minLength: 1 description: The content of the message. sender: $ref: '#/components/schemas/Participant' description: Information about the participant who sent the message. timestamp: type: string format: date-time description: The time when the message was sent. Include the timezone, otherwise UTC will be assumed. required: - text - sender - timestamp example: text: Hello, I would like to upgrade my internet plan to GOLD. sender: role: agent externalId: 123 timestamp: '2021-11-23T12:13:14.555Z' BadRequestResponse: description: Bad request response type: object properties: error: $ref: '#/components/schemas/DefaultErrorDetails' example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 400-01 message: Bad request NotFoundResponse: description: Not Found response type: object properties: error: $ref: '#/components/schemas/DefaultErrorDetails' example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 404-01 message: Not Found DefaultErrorResponse: description: Default error response type: object properties: error: $ref: '#/components/schemas/DefaultErrorDetails' example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 500-01 message: Internal server error RequestEntityTooLargeResponse: description: Request Entity Too Large response type: object properties: error: $ref: '#/components/schemas/DefaultErrorDetails' example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 413-01 message: Request Entity Too Large Folder: type: object description: A folder of responses properties: id: type: string description: The ID of the folder readOnly: true parentFolderId: type: string description: The ID of the parent folder. name: type: string description: the name of the folder required: - name example: id: '123' parentFolderId: '456' name: folder name MessagesResponse: description: Response for messages type: object properties: id: type: string description: Message ID to be used for analytics example: id: 01BX5ZZKBKACTAV9WEVGEMMVS1 GlobalResponsesVersion: type: object properties: id: type: string description: The ID of this version of the global responses readOnly: true description: type: string description: A human-readable description of the version ParticipantRole: description: 'A participant role, usually the customer or an agent for human participants. System participant is also allowed but keep in mind that this role won''t be considered a participant in a conversation, just a message sender. ' type: string enum: - agent - customer - system ServiceUnavailableResponse: description: Service Unavailable response type: object properties: error: $ref: '#/components/schemas/DefaultErrorDetails' example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 503-01 message: Service Unavailable Response: type: object properties: id: type: string description: The ID of this response, data format is UUID readOnly: true text: type: string description: The text of the response title: type: string description: The title of the response. Always non-empty for custom responses, but may be empty for other types of responses (global and organic). folderId: type: string description: the ID of the folder the response belongs to. metadata: type: array items: type: object properties: name: type: string description: the name of this metadata item allowedValues: type: array items: type: string description: the list of allowed values for this metadata item description: free-form metadata, in the form of a map of keys to lists of allowed values for each key, that can be added to any response. At least one of the values in the list for each key included here must match what gets sent when requesting suggestions, so that responses can be filtered appropriately. NewCustomResponse: type: object properties: text: type: string description: The text of the response title: type: string description: The title of the response folderId: type: string description: the ID of the folder the response belongs to (used for custom responses). metadata: type: array items: type: object properties: name: type: string description: the name of this metadata item allowedValues: type: array items: type: string description: the list of allowed values for this metadata item description: free-form metadata, in the form of a map of keys to lists of allowed values for each key, that can be added to any response. At least one of the values in the list for each key included here must match what gets sent when requesting suggestions, so that responses can be filtered appropriately. required: - text - title example: text: fold text title: folder title folderId: '123' Suggestions: description: Suggestions for next agent message type: object properties: id: description: ID for the suggestions that were returned (to be used in analytics events) type: string message: $ref: '#/components/schemas/MessagesResponse' suggestions: type: array items: $ref: '#/components/schemas/Suggestion' phraseCompletion: $ref: '#/components/schemas/PhraseCompletion' autopilotMessage: $ref: '#/components/schemas/AutopilotMessage' Participant: description: Represents a participant in the conversation. type: object properties: role: $ref: '#/components/schemas/ParticipantRole' description: The role of the participant in the conversation. externalId: type: string description: The unique identifier for the participant in your external system. This should be consistent across all interactions for the same individual. required: - role - externalId AutopilotStatus: type: object description: Autopilot status for an agent properties: enabled: type: boolean description: If true, autopilot is enabled required: - enabled example: enabled: true GlobalResponsesWithVersion: type: object properties: responses: $ref: '#/components/schemas/Responses' version: $ref: '#/components/schemas/GlobalResponsesVersion' UnauthorizedResponse: description: Unauthorized response type: object properties: error: $ref: '#/components/schemas/DefaultErrorDetails' example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 401-01 message: Unauthorized SpellcheckQuery: type: object properties: text: description: text being typed by the agent, already entered into the composer type: string typingEvent: type: object properties: cursorStart: description: position of the cursor before the typing event, to identify if a word is being typed type: integer cursorEnd: description: position of the cursor after the typing event, to identify if a word is being typed type: integer required: - cursorStart - cursorEnd userDictionary: description: Words that should not be corrected if they are present on the text type: array items: type: string required: - text - typingEvent example: text: 'How is tihs ' typingEvent: cursorStart: 11 cursorEnd: 12 userDictionary: - Hellooo ForbiddenResponse: description: Forbidden response type: object properties: error: $ref: '#/components/schemas/DefaultErrorDetails' example: requestId: 8e033668-9f1a-11ec-b909-0242ac120002 code: 403-01 message: Forbidden Response DefaultErrorDetails: description: Error details type: object properties: requestId: type: string description: Unique ID of the failing request message: type: string description: Error message code: type: string description: Error code required: - requestId - message responses: ServiceUnavailable: description: 503 - Service Unavailable content: application/json: schema: $ref: '#/components/schemas/ServiceUnavailableResponse' DefaultError: description: 500 - Internal Server Error content: application/json: schema: $ref: '#/components/schemas/DefaultErrorResponse' Unauthorized: description: 401 - Unauthorized content: application/json: schema: $ref: '#/components/schemas/UnauthorizedResponse' BadRequest: description: 400 - Bad request content: application/json: schema: $ref: '#/components/schemas/BadRequestResponse' Forbidden: description: 403 - Forbidden content: application/json: schema: $ref: '#/components/schemas/ForbiddenResponse' Conflict: description: 409 - Conflict content: application/json: schema: $ref: '#/components/schemas/ConflictResponse' RequestEntityTooLarge: description: 413 - Request Entity Too Large content: application/json: schema: $ref: '#/components/schemas/RequestEntityTooLargeResponse' TooManyRequests: description: 429 - Too Many Requests content: application/json: schema: $ref: '#/components/schemas/TooManyRequestsResponse' UnprocessableEntity: description: 422 - Unprocessable Entity content: application/json: schema: $ref: '#/components/schemas/UnprocessableEntity' NotFound: description: 404 - Not Found content: application/json: schema: $ref: '#/components/schemas/NotFoundResponse' parameters: responseId: name: responseId description: Identifier of the response, data format is expected to be UUID in: path required: true schema: type: string conversationId: name: conversationId description: The identifier for a conversation. in: path required: true schema: type: string pattern: ^[A-Z0-9]+$ agentId: name: agentId description: Identifier of the agent, data format is expected to be UUID in: query required: true schema: type: string folderId: name: folderId description: Identifier of the folder, data format is expected to be UUID in: path required: true schema: type: string securitySchemes: API-ID: type: apiKey in: header name: asapp-api-id API-Secret: type: apiKey in: header name: asapp-api-secret x-tagGroups: - name: AutoCompose API tags: - AutoCompose - name: AutoSummary API tags: - AutoSummary - name: AutoTranscribe API tags: - AutoTranscribe - name: Conversations API tags: - Conversations - name: File Exporter API tags: - File Exporter - name: GenerativeAgent API tags: - GenerativeAgent - name: Health Check API tags: - Health Check - name: Knowledge Base API tags: - Knowledge Base - name: Metadata Ingestion API tags: - Metadata - name: MG Autotranscribe API Router tags: - AutoTranscribe Media Gateway x-provenance: method: harvested publisher: Asapp3 source: https://docs.asapp.com/api-specs/openapi.yaml note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json); stamped by stamp-openapi-provenance.py (roadmap#793)