Deploying AutoCompose API

ASAPP AutoCompose has the following technical components:

• An autosuggest model that ASAPP retrains weekly with agent usage data you provide through the /analytics/message-sent endpoint
• Data storage for historical conversations, global response lists and agent historical feature usage that are used for weekly retraining
• The Conversation API for creating and updating conversation data and the AutoCompose API that interfaces with the application with which agents interact and receives agent usage data in the form of message analytics events

​

Setup

ASAPP provides an AI Services Developer Portal. Within the portal, developers can do the following:

• Access relevant API documentation (e.g. OpenAPI reference schemas)
• Access API keys for authorization
• Manage user accounts and apps

In order to use ASAPP’s APIs, all apps must be registered through the portal. Once registered, each app will be provided unique API keys for ongoing use.

​

Usage

ASAPP AutoCompose exposes API endpoints that each enable distinct features in the course of an agent’s message composition workflow. Requests should be sent to each endpoint based on events in the conversation and actions taken by the agent in their interface.

For example, the sequence below shows requests made for a typical new conversation in which the agent begins creating their first message, sends the first message and receives one message in return from an end-customer:

In this example:

The Endpoints section below outlines how to use each endpoint.

​

Endpoints Listing

Use the links below to skip to information about the relevant fields and parameters for the corresponding endpoint(s):

Conversations

• POST /conversation/v1/conversations
• POST /conversation/v1/conversations/\{conversationId\}/messages

Requesting Suggestions

• POST /autocompose/v1/conversations/\{conversationId\}/suggestions

Checking Profanity & Spelling

• POST /autocompose/v1/profanity/evaluation
• POST /autocompose/v1/spellcheck/correction

Sending Agent Usage Data

• POST /autocompose/v1/analytics/message-sent

Getting Response Lists

• GET /autocompose/v1/responses/globals
• GET /autocompose/v1/responses/customs

Updating Custom Response Lists

• POST /autocompose/v1/responses/customs/response
• PUT /autocompose/v1/responses/customs/response/\{responseId\}
• DELETE /autocompose/v1/responses/customs/response/\{responseId\}
• POST /autocompose/v1/responses/customs/folder
• PUT /autocompose/v1/responses/customs/folder/\{folderId\}
• DELETE /autocompose/v1/responses/customs/folder/\{folderId\}

​

Conversations API

ASAPP receives conversations through POST requests to the Conversations API. This service creates a record of conversations referenced as a source of truth by all ASAPP services.

By promptly sending conversation and message data to this API, you ensure that ASAPP’s conversation records match your own and that ASAPP services use the most current information available.

POST /conversation/v1/conversations

Use this endpoint to create a new conversation record or update an existing conversation record.

When to Call

This service should be called when a conversation starts or when something about the conversation changes (e.g. a conversation is reassigned to a different agent).

Request Details

Requests must include a conversation identifier from your system of record (external to ASAPP) and a timestamp (formatted in RFC3339 micro second date-time expressed in UTC) for when the conversation started.

Requests to create a conversation record must also include identifying information about the human participants. Two types of requests are supported to create a new conversation:

1. Conversations started with an agent: Provide both the agent and customer objects in the request when the conversation begins.
2. Conversations started with a virtual agent: Provide only the customer object in the initial request when the conversation with the virtual agent begins; you must send a subsequent request that includes both the agent and customer objects once the agent joins the conversation.

Requests may also include key-value pair metadata for the conversation that can be used either (1) to insert values into templated responses for agents or (2) as filter criteria to determine whether a conversation is eligible for specific response suggestions.

Response Details

When successful, this endpoint responds with a unique ASAPP identifier (id) for the conversation. This identifier should be used whenever referencing this conversation in the future. For example, adding new messages to this conversation record will require use of this identifier so that ASAPP knows to which conversation messages should be added.

POST /conversation/v1/conversations/\{conversationId\}/messages

Use this endpoint to add a message to an existing conversation record.

When to Call

This service should be called after each sent message by a participant in the conversation.

Request Details

The path parameter for this request is the unique ASAPP conversation ID that was provided in the response body when the conversation record was initially created. Requests must include the message’s text and the message’s sent timestamp (formatted in RFC3339 micro second date-time expressed in UTC). Requests must also include identifying information about the sender of the message, including their role; supported values include agent, customer, or system for virtual agent messages.

Response Details

When successful, this endpoint responds with a unique ASAPP identifier (id) for the message. This identifier should be used if a need arises to reference this message in the future.

​

Requesting Suggestions

ASAPP provides suggestions through one POST request to the AutoCompose API.

POST /autocompose/v1/conversations/\{conversationId\}/suggestions

Use this endpoint to get suggestions for the next agent message in the conversation.

When to Call

This service should be called when an agent joins the conversation, after every agent keystroke, and after a message is sent by either the customer or the agent. In each of these instances, AutoCompose takes into account new conversation context (e.g. the next letter the agent typed) and will return suggestions suitable for that context.

While making a request for a suggestion, a new sent message by either the customer or agent can be posted to the conversation record by including it in the request body. This optional approach to updating the conversation record is in lieu of sending a separate request to the /messages endpoint.

Request Details

The path parameter for this request is the unique ASAPP conversation ID that was provided in the response body when the conversation record was initially created.

Requests must include any text that the agent has already typed (called the query).

To add a message to the conversation record during a suggestion request, you must also include a message object that contains the text of the sent message, the sender role and ID, and the timestamp for the sent message.

Response Details

When successful, this endpoint responds with a set of suggestions or phrase completions, and a unique ASAPP identifier (id) that corresponds to this set of suggestions.

Full suggestions will be returned when the agent has not yet typed and early in the composition of their typed message. Once the agent’s typed message is sufficiently complete, no suggestions will be returned.

Phrase completions are only provided when a high-confidence phrase is available to complete a partially typed message with several words. If no such phrases fit the message, phrase completions will not be returned.

If a message object was included in the request body, the response will include a message object with a unique message identifier.

Metadata Inserts

Suggestions will always include messages with text and templateText fields. Text fields contain the message as it should be shown in the end-user interface, whereas templateText indicates where metadata was inserted into a templated part of the message.

For example, text would read "Sure John"and templateText would read "Sure \{NAME\}". AutoCompose currently supports inserting metadata about a customer name or agent name into a templated suggestion.

​

Check Profanity & Spelling

POST /autocompose/v1/profanity/evaluation

Use this endpoint to receive an evaluation of a text string to verify if it contains a word present on ASAPP’s profanity blocklist.

When to Call

This service should be called when a carriage return or “enter” is used to send an agent message in order to prevent sending profanities in the chat.

Request Details

Requests need only specify the text required to be checked for profanity

Response Details

When successful, this endpoint responds with a boolean indicating whether or not the submitted text contains profanity.

POST /autocompose/v1/spellcheck/correction

Use this endpoint to get a spelling correction for a message as it is being typed.

When to Call

This service should be called after a space character is entered, checking  the most recently completed word in the sentence.

Request Details

Requests must include the text the agent has typed and the position of the cursor to indicate which word the agent has just typed to be checked for spelling.

The request may also specify a user dictionary of any words that should not be corrected if present.

Response Details

When successful and a spelling mistake is present, this endpoint identifies the misspelled text, the correct spelling of the word and start position of the cursor where the misspelled word begins so that it can be replaced.

​

Sending Agent Usage Data

POST /autocompose/v1/analytics/message-sent

Use this endpoint to create an analytics event describing the agent’s usage of AutoCompose for a given message. ASAPP uses these events to train AutoCompose, identifying which forms of augmentation should be credited for contributing to the final sent message.

When to Call

This service should be called after both of the following have occurred:

1. A message has been submitted by an agent
2. A successful request has been made to add this message to ASAPP’s record of the conversation

Request Details

Requests must include the ASAPP identifiers for the conversation and the specific message about which the analytics data is about.

Requests must also include an array called augmentationType that describes the agent’s sequence of AutoCompose usage before sending the message. Valid augmentationType values are described below:

Requests should include identifiers for the initial set of suggestions shown to the agent and the last set of suggestions where the agent made a selection (if any selections were made). If a selection was made, the index of the selected message (from the list of three) should also be specified.

Requests may also include further metadata describing the agents editing keystrokes after selecting a suggestion, their time crafting and waiting to send the message, the time between the last sent message and their first action, and their interactions with phrase completion suggestions (if relevant).

Response Details

When successful, this endpoint confirms the analytics message event was received and returns no response body.

​

Getting Response Lists

ASAPP provides access to the global response list and agent-specific custom response lists through GET requests to two endpoints. Each endpoint is designed to be used to show an agent the contents of the response list in a user interface as they browse or search the list.

GET /autocompose/v1/responses/globals

Use this endpoint to retrieve the global responses and associated folder organization.

When to Call

This service should be called to show an agent the global response list - the list of responses available to all agents - in a user interface in response to an action taken by the agent, such as clicking on a response panel icon or searching for a specific response.

Request Details

Requests must include the agent’s unique identifier from your system - this is the same identifier used to create conversation and conversation message records.

• Only values within a specific folder
• Only responses, only folders, or both
• Only values that match an agent search term

Requests can be returned in multiple pages based on a maximum per page parameter set to ensure a user interface only receives the number responses it can support. This endpoint can be called again with the same query parameters and a pageToken to indicate which page to retrieve in a multi-page list.

Response Details

When successful, this endpoint responds with a response list (if requested) that fits the criteria of the request query parameters, including the id of the response along with the text, title, corresponding folder to which it belongs and any key-value pair metadata associated with the response.

As discussed previously in Metadata Inserts, responses can be templated to insert metadata into specific parts of the message, such as the customer or agent’s name. ASAPP can also use metadata associated with a response (e.g. agent skills for which that response is allowed) to filter out that response from suggestions for a given conversation.

If there is a next page to the response list, a pageToken is provided in the response for use in a subsequent call to show the next page to the user.

This endpoint also responds with a folder list (if requested) including the identifier of the folder, its name, and parent folder (if one exists), and version information about the global list of responses from which this list is sourced.

GET /autocompose/v1/responses/customs

Use this endpoint to retrieve the custom responses and associated folder organization.

When to Call

This service should be called to show an agent their custom response list - the list of responses available to only that agent - in a user interface in response to an action taken by the agent, such as clicking on a response panel icon or searching for a specific response.

Request Details

Requests must include the agent’s unique identifier from your system - this is the same identifier used to create conversation and conversation message records.

Requests may include parameters about what values the returned list should contain based on the context of the request:

• Only values within a specific folder
• Only responses, only folders, or both
• Only values that match an agent search term

Requests can be returned in multiple pages based on a maximum per page parameter set to ensure a user interface only receives the number responses it can support. This endpoint can be called again with the same query parameters and a pageToken to indicate which page to retrieve in a multi-page list.

Response Details

When successful, this endpoint responds with a response list (if requested) that fits the criteria of the request query parameters, including the identifier of the response along with the text, title, corresponding folder to which it belongs and any key-value pair metadata associated with the response.

As discussed previously in Metadata Inserts, responses can be templated to insert metadata into specific parts of the message, such as the customer or agent’s name. ASAPP can also use metadata associated with a response (e.g. agent skills/queues for which that response is allowed) to filter out that response from suggestions for a given conversation.

If there is a next page to the response list, a pageToken is provided in the response for use in a subsequent call to show the next page to the user.

This endpoint also responds with a folder list (if requested) including the identifier of the folder, its name, and parent folder (if one exists).

​

Updating Custom Response Lists

Each agent’s custom responses and the related folders can be added, updated and deleted using six endpoints. These endpoints are designed to carry out actions taken by agents in their personal list management interface.

​

For Responses

POST /autocompose/v1/responses/customs/response

Use this endpoint to add a single custom response for an agent.

When to Call

This service should be called when an agent creates a new custom response.

Request Details

Requests must include the agent’s unique identifier from your system - this is the same identifier used to create conversation and conversation message records.

Requests must also include the text of the custom response and its title.

Requests may include the identifier of the folder in which the response should be stored; if not provided, the response is created at the __root folder level.

Requests may also specify metadata to be inserted into specific parts of the message, such as the customer or agent’s name.

Response Details

When successful, the endpoint responds with a unique ASAPP identifier for the response. This value should be used to update and delete the same response.

PUT /autocompose/v1/responses/customs/response/\{responseId\}

Use this endpoint to update a specific custom response for an agent.

When to Call

This service should be called once an agent edits a custom response.

Request Details

The path parameter for this request is the unique ASAPP response ID provided in the response body when creating the response.

Requests must also include the text and title values of the updated custom response.

Requests may include the identifier of the folder in which the response should be stored and may also specify metadata to be inserted into specific parts of the message, such as the customer or agent’s name.

Response Details

When successful, this endpoint confirms the update and returns no response body.

DELETE /autocompose/v1/responses/customs/response/\{responseId\}

Use this endpoint to delete a specific custom response for an agent.

When to Call

This service should be called when an agent deletes a response.

Request Details

The path parameter for this request is the unique ASAPP response ID provided in the response body when creating the response.

Requests must also include the agent’s unique identifier from your system.

Response Details

When successful, this endpoint confirms the deletion and returns no response body.

​

For Folders

POST /autocompose/v1/responses/customs/folder

Use this endpoint to add a single folder for an agent.

When to Call

This service should be called when an agent creates a new custom response folder.

Request Details

Requests must include the agent’s unique identifier from your system - this is the same identifier used to create conversation and conversation message records.

Requests must also include the name of the custom response folder.

Requests may include the identifier of the parent folder in which to create the new folder.

Response Details

When successful, the endpoint responds with a unique ASAPP identifier for the folder. This value should be used to update and delete the same folder.

PUT /autocompose/v1/responses/customs/folder/\{folderId\}

Use this endpoint to update a specific folder for an agent.

When to Call

This service should be called once an agent edits the name or hierarchy location of the folder.

Request Details

The path parameter for this request is the unique ASAPP folder ID provided in the response body when creating the folder.

Requests must include the agent’s unique identifier from your system and the name of the folder once updated.

Requests may include the identifier of the folder in which the response should be stored if that parent folder has been updated.

Response Details

When successful, this endpoint confirms the update and returns no response body.

DELETE /autocompose/v1/responses/customs/folder/\{folderId\}

Use this endpoint to delete a specific folder for an agent.

When to Call

This service should be called when an agent deletes a folder.

Request Details

The path parameter for this request is the unique ASAPP folder ID provided in the folder body when creating the folder.

Requests must include the agent’s unique identifier from your system.

Response Details

When successful, this endpoint confirms the deletion and returns no response body.

​

Certification

Before providing credentials for applications to use production services, ASAPP reviews your completed integration in the sandbox environment to certify that your application is ready.

The following criteria are used to certify that the integration is ready to use the AutoCompose API in a production environment:

• Under normal conditions, the integration is free of errors
• Under abnormal conditions, the integration provides the correct details in order to troubleshoot the issue
• The correct analytics events are being provided for agent messages that are sent

To test these criteria, an ASAPP Solution Architect will review these AutoCompose functionalities:

• Load a new customer conversation onto the agent desktop/view (with existing customer messages)
• Present the agent with suggestions and enable them to select an option and send
• Enable the agent to modify or add to a selected suggestion, and then send
• Enable the agent to freely type and use a phrase completion
• Enable the agent to use the spell check and profanity functionality
• Verify that correct analytics details are sent to ASAPP when an agent sends a message
• Disable API Keys in developer.asapp.com and generate an error message

The following are the test scenarios and accompanying sequence of expected API requests:

​

Use Case Examples

​

1. Create a Conversation and Ask for Suggestions

The example below is a conversation post request with one customer message. Notice that the id value provided in the /conversations response is used as the conversationId path parameter in subsequent calls.

The conversation and message calls are followed by a suggestion request and response for the agent’s reply which includes two suggestions without a title and one suggestion with a title. The phraseCompletion field is not returned, as the agent has only just begun typing their message with "query": "Sure" when this suggestion request was made.

POST /conversation/v1/conversations

Request

{
  "externalId": "33411121",
  "agent": {
    "externalId": "671",
    "name": "agentname"
  },
  "customer": {
    "externalId": "11462",
    "name": "Sarah Jones"
  },
  "metadata": {
    "organizationalGroup": "some-group",
    "subdivision": "some-division",
    "queue": "some-queue"
  },
  "timestamp": "2021-11-23T12:13:14.55Z"
}

Response

STATUS 200: Successfully created or updated conversation

{
  "id": "5544332211"
}

POST /conversation/v1/conversations/5544332211/messages

Request

{
  "text": "Hello, I would like to upgrade my internet plan to GOLD.",
  "sender": {
    "role": "customer",
    "externalId": "3455123"
  },
  "timestamp": "2021-11-23T12:13:18.55Z"
}

Response STATUS 200: Successfully created message in conversation

{
  "id": "099455443322115544332211"
}

POST /autocompose/v1/conversations/5544332211/suggestions Request

{
  "query": "Sure"
}

Response STATUS 200: Successfully fetched suggestions for the conversation

{
  "id": "453466732233",
  "suggestions": [
    {
      "text": "Sure, can I get your account number for verification please?",
      "templateText": "Sure, can I get your account number for verification please?",
      "title": ""
    },    
    {
      "text": "Sure Sarah, I can certainly help you with that.",
      "templateText": "Sure {NAME}, I can certainly help you with that.",
      "title": ""
    },
    {
      "text": "The GOLD plan is a great choice",
      "templateText": "The GOLD plan is a great choice",
      "title": "Gold plan great choice"
    }
  ]
}

​

2. Check Profanity

The example below is of a profanity check request and response for a text string that does not contain any words found in the profanity blocklist:

POST /autocompose/v1/profanity/evaluation

Request

{
  "text": "This is a perfectly decent sentence."
}

Response

STATUS 200: Successfully fetched a evaluation result of the sentence.

{
  "hasProfanity": false
}

​

3. Check Spelling

The example below is of a spell check request and response for a text string that contains a misspelling in the last typed word of the string:

POST /autocompose/v1/spellcheck/correction

Request

{
  {
  "text": "How is tihs ",
  "typingEvent": {
    "cursorStart": 11,
    "cursorEnd": 12
  },
  "userDictionary": [
    "Hellooo"
  ]
}

Response

STATUS 200: Successfully checked for a spelling mistake.

{
  "misspelledText": "tihs",
  "correctedText": "this",
  "position": 7
}

​

4. Send an Analytics Message Event

The example below is of an analytics message event being sent to ASAPP that provides metadata about how an agent used AutoCompose for a given message. For this message example, the agent used a spelling correction, selected the first response suggestion offered, and subsequently used the first phrase completion presented to finish the sentence, in that order. POST /autocompose/v1/analytics/message-sent Request

{
  "conversationId": "5544332211",
  "messageId": "ee675e6576c0faf40dbb92d0d5993f5f",
  "augmentationType": [
    "FLUENCY_APPLY",
    "AUTOSUGGEST",
    "PHRASE_AUTOCOMPLETE"
  ],
  "numEdits": 2,
  "selectedSuggestionText": "How can I help you today?",
  "selectedSuggestionsId": "5e9491b203e6ecccfef964e26fb1a5d3",
  "selectedSuggestionIndex": 1,
  "initialSuggestionsId": "5e9491b203e6ecccfef964e26fb1a5d3",
  "timeToAction": 1.891412,
  "craftingTime": 10.9472,
  "dwellTime": 4.132985,
  "phraseAutocompletePresentedCt": 1,
  "phraseAutocompleteSelectedCt": 1
}

Response STATUS 200: Successfully created a MessageSent event. In this example, the agent typed a message and sent it without using any assistance from AutoCompose: Request

 {
  "messageId": "ee675e6576c0faf40dbb92d0d5993e2q",
  "augmentationType": [
    "FREEHAND"
  ],
  "initialSuggestionsId": "5e9491b303e6ecccfef164e26fb1afq9",
  "timeToAction": 2.891412,
  "craftingTime": 20.9472,
  "dwellTime": 5.132985
}

Response

STATUS 200: Successfully created a MessageSent event.

In this example, the agent typed “hel”, selected the second suggestion presented to them and sent it:

Request

 {
  "messageId": "ee675e1236c0faf40dcb92h0e5y93e2p",
  "augmentationType": [
    "AUTOCOMPLETE"
  ],
  "selectedSuggestionText": "Hello there, welcome to customer support chat!",
  "selectedSuggestionsId": "4d2fd982640c311394008259594399a1",
  "selectedSuggestionIndex": 2,
  "initialSuggestionsId": "4d2fd982640c311394008259594399a1",
  "timeToAction": 1.891412,
  "craftingTime": 11.9472,
  "dwellTime": 2.132985
}

Response STATUS 200: Successfully created a MessageSent event. In this example, the agent typed “htis”, hit the space bar, and spellcheck corrected the text to “this”. Then the agent accidentally reversed the spell check and sent the message to the customer without using any other AutoCompose assistance: Request

 {
  "messageId": "fe675e1236c0fbf40dcb33h0e5y93e1d",
  "augmentationType": [
    "FLUENCY_APPLY",
    "FLUENCY_UNDO"
  ],
  "initialSuggestionsId": "2d2fd982640c311146008259594399a2",
  "timeToAction": 1.891412,
  "craftingTime": 11.9472,
  "dwellTime": 2.132985
}

Response

STATUS 200: Successfully created a MessageSent event.

​

5. Show an Agent Global Responses

The example below is of a request to show global responses only to an agent who is searching the greetings folder for a particular response. NOTE: The response below is shortened to show two responses.

GET /autocompose/v1/responses/globals

Request

Query Parameters:

        folderId: "9923599"
        resourceType: "responses"
        searchTerm: "transfer"

Response

STATUS 200: The global responses for this company

{
  "responses": {
    "responsesList": [
      {
        "id": "425523523599",
        "text": "I’d be happy to transfer you to my supervisor.",
        "title": "Sup Transfer 2",
        "folderId": "9923599",
      },
      {
        "id": "425523523598",
        "text": "No problem {NAME}, I’d be happy to transfer you to my supervisor.",
        "title": "Sup Transfer 1",
        "folderId": "9923599 ",
        "metadata": [
          {
            "name": "NAME",
            "allowedValues": [
              "customer.name"
            ]
          }
        ]
      }
    ],
  },
  "version": {
    "id": "12134",
    "description": "June 5 2022 Update"
  }
}

​

6. Creating a New Custom Response Folder and Response

The example below shows the calls that would accompany an agent creating a new greeting custom response without a folder, then adding it to an existing folder.

POST /autocompose/v1/responses/customs/response

Request

{
  "text": "Howdy, how can I help you today?",
  "title": "Howdy Help"
}

Response

STATUS 200: Acknowledgement that the response was successfully added

{
  "id": "425523523523",
  "text": "Howdy, how can I help you today?",
  "title": "Howdy Help",
  "folderId": "__root"
}

PUT /autocompose/v1/responses/customs/response/425523523523

Request

{
  "text": "Howdy, how can I help you today?",
  "title": "Howdy Help",
  "folderId": "9923523"
}

Response

STATUS 201: Acknowledgement that the custom response was successfully updated

​

Data Security

ASAPP’s security protocols protect data at each point of transmission, from first user authentication, to secure communications, to our auditing and logging system, all the way to securing the environment when data is at rest in the data logging system. Access to data by ASAPP teams is tightly constrained and monitored. Strict security protocols protect both ASAPP and our customers.

The following security controls are particularly relevant to AutoCompose:

1. Client sessions are controlled using a time-limited authorization token. Privileges for each active session are controlled server-side to mitigate potential elevation-of-privilege and information disclosure risks.
2. To avoid unauthorized disclosure of information, unique, non-guessable IDs are used to identify conversations. These conversations can only be accessed using a valid client session.
3. Requests to API endpoints that can potentially receive sensitive data are put through a round of redaction to strip the request of sensitive data (like SSNs and phone numbers).

​

Additional Considerations

​

Historical Conversation Data for Generating a Response List

ASAPP uses past agent conversations to generate a customized response list tailored to a given use case. In order to create an accurate and relevant list, ASAPP requires a minimum of 200,000 historical transcripts to be supplied ahead of implementing AutoCompose.

For more information on how to transmit the conversation data, reach out to your ASAPP account contact.

Visit Transmitting Data to SFTP for instructions on how to send historical transcripts to ASAPP.