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.

List Customers

GET /api/v2/account/customers

{
  "items": [
    {
      "idn": "customer_unique_name",
      "organization_name": "Acme Corp",
      "industry": ["Technology"],
      "logo": "base64_string...",
      "created_at": "2024-01-20T10:00:00Z",
      "status": "permanent",
      "project_stage": "production",
      "location_count": 5,
      "comment": "Key account",
      "contact_phone": "+15550199",
      "connector_phone_numbers": ["+15550200"],
      "connector_sms_numbers": [],
      "connector_chat_urls": [],
      "session_count": 150,
      "leads_success_score": 0.85,
      "conversations_success_score": 0.9,
      "units": 120.5,
      "external_customer_id": "ext_12345"
    }
  ],
  "metadata": {
    "page": 1,
    "per": 20,
    "total": 50
  }
}

Query Parameters:

Parameter Name	Data Type	Format	Required	Description
page	integer	-	Yes	Number of page.
per	integer	-	Yes	Items per page (Max: 100).
query	string	-	No	The query for search Customers.
sort_by	string	-	No	The sorting field and order.
stats_from_datetime	string	date-time	No	Start time to collect stats.
stats_to_datetime	string	date-time	No	End time to collect stats.
admin_view	boolean	-	No	Admin view mode.
status	string	-	No	Status filter (e.g., temporal, permanent).
project_stage	array	-	No	Project stage filter (e.g., lead, production).
owner	string	email	No	Owner filter.
technical_owner	string	email	No	Technical Owner filter.
account_manager	string	email	No	Account Manager filter.
referral	string	email	No	Referral filter.
project_idn	string	-	No	Project IDN filter.
project_version	string	-	No	Project Version filter.
organization_type	string	-	No	Filter by organization type.
tenant	string	-	No	Filter by tenant identifier.
is_utility	boolean	-	No	Filter by utility organization flag.

Response:

200 OK – Customers returned successfully.
4XX – Request error.

Get Multiple Sessions Info

GET /api/v1/bff/sessions/info/multiple

{
  "items": [
    {
      "external_customer_id": "cust_001",
      "sessions": [
        {
          "sessions_by_leads": {
            "items": [
              {
                "date": "2024-12-01",
                "total_sessions": 10,
                "total_sessions_leads": 10
              }
            ],
            "total_sessions": 10,
            "total_sessions_leads": 10
          },
          "sessions_by_type": {
            "sessions_leads": [
              {
                "argument": "working_hours",
                "total_sessions": 10
              }
            ],
            "sessions_non_leads": []
          },
          "sessions_by_channel": [
            {
              "channel": "chat",
              "count": 3
            }
          ],
          "sessions_by_asr": [
            {
              "date": "2024-12-01",
              "asr_amount": 10
            }
          ],
          "summary": {
            "revenue": {
              "non_working_hours": 10,
              "working_hours": 10,
              "total": 10
            },
            "sessions": {
              "non_working_hours": 10,
              "working_hours": 10,
              "total": 10
            },
            "leads": {
              "non_working_hours": 5,
              "working_hours": 5,
              "total": 10
            }
            // Additional summary fields: asr, opportunity_sessions, etc.
          }
        }
      ]
    }
  ]
}

Query Parameters:

Parameter Name	Data Type	Format	Required	Description
from_datetime	string	date-time	Yes	Start date/time for the session info.
to_datetime	string	date-time	Yes	End date/time for the session info.
external_customer_ids	array	-	No	List of external customer IDs to filter by.

Response:

200 OK – Info client sessions returned successfully.
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.
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.
SessionsByChannelDto: Sessions data grouped by communication channel.
- Properties:
  - channel: The communication channel (e.g., chat, voice).
  - count: The number of sessions for this channel.
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.
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.
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.
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.

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.

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.
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.
SessionsByChannelDto: Sessions data grouped by communication channel.
- Properties:
  - channel: The communication channel (e.g., chat, voice).
  - count: The number of sessions for this channel.
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.
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.
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.
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.

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.