Service Cloud Voice Implementation Guide

Clouds with binary code floating aboveCloud with binary code floating above

No Results

Search Tips:

  • Please consider misspellings
  • Try different search keywords
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

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:

    SELECT ConversationId FROM VoiceCall WHERE Id = '0LMRM000000HU8a4AG'

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

    SELECT ConversationChannelId,ConversationIdentifier,CreatedById,CreatedDate,EndTime,Id,IsDeleted,LastModifiedById,LastModifiedDate,Name,StartTime 
       FROM Conversation WHERE Id = '0dwRMR000003M5pYAE'

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

    SELECT AppType,ConversationId,CreatedById,CreatedDate,Id,IsDeleted,JoinedTime,LastActiveTime,LastModifiedById,LastModifiedDate,LeftTime,Name,ParticipantContext,ParticipantDisplayName,ParticipantEntityId,ParticipantKey,ParticipantRole
       FROM ConversationParticipant WHERE ConversationId = '0dwRMR000003M5pYAE'

    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:

    POST https://MY_ORG_DOMAIN/services/data/v52.0/connect/conversations/upload

    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.

    {"type": "conversation", "payload": {"conversationId": "ab123456-76d6-4d60-a53d-fb69d800b10c"}}
{"type": "conversationEntry", "payload": {"conversationId": "cd123456-76d6-4d60-a53d-fb69d800b10c", "id": "1", "clientSentTimestamp": 1610580214000, "clientDuration": 123432, "messageText":"Hello, how can I help you?","sender": {"appType": "AGENT", "subject": "005RM00000225FB","role": "AGENT"},"relatedRecords": ["0LQXXXXXXXXXXXX"] }}
{"type": "conversationEntry", "payload": {"conversationId": "ef987654-76d6-4d60-a53d-fb69d800b10c", "id": "2", "clientSentTimestamp": 1610580214001, "clientDuration": 123432, "messageText":"I want to return this merchandise. Can you please help?","sender": {"appType": "TELEPHONY_INTEGRATION", "subject": "END_USER","role": "END_USER"},"relatedRecords": ["0LQXXXXXXXXXXXX"]}}

    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 used to add contextual information. This parameter is optional.
    • appType, role, and subject come from the ConversationParticipant SOQL call described in the previous step.
    • relatedRecords is the list of object records that are associated with the conversation entry.
    • 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.

    {
    "conversationBulkUploadsResults": [
        {
            "conversationIdentifier": "fc803778-76d6-4d60-a53d-fb69d800b10c",
            "errorDetail": null,
            "status": "SUCCESS",
            "uploadId": "333e7382-ef11-3396-b7c2-156fb6b5f7ad"
        }
    ]
}
  4. Check the status of the upload.

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

    GET https://MY_ORG_DOMAIN/services/data/v51.0/connect/conversations/upload?uploadIds=uploadId1,uploadId2,uploadId3

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

    {
    "conversationBulkUploadsResults": [
        {
            "conversationIdentifier": "fc803778-76d6-4d60-a53d-fb69d800b10c",
            "errorDetail": null,
            "status": "SUCCESS",
            "uploadId": "333e7382-ef11-3396-b7c2-156fb6b5f7ad"
        }
    ]
}

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

    {
    "conversationBulkUploadStatuses": [
        {
            "conversationId": "fc803778-76d6-4d60-a53d-fb69d800b10c",
            "errorDetail": "Failed to process any conversation entries.",
            "failedEntryCount": 2,
            "failedEntryIds": [
                "1",
                "2"
            ],
            "lastUpdatedTimestamp": 1611621077219,
            "status": "FAILED",
            "successEntryCount": 0,
            "uploadId": "333e7382-ef11-3396-b7c2-156fb6b5f7ad"
        }
    ]
}

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