Service Cloud Voice Implementation Guide

Overview
Examples of Common Use Cases
Telephony Integration API
Toolkit API
Connect API
AWS Lambda Functions
Amazon Connect Flows
Amazon CloudWatch Monitoring
Limits and Scaling
PDF

Newer Version Available

This content describes an older version of this product. View Latest

Upload or Update Transcripts with Connect REST API

Use Connect REST API to upload and update transcripts for voice calls. This functionality can also be used for redacting content in transcripts.

These Connect API resources provide programmatic access to voice transcripts (also called “conversation entries”) so that customers can build custom solutions with voice transcripts.

/connect/conversations/upload (GET)
Get the status of conversation uploads.
/connect/conversations/upload (POST)
Upload bulk conversations.
/connect/conversation/conversationIdentifier/entries (GET)
Get conversation entries.
/connect/conversation/conversationIdentifier/entries (PATCH)
Update conversation entries.

Usage Example

This example describes how to perform bulk upload of transcripts to a voice call after the conversation.

  1. Retrieve the VoiceCall ID for a conversation.

    In order to perform the subsequent steps, you must get the VoiceCall record ID.

    VoiceCall ID

  2. Using the VoiceCall ID, retrieve the Conversation record and the ConversationParticipant records.

    Using SOQL, you can query for the Conversation ID. For example:

    With the Conversation ID, you can query for additional fields on the Conversation record. For example:

    You can also get information about the ConversationParticipant records. For example:

    Values returned from this SOQL call are used in the subsequent upload API POST payload. Specifically:

    • AppType in the SOQL call is used for the “appType” value in the payload. For API version 52.0 and later, refer to the AppType to appType Mapping table.
    • ParticipantRole is used for the “role” value. For API version 52.0 and later, refer to the ParticipantRole to role Mapping table.
    • ParticipantKey is used for the “subject” value.
    Table 1. AppType to appType Mapping
    AppType Value in SOQL appType Value in Payload
    bmapi BMAPI
    live_message LIVE_MESSAGE
    chatbot CHATBOT
    messaging MESSAGING
    perftool PERFTOOL
    agent AGENT
    telephony_integration TELEPHONY_INTEGRATION
    translation TRANSLATION
    iamessage IAMESSAGE
    conversation CONVERSATION
    Table 2. ParticipantRole to role Mapping
    ParticipantRole Value in SOQL role Value in Payload
    System SYSTEM
    Agent AGENT
    Chatbot CHATBOT
    EndUser END_USER
    Supervisor SUPERVISOR
    Router ROUTER
  3. Call the bulk upload API using the desired payload.

    Make a POST call to the Connect REST API for uploading conversation data. For example:

    Use a payload that contains the desired conversation participant info, along with the conversation entries. For example, the following payload sample applies to API version 52.0 and later.

    Use the following guidance when filling out this payload:

    • Within each part of the payload, the first object must contain the conversation details (”conversation”). The last set of objects contains the conversation entries (”conversationEntry”).
    • The clientSentTimestamp must be between startTimestamp and endTimestamp. Timestamps are specified using the UNIX Epoch time.
    • contextParamMap is optional and can be used to add contextual information.
    • appType, role, and subject come from the ConversationParticipant SOQL call described in the previous step.
    • In the multi-part POST request, the name of the part (that is, the binary file) must be the conversationId. For details, see Uploading Binary Files in the Connect REST API Developer Guide.

    Currently, this API only supports existing closed conversations. A previous version of this API required a conversation channel, the start timestamp, and the end timestamp in the conversation object, and it required conversation participant objects. These values are now optional.

    Note

    You get the following response when the call is successful.

  4. Check the status of the upload.

    To check the status, perform a GET request to the same resource using the upload IDs.

    If the upload was successful, you see this type of response.

    If the upload failed, you see this type of response.

You can get the new conversation entries using an HTTP GET to /connect/conversation/conversationIdentifier/entries.