Transcript Service

The ServisBOT Transcript Service allows users to get a complete transcript of a conversation as an email, .pdf file, or as JSON.

API Definition

The Swagger API definition for the Transcript Service can be found below:

swagger: '2.0'
info:
  title: ServisBOT Transcript Service
  version: '1.0'
basePath: /
schemes:
  - https

paths:
  /health:
    get:
      tags:
        - health
      responses:
        '200':
          description: OK
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/InternalServerError'
      produces:
      - "application/json"
  /{version}/{org}/RetrieveTranscript:
    post:
      tags:
        - Transcript
      parameters:
        - name: version
          in: path
          required: true
          type: string
          default: v1
        - name: org
          in: path
          required: true
          type: string
          default: myorg
        - name: Authorization
          in: header
          required: true
          type: string
          default: ApiKey supersecretkey
        - name: body
          in: body
          schema:
            $ref: '#/definitions/ConversationId'
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/SampleTranscription'
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/BadRequest'
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/Unauthorized'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/InternalServerError'
      produces:
      - "application/json"
  /{version}/{org}/EmailTranscript:
    post:
      tags:
        - Transcript
      parameters:
        - name: version
          in: path
          required: true
          type: string
          default: v1
        - name: org
          in: path
          required: true
          type: string
          default: myorg
        - name: Authorization
          in: header
          required: true
          type: string
          default: ApiKey supersecretkey
        - name: body
          in: body
          schema:
            $ref: '#/definitions/ConversationIdWithEmail'
      responses:
        '200':
          description: OK
          schema:
            type: object
            description: Message ID
            example:
              MessageId: "010031721c5f01ef-1069be3c-a9aa-4263-a584-313a4fbf7c49-000000"
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/BadRequest'
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/Unauthorized'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/InternalServerError'
      produces:
      - "application/json"
  /{version}/{org}/GeneratePDF:
    post:
      tags:
        - Transcript
      parameters:
        - name: version
          in: path
          required: true
          type: string
          default: v1
        - name: org
          in: path
          required: true
          type: string
          default: myorg
        - name: Authorization
          in: header
          required: true
          type: string
          default: ApiKey supersecretkey
        - name: Body Parameters
          in: body
          schema:
            $ref: '#/definitions/ConversationId'
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/SamplePDF'
        '400':
          description: Bad Request
          schema:
            $ref: '#/definitions/BadRequest'
        '401':
          description: Unauthorized
          schema:
            $ref: '#/definitions/Unauthorized'
        '500':
          description: Internal Server Error
          schema:
            $ref: '#/definitions/InternalServerError'
      produces:
      - "application/json"

definitions:
  SampleTranscription:
    type: object
    properties:
      Messages:
        type: array
        items:
          type: object
          properties:
            Actor:
              type: string
              description: Who sent the message
              example: bot
            Timestamp:
              type: integer
              description: When the message was sent
              example: 1585236944
            Message:
              type: object
              description: The details of the message itself
              properties:
                Content:
                  type: string
                  description: The contents of the sent message
                  example: Welcome! How can I help you today?
                Type:
                  type: string
                  description: The type of the message that was sent
                  example: TimelineElement - TextMsg
    example:
      - Actor: bot
        Timestamp: 1585236944
        Message:
          Content: Welcome! How can I help you today?
          Type: TimelineElement - TextMsg
      - Actor: user
        Timestamp: 1585236959
        Message:
          Content: How many orders do I have?
          Type: ContentType - Message
      - Actor: bot
        Timestamp: 1585236964
        Message:
          Content: You have two orders on the way.
          Type: TimelineElement - TextMsg
  SamplePDF:
    type: object
    properties:
      text:
        type: string
        description: Raw PDF file
        example: "%PDF-1.4\n ... %%EOF"
  ConversationId:
    type: object
    description: ID of the conversation to transcribe
    properties:
      ConversationId:
        type: string
        description: ConversationID of the conversation to be transcribed
        example: "1064b3c3-3bc2-ff32-b601-60bd58fae143"
    required:
      - ConversationId
  ConversationIdWithEmail:
    type: object
    description: ID of the conversation to transcribe and the email to send it to
    properties:
      ConversationId:
        type: string
        description: ID of the transcribed conversation
        example: "1064b3c3-3bc2-ff32-b601-60bd58fae143"
      Email:
        type: string
        description: Email to send the transcribed conversation to
        example: botty@servisbot.com
    required:
      - ConversationId
      - Email
  BadRequest:
    type: object
    description: Bad Request
    properties:
      Error:
        type: string
        example: "\"ConversationId\" is required"
  Unauthorized:
    type: object
    description: Unauthorized
    properties:
      Error:
        type: string
        example: Unauthorized
  InternalServerError:
    type: object
    description: Internal Server Error
    properties:
      Error:
        type: string
        example: Internal Server Error

API Connectors

Secret Configuration

To configure a secret for the transcript service in Portal:

  1. Log into your organization as a user with the IT role
  2. On the navigation bar on the left, click ‘Secrets Management’
  3. A list of all secrets appears. Click ‘+ Create Secret’ at the top right
  4. Enter a name for your secret under Alias
  5. Click the Secret Type Template dropdown and select ‘Custom JSON’
  6. Under Secret, enter the following:
{
  "Authorization": "ApiKey yourSecretApiKeyHere"
}
  1. Click ‘Validate Secret Format’ under Secret to double check the JSON validity. Secrets cannot be viewed nor edited after creation.
  2. Click ‘Save’

Secret Creation

To access the API key later, use its ssn: srn:vault:global:myorg:secret:my-secret-alias/Authorization

BaaS Configuration and Testing

To create a Transcript Service API connector in Portal:

  1. On the navigation bar on the left, click ‘API Connectors’
  2. A list of API connectors will appear. Click ‘+ Create New’ -> Create New
  3. Enter suitable JSON for the API connector. Examples of JSON for each endpoint can be seen here.

api-connector-creation

  1. Click ‘Save’
  2. Go to the Test tab on the API connector page
  3. Enter the required mappings such as conversationId/email
  4. Click ‘test’
  5. Check the raw/mapped endpoint response to see what the transcript service returned.

api-connector-testing

Examples

Note: The endpoints below are using an example domain. In practice, your BaaS will have to point to your own transcript site.

RetrieveTranscript

CHS in sherpa

{
  "Method": "POST",
  "Endpoint": "https://sometranscriptsite.com/v1/myorg/RetrieveTranscript",
  "Headers": {
    "Authorization": "srn:vault::myorg:secret:my-secret-alias/Authorization",
    "Content-Type": "application/json"
  },
  "Alias": "RetrieveTranscript",
  "RequestMapping": {
    "ConversationId": {
      "type": "requestBody",
      "requestBodyPath": "$.ConversationId",
      "inputPath": "$.conversationId"
    }
  },
  "ResponseMapping": {},
  "Body": {}
}

Using the Servisbot CHS

{
  "Method": "POST",
  "Endpoint": "https://chsurl.com/v1/YOUR_ORG/RetrieveTranscript",
  "Headers": {
    "Content-Type": "application/json"
  },
  "Alias": "RetrieveTranscript",
  "Organization": "YOUR_ORG",
  "RequestMapping": {
    "ConversationId": {
      "type": "requestBody",
      "requestBodyPath": "$.ConversationId",
      "inputPath": "$.conversationId"
    }
  },
  "ResponseMapping": {},
  "Type": "sb-jwt-api-connector",
  "Body": {},
  "Credentials": "srn:vault::YOUR_ORG:secret:transcriptsecret"
}
EmailTranscript

CHS in sherpa

{
  "Method": "POST",
  "Endpoint": "https://sometranscriptsite.com/v1/myorg/EmailTranscript",
  "Headers": {
    "Authorization": "srn:vault:global:myorg:secret:my-secret-alias/Authorization",
    "Content-Type": "application/json"
  },
  "Alias": "EmailTranscript",
  "RequestMapping": {
    "ConversationId": {
      "type": "requestBody",
      "requestBodyPath": "$.ConversationId",
      "inputPath": "$.conversationId"
    },
    "Email": {
      "type": "requestBody",
      "requestBodyPath": "$.Email",
      "inputPath": "$.email"
    }
  },
  "ResponseMapping": {},
  "Body": {}
}

Using the Servisbot CHS

{
  "Method": "POST",
  "Endpoint": "https://chsurl.com/v1/YOUR_ORG/EmailTranscript",
  "Headers": {
    "Content-Type": "application/json"
  },
  "Alias": "EmailTranscript",
  "Organization": "YOUR_ORG",
  "RequestMapping": {
    "ConversationId": {
      "type": "requestBody",
      "requestBodyPath": "$.ConversationId",
      "inputPath": "$.conversationId"
    },
    "Email": {
      "type": "requestBody",
      "requestBodyPath": "$.Email",
      "inputPath": "$.email"
    }
  },
  "ResponseMapping": {},
  "Type": "sb-jwt-api-connector",
  "Body": {},
  "Credentials": "srn:vault::YOUR_ORG:secret:transcriptsecret"
}
GeneratePDF

CHS in sherpa

{
  "Method": "POST",
  "Endpoint": "https://sometranscriptsite.com/v1/myorg/GeneratePDF",
  "Headers": {
    "Authorization": "srn:vault:global:myorg:secret:my-secret-alias/Authorization",
    "Content-Type": "application/json"
  },
  "Alias": "GeneratePDF",
  "RequestMapping": {
    "ConversationId": {
      "type": "requestBody",
      "requestBodyPath": "$.ConversationId",
      "inputPath": "$.conversationId"
    }
  },
  "ResponseMapping": {},
  "Body": {}
}

Using the Servisbot CHS

{
  "Method": "POST",
  "Endpoint": "https://chsurl.com/v1/YOUR_ORG/GeneratePDF",
  "Headers": {
    "Content-Type": "application/json"
  },
  "Alias": "GeneratePDF",
  "Organization": "YOUR_ORG",
  "RequestMapping": {
    "ConversationId": {
      "type": "requestBody",
      "requestBodyPath": "$.ConversationId",
      "inputPath": "$.conversationId"
    }
  },
  "ResponseMapping": {},
  "Type": "sb-jwt-api-connector",
  "Body": {},
  "Credentials": "srn:vault::YOUR_ORG:secret:transcriptsecret"
}