Portal API
Authentication
Authentication is handled via custom headers. You must include the following headers in your request:
Header Name | Required | Description |
---|---|---|
x-portal-secret | Yes | Your unique secret key. |
x-portal-external-customer-id | Optional | The unique identifier for a specific customer. Use to filter sessions for a single customer. |
Get Paginated Sessions
GET /api/v1/bff/sessions
{
"items": [
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"persona": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"actor_id": "123e4567-e89b-12d3-a456-426614174000",
"name": "string",
"external_id": "string",
"is_deleted": false
},
"integration_idn": "integration_idn",
"connector_idn": "connector_idn",
"created_at": "2024-01-01T12:00:00Z",
"arguments": {
"key1": "value1",
"key2": "value2"
},
"user_messages_count": 10,
"agent_messages_count": 5,
"messages_count": 15,
"events_count": 2,
"latest_message_datetime": "2024-01-01T12:10:00Z",
"latest_event_datetime": "2024-01-01T12:15:00Z",
"ended_at": "2024-01-01T12:30:00Z"
}
],
"metadata": {
"page": 1,
"per": 20,
"total": 20
}
}
Query Parameters:
Parameter Name | Data Type | Format | Required | Description |
---|---|---|---|---|
page | integer | - | Yes | The page number of the paginated response. |
per | integer | - | Yes | The number of items per page. |
from_datetime | string | date-time | Optional | Filter sessions starting from this datetime. |
to_datetime | string | date-time | Optional | Filter sessions up to this datetime. |
connectors | array | - | Optional | Filter by connector identifiers (e.g., sandbox, some_connector). |
is_active | boolean | - | Optional | Filter active sessions only. |
Response:
200 OK
– Successfully returns a paginated list of sessions.4XX
– Request error.
Get Sessions Info
This endpoint is used to retrieve statistical information about client sessions over a specified time period. It provides aggregated data suitable for display on dashboards and in analytical reports.
GET /api/v1/bff/sessions/info
GET
/api/v1/bff/sessions/info?from_datetime=2024-01-01T00:00:00Z&to_d
atetime=2024-01-31T23:59:59Z
Headers:
x-portal-secret: YOUR_SECRET_KEY
x-portal-external-customer-id: YOUR_CUSTOMER_ID (Optional)
{
"sessions_by_leads": {
"items": [
{
"date": "2024-01-01",
"total_sessions": 10,
"total_sessions_leads": 5
}
],
"total_sessions": 100,
"total_sessions_leads": 50
},
"sessions_by_type": {
"sessions_leads": [
{
"argument": "booking",
"total_sessions": 20
}
],
"sessions_non_leads": [
{
"argument": "support",
"total_sessions": 30
}
]
},
"sessions_by_channel": [
{
"channel": "chat",
"count": 70
},
{
"channel": "voice",
"count": 30
}
],
"sessions_by_hours": [
{
"hour": "working_hours",
"count": 80
},
{
"hour": "non_working_hours",
"count": 20
}
],
"sessions_by_asr": [
{
"date": "2024-01-01",
"asr_amount": 10.5
}
],
"summary": {
"asr": {
"non_working_hours": 2,
"working_hours": 8,
"total": 10
},
"revenue": {
"non_working_hours": 1000,
"working_hours": 4000,
"total": 5000
},
"sessions": {
"non_working_hours": 20,
"working_hours": 80,
"total": 100
},
"leads": {
"non_working_hours": 5,
"working_hours": 15,
"total": 20
},
"opportunity_sessions": {
"non_working_hours": 1,
"working_hours": 5,
"total": 6
},
"opportunity_value": {
"non_working_hours": 200,
"working_hours": 800,
"total": 1000
},
"additional_deal": {
"non_working_hours": 1,
"working_hours": 3,
"total": 4
},
"units": {
"non_working_hours": 50,
"working_hours": 150,
"total": 200
}
}
}
Query Parameters:
Parameter Name | Data Type | Format | Required | Description |
---|---|---|---|---|
from_datetime | string | date-time | Yes | The start date and time range for which to retrieve session data. |
to_datetime | string | date-time | Yes | The end date and time range for which to retrieve session data. |
Response:
200 OK
– Successfully returns a paginated list of sessions.4XX
– Request error.
{
"code": 400,
"type": "Bad Request",
"reason": "Invalid datetime format",
"errors": [
{
"message": "The 'from_datetime' parameter must be a valid
date-time string.",
"code": "invalid_parameter"
}
]
}
Data Schemas:
SessionsInfoDto
: Contains various session statistics, grouped for dashboard and analytical views.SessionsByDateDto
: Sessions data grouped by a specific date.- Properties:
date
: The date in YYYY-MM-DD format.total_sessions
: The total number of sessions on this date.total_sessions_leads
: The number of sessions marked as leads on this date.
- Properties:
SessionsByHourDto
: Sessions data grouped by hour category.- Properties:
hour
: The hour category (working_hours or non_working_hours).count
: The number of sessions in this category.
- Properties:
SessionsByChannelDto
: Sessions data grouped by communication channel.- Properties:
channel
: The communication channel (e.g., chat, voice).count
: The number of sessions for this channel.
- Properties:
SessionsByAsrDto
: Sessions data by date, including ASR (Automatic Speech Recognition) amount.- Properties:
date
: The date in YYYY-MM-DD format.asr_amount
: The total ASR amount for this date.
- Properties:
SessionsByArgumentDto
: A count of sessions grouped by a specific argument.- Properties:
argument
: The name of the argument.total_sessions
: The number of sessions associated with this argument.
- Properties:
SummaryDto
: A summary of key metrics.- Properties:
non_working_hours
: The count for non-working hours.working_hours
: The count for working hours.total
: The overall total count.
- Properties:
SessionsByLeads
: Sessions data summary defined as lead.- Properties:
items
: Summary in the sessions data grouped by date and time.total_sessions
: Total amount of sessions in date and time range.total_sessions_leads
: Total amount of sessions in date and time range defined as leads.
- Properties:
Retrieve Customer Attributes
GET /api/v1/bff/customer/attributes
{
"groups": ["group"],
"attributes": [
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"idn": "attribute_1",
"value": "value_1",
"title": "Title",
"description": "description",
"group": "group",
"is_hidden": false,
"possible_values": [],
"value_type": “string”,
},
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"idn": "attribute_2",
"value": "value_2",
"title": "Title 2",
"description": "description 2",
"group": "group",
"is_hidden": false,
"possible_values": [],
"value_type": “string”,
}
]
}
Query Parameters:
query (string, optional)
– Search query for name, title, or group.
Response:
200 OK
– Successfully returns a list of customer attributes.4XX
– Request error.
Get a Specific Customer Attribute by id
GET /api/v1/customer/attributes/{attribute_id}
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"idn": "attribute_1",
"value": "value",
"title": "Title",
"description": "description",
"group": "group",
"is_hidden": false,
"possible_values": [],
"value_type": "string"
}
Query Parameters:
attribute_id (UUID, required)
– The unique identifier of the attribute.
Response:
200 OK
– Attribute retrieved successfully.4XX
– Request error.
Update an Existing Customer Attribute
PUT /api/v1/customer/attributes/{attribute_id}
{
"value": "value",
"title": "Title",
"description": "description",
"group": "group",
"is_hidden": false,
"possible_values": [],
"value_type": "string"
}
Query Parameters:
attribute_id (UUID, required)
– The unique identifier of the attribute.
Response:
200 OK
– Attribute updated successfully.4XX
– Request error.
Updated 16 days ago