1. Text-Based Integration

Text-Based Integration is used when SR and TTS services are externally managed by the IVR system and only text messages are sent Knovvu VA. Audio can also be included optionally, typically for reporting and analysis purposes.

Request Types:

• Text: Message that includes only text, without any audio.
• Text with Audio Base64: Text message with audio encoded in Base64 format, included in the attachments field as content.
• Text with Audio Minio: Text message with a path to an audio file stored in Minio, included in the attachments field as contentUrl.
• Text with Audio URL: Text message with a link to audio file, included in the attachments field as contentUrl.
• Text with Audio Multipart: Text message with audio file, included in request body as form data as AudioForSr.

Parameters to be sent in the request header:

1. Sending Text Request

Endpoint:
URL: {{baseUrl}}/magpie/ext-api/messages/synchronized
HTTP Method: POST
Content Type: application/json

Here's an example of a request:

curl --location '{{baseUrl}}/magpie/ext-api/messages/synchronized' \
--header 'Project: {{Project}}' \
--header 'X-Knovvu-Conversation-Id: {{GUID}}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{accessToken}}' \
--data '{
    "text": "{{userInput}}",
    "type": "message",
    "channelId": "ivr-external",
    "conversation": {
        "id": "{{X-Knovvu-Conversation-Id}}"
    },
    "attachments": [],
    "channelData": {
        "ResponseType": "Text"
    }
}'

Expected Response:

{
    "type": "message",
    "id": "3083749e-80af-4032-a929-768308edf654",
    "timestamp": null,
    "localTimestamp": null,
    "localTimezone": null,
    "serviceUrl": "http://localhost",
    "channelId": "ivr-external",
    "from": null,
    "conversation": {
        "isGroup": null,
        "conversationType": null,
        "id": "{{X-Knovvu-Conversation-Id}}",
        "name": null,
        "aadObjectId": null,
        "role": null,
        "tenantId": null
    },
    "recipient": null,
    "textFormat": null,
    "attachmentLayout": null,
    "membersAdded": null,
    "membersRemoved": null,
    "reactionsAdded": null,
    "reactionsRemoved": null,
    "topicName": null,
    "historyDisclosed": null,
    "locale": null,
    "text": "{{botResponse}}",
    "speak": null,
    "inputHint": null,
    "summary": null,
    "suggestedActions": null,
    "attachments": [],
    "entities": null,
    "channelData": {
        "IsSynchronizer": false,
        "HasExternalAudioContent": false,
        "SrConfidence": null,
        "CustomProperties": {},
        "CustomAction": null,
        "CustomActionData": null,
        "ProjectName": "{{Project}}",
        "ResponseType": 0,
        "EndUser": {
            "Name": null,
            "Phone": null,
            "Email": null,
            "Twitter": null
        }
    },
    "action": null,
    "replyToId": null,
    "label": null,
    "valueType": null,
    "value": null,
    "name": null,
    "relatesTo": null,
    "code": null,
    "expiration": null,
    "importance": null,
    "deliveryMode": null,
    "listenFor": null,
    "textHighlights": null,
    "semanticAction": null,
    "callerId": null
}

2. Sending Text Request with Attachment

This feature is intended for situations where audio is attached to a text-based request. The attached audio file is downloaded and stored in Minio, enabling playback on the Conversation Details page for reporting purposes.

When sending a text message with an attachment, HasExternalAudioContent must be set to true to indicate the presence of external audio content. If SR (Speech Recognition) confidence data is available, you can set the SrConfidence property to reflect the confidence level of the speech recognition. This property should be a double value between 0.00 and 1.00.

Supported contentType for the attachment field includes:

• audio/base64
• • audio/minio
• audio/url

2.1. Audio Base64

{
    "text": "{{userInput}}",
    "type": "message",
    "channelId": "ivr-external",
    "conversation": {
        "id": "{{X-Knovvu-Conversation-Id}}"
    },
    "attachments": [
        {
            "contentType": "audio/base64",
            "content": "{{base64Data}}"
        }
    ],
    "channelData": {
        "ResponseType": "text",
        "HasExternalAudioContent": true,
        "SrConfidence": {{SrConfidence}}
    }
}

2.2. Audio Minio

{
    "text": "{{userInput}}",
    "type": "message",
    "channelId": "ivr-external",
    "conversation": {
        "id": "{{X-Knovvu-Conversation-Id}}"
    },
    "attachments": [
        {
            "contentType": "audio/minio",
            "contentUrl": "{{audioMinioKey}}"
        }
    ],
    "channelData": {
        "ResponseType": "text",
        "HasExternalAudioContent": true,
        "SrConfidence": {{SrConfidence}}
    }
}

2.3. Audio URL

{
    "text": "{{userInput}}",
    "type": "message",
    "channelId": "ivr-external",
    "conversation": {
        "id": "{{X-Knovvu-Conversation-Id}}"
    },
    "attachments": [
        {
            "contentType": "audio/url",
            "contentUrl": "{{audioUrl}}"
        }
    ],
    "channelData": {
        "ResponseType": "text",
        "HasExternalAudioContent": true,
        "SrConfidence": {{SrConfidence}}
    }
}

3. Sending Text Request with Audio File

This configuration is used when sending an audio file as part of a text-based request to the Knovvu VA Synchronized API. The body section of the request should contain the following key parameters:

• activity: An activity object representing the text message and its associated metadata, such as ResponseType, HasExternalAudioContent, and SrConfidence.

• AudioForSr: An audio file (e.g., audio.wav) uploaded as form-data.

Here is an example activity object:

{
    "text": "{{userInput}}",
    "type": "message",
    "channelId": "ivr-external",
    "conversation": {
        "id": "{{X-Knovvu-Conversation-Id}}"
    },
    "attachments": [],
    "channelData": {
        "ResponseType": "text",
        "HasExternalAudioContent": true,
        "SrConfidence": {{SrConfidence}}
    }
}