--- title: "Text-Based Integration" slug: "ai-agents-text-based-integration" updated: 2026-11-02T11:41:46Z published: 2026-11-02T11:41:46Z canonical: "docs.sestek.com/ai-agents-text-based-integration" --- > ## Documentation Index > Fetch the complete documentation index at: https://docs.sestek.com/llms.txt > Use this file to discover all available pages before exploring further. # Text-Based Integration 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. - [SIP Trunk Integration (On-Premises)](https://docs.sestek.com/docs/en/ai-agents-sip-trunk-integration-on-premises) - [SIP Trunk Integration (Cloud)](https://docs.sestek.com/docs/en/ai-agents-sip-trunk-integration-cloud) 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](https://cdn.document360.io/9bca2910-6a3b-4224-9470-43f91f9a6d57/Images/Documentation/image-NU5RBCYD.png?sv=2026-02-06&spr=https&st=2026-11-21T18%3A23%3A28Z&se=2026-11-21T19%3A23%3A28Z&sr=b&sp=r&sig=CHNytjUR9mWgacp3hSWzIRW9GrLn%2F0TudJ793GN%2FWOk%3D) **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](https://docs.knovvu.com/docs/va-getting-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](https://cdn.document360.io/9bca2910-6a3b-4224-9470-43f91f9a6d57/Images/Documentation/image-C4X9S1UK.png?sv=2026-02-06&spr=https&st=2026-11-21T18%3A23%3A28Z&se=2026-11-21T19%3A23%3A28Z&sr=b&sp=r&sig=dlhHENr8hxkdP8c5oLHHEvVHSSRiIK%2FNHzCQI%2FbSJ0Y%3D) 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](https://cdn.document360.io/9bca2910-6a3b-4224-9470-43f91f9a6d57/Images/Documentation/image-UBLB6QC6.png?sv=2026-02-06&spr=https&st=2026-11-21T18%3A23%3A28Z&se=2026-11-21T19%3A23%3A28Z&sr=b&sp=r&sig=4Po1vmMnDmLhHRSuwPhyLaeodJyRmH6Kloj19j87WQ8%3D) **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 } } } ```