Integration Technical Requirements

This document contains information about providing an real-time integration between Knovvu products (Knovvu Real-Time Guiance/Knovvu Biometrics) and a 3rd party platform. The 3rd party platform to be integrated, should meet the requirements further explained.

There are 3 main technical steps required to provide a real-time integration:
1. Authentication: Authentication step is required for security reasons, in order to verify that incoming requests come from the integrated platform.
2. Sending events: To provide a real-time integration, the events of the calls, such as call started, call ended etc., should be received.
3. Sending streams: Real-time audiostreams of the calls should be sent to Knovvu products, to provide real-time outputs.

1. Authentication

Authentication step is required to verify that incoming requests come from the integrated platform.
To provide a secure authentication, when sending an event 2 parameters should be sent in each websocket and webhook request.

1.1. API Key

Sestek will manually send a base64 value to the integration platform. It is expected from integrated platform to return this value in the header of each request.

Key=Sestek-Api-Key
Value=base64 api key value

1.2. Organization ID

Sestek's integration services run multitenant, meaning that only 1 service will be deployed in each environment.
In order to match the requests to the related Sestek tenant, the integrated platform should send an ID to represent their organization/tenant/account (according to their naming).

##Example request:

curl --location 'sestek-url' \
--header 'Sestek-Api-Key: base64 encoded string' \
--header 'OrganizationId: organizationId' \
--header 'Content-Type: application/json' \
--data '{
	"caller_number": "+1...",
	"called_number": "+1...",
	"direction": "inbound",
	"call_id": "",
	"agent_id": "",
	"call_start_time": "",
	"call_end_time": "",
	"attached_data": "",
	"ender_side": "",
	"customer_phone_number": "",
	"customer_id": "",
	"queue_id": ""
}'

2. Sending Events

Eventler her zaman webhook.

When sending event the parameters below should be sent in the request.

1. Call Properties: The details about the call should be sent under CallProperties object.

   1. Caller number
   2. Called number
   3. Direction: Options should be inbound/outbound
   4. Call ID (unique key of conversation)
   5. Agent ID
   6. Call start time (optional)
   7. Call end time (optional)
   8. Attached data: (i.e. custom data) If sent, it must be as key-value pairings. (optional)
   9. Ender side: Options: agent/customer/unknown/transfer)
   10. Customer phone number (optional)
   11. Customer ID (optional)
   12. Queue ID (optional) -> mandatory if queue-filter will be implemented

2. Event Type: Options should be call begin/call end/call hold/call resume (other event types can be added)

3. Event Time

##Example request:
{
	"caller_number": "+1...",
	"called_number": "+1...",
	"direction": "inbound",
	"call_id": "",
	"agent_id": "",
	"call_start_time": "",
	"call_end_time": "",
	"attached_data": "",
	"ender_side": "",
	"customer_phone_number": "",
	"customer_id": "",
	"queue_id": ""
}

3. Sending streams

Audio streams required for a real-time integration should be sent using websocket protocol.

Websocket Connection
For each conversation, the 3rd party to be integrated is expected to open a websocket connection. The entire duration of an agent's conversation from the beginning to the end is considered a session. In integration, a new websocket must be opened for each session.

There are 2 types of websocket messages for sending streams and conversations details: websocket binary messages and websocket text messages.

Note: The audio stream should be send according to the OpenedParameter message after receiving it. The details are further explained.

3.1. Websocket Binary Messaging

To send audiostreams of the conversation, websocket messages should be as binary message.

3.2. Websocket Text Messaging

To send conversation details, websocket messages should be as text messages.

The websocket request must contain the following parameters in WebsocketMessage object:

1. Type: Options should be open/opened/resume/resumed. Websocket message types are further explained.
2. Client Sequence: Client and Server Sequence parameters represent the order of the messages. Each request coming from the integration side will increase ClientSeq by 1 and each request coming from Sestek will increase ServerSeq by 1.
3. Server Sequence: Client and Server Sequence parameters represent the order of the messages. Each request coming from the integration side will increase ClientSeq by 1 and each request coming from Sestek will increase ServerSeq by 1.

4. Parameters: Parameters required for each websocket message type are further explained.

WebsocketMessage Parameter Types

OpenParameter
OpenParameter is sent first when a websocket connection is to be opened. This request will be sent to Sestek by the integrated other party. In the websocket request, if Type is Open, OpenParameter should be sent as "Parameter". In OpenapArameter object, the parameters below should be sent:

1. Conversation ID
2. MediaParameters: The details about media file should be sent under MediaParameters object.
   1. Media Format: Options should be A-law or u-law.
   2. Sample rate: Default value should be 8000 (integer)
   3. Media Channel: Options should be customer, agent. (array) It indicates which channel will be the first byte in the incoming stereo stream, e.g., if "customer, agent" is sent, the first speaker in the conversation is the customer and the second agent.

##Example request:
{
	"type": "open",
	"seq": 1,
	"server_seq": 1,
	"conversation_id": "",
	"media_format": "alaw", // alaw, ulaw
	"sample_rate": "8000",
	"media_channel": ["agent", "customer"]
}

OpenedParameter
If the information in the OpenParameter type websocket request is correct, Sestek will return OpenedParameter type websocket message in response to this request.
The parameter in this response will be StartPaused. It should be boolean type.
If this StartPaused is false, it means the stream should be started. If it is true, the stream should not be started.

##Example request:
{
	"type": "opened",
	"seq": 1,
	"server_seq": 1,
	"conversation_id": "",
	"media_format": "alaw", // alaw, ulaw
	"sample_rate": "8000",
	"media_channel": ["agent", "customer"],
	"start_paused": true
}

ResumeParameter
If StartPaused is true, an additional ResumeParameter request is sent to start the stream. Sestek will send this request to the integrated other party.

##Example request:
{
	"type": "resume",
	"seq": 1,
	"server_seq": 1,
	"conversation_id": "",
}

ResumedParameter
As a response to ResumeParameter, ResumedParameter should be returned if successful.

##Example request:
{
	"type": "resumed",
	"seq": 1,
	"server_seq": 1,
	"conversation_id": "",
}

Transfer Calls

Transfer scenario: In case a meeting is transferred, the two meetings are considered as two separate meetings, independent of each other. In this case, in case of transfer, it is expected that the first session will be closed and a new session will be started by opening a second websocket after the transfer.