Text-Based Integration

Prev Next
Recommended integration methods

This method is still supported, but it is not the recommended way to connect a telephony system to SESTEK AI Agents. For new integrations, use one of the following methods.

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

image.png

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:

Key Description
Authorization Sestek AI Agents Synchronized API requires an access token with the orchestrator_external scope, which must be sent as a Bearer token in the Authorization header.
Project The project name that the client wants to run must be included in the HTTP request headers, such as 'Banking'.
X-Knovvu-Conversation-Id X-Knovvu-Conversation-Id key and its value must be included in the request header. to send multiple requests within a single conversation session.

image.png

Important Notes
  • To integrateSestek AI Agents with telephony systems, use ivr-external as channelId in the activity object.

  • The responseType parameter must be set as Text and included within the channelData{} field of the activity object.


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",
        "EndUser": {
            "Name": null,
            "Phone": null,
            "Email": null,
            "Id": null
        }
    }
}'


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,
            "Id": 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}},
        "EndUser": {
            "Name": null,
            "Phone": null,
            "Email": null,
            "Id": null
        }
    }
}


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}},
        "EndUser": {
            "Name": null,
            "Phone": null,
            "Email": null,
            "Id": null
        }
    }
}


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}},
        "EndUser": {
            "Name": null,
            "Phone": null,
            "Email": null,
            "Id": null
        }
    }
}



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.

image.png

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}},
        "EndUser": {
            "Name": null
            "Phone": null,
            "Email": null,
            "Id": null
        }
    }
}