Skip to main content
Version: Latest

Workspaces and sessions

A workspace belongs to one application and contains the Agent's knowledge, model and tools. Configure the workspace and model in the Hub dashboard, then use the application's API key to discover its ID:

curl 'https://app.chatt2.me/v1/agent/workspaces' \
  -H 'x-api-key: YOUR_APPLICATION_API_KEY'

The 200 response is an array of workspaces, each with id, applicationId, name, model identifiers and storage/count fields. An application key already determines the scope; no applicationId query is needed. An empty array means this application has no workspaces. Save the chosen id as WORKSPACE_UUID. Use it as workspaceId when configuring the channel Agent.

A message webhook's payload.message.sessionId is the session UUID for the conversation. Save it as SESSION_UUID; it is separate from the message ID. A session belongs to the channel and visitor and can reference the channel's workspace. Its states are active (Agent handling), awaiting_human, transferred (external handling), closed and expired. The following operations are scoped to the API key's application; unknown or inaccessible IDs return 404.

Read and configure tools​

The application API exposes business_hours and queue_routing. Google Calendar connection, service configuration and publication are managed in the dashboard; this API does not expose that tool.

curl 'https://app.chatt2.me/v1/agent/workspaces/WORKSPACE_UUID/tools' \
  -H 'x-api-key: YOUR_APPLICATION_API_KEY'

The 200 response is an array of saved tools with toolType, enabled, config and hasCredentials. For example:

[
  {
    "toolType": "business_hours",
    "enabled": true,
    "config": {
      "timezone": "America/Sao_Paulo",
      "schedules": [
        { "day": "monday", "startTime": "09:00", "endTime": "18:00" }
      ]
    },
    "hasCredentials": false
  }
]

PUT /v1/agent/workspaces/{workspaceId}/tools/{toolType} replaces the complete configuration. Include all schedules or queues you intend to retain.

curl -X PUT 'https://app.chatt2.me/v1/agent/workspaces/WORKSPACE_UUID/tools/business_hours' \
  -H 'x-api-key: YOUR_APPLICATION_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "enabled": true,
    "config": {
      "timezone": "America/Sao_Paulo",
      "schedules": [
        { "day": "monday", "startTime": "09:00", "endTime": "18:00" },
        { "day": "tuesday", "startTime": "09:00", "endTime": "18:00" }
      ]
    }
  }'

Use a scheduling timezone such as America/Sao_Paulo. The timezone is trimmed, nonempty and at most 100 characters. day is a lowercase weekday from monday through sunday. Times use 24-hour HH:mm (00:00–23:59); endTime must be later than startTime. Each interval stays within one day: 22:00–02:00 is invalid. Send explicit schedules for each day you support.

Create queues without IDs; Hub generates UUID v4 IDs:

curl -X PUT 'https://app.chatt2.me/v1/agent/workspaces/WORKSPACE_UUID/tools/queue_routing' \
  -H 'x-api-key: YOUR_APPLICATION_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "enabled": true,
    "config": {
      "queues": [
        { "name": "Support", "description": "Help with existing accounts and technical issues." },
        { "name": "Sales", "description": "Questions about plans and new purchases." }
      ]
    }
  }'

A 200 PUT response contains toolType, enabled and config, without the GET-only hasCredentials field. An illustrative queue response is:

{
  "toolType": "queue_routing",
  "enabled": true,
  "config": {
    "queues": [
      {
        "id": "3531b4db-70b6-4cc9-a66a-ceb1f96fa4c0",
        "name": "Support",
        "description": "Help with existing accounts and technical issues."
      },
      {
        "id": "ced0928d-610c-4a81-9e9a-6b1247afbb06",
        "name": "Sales",
        "description": "Questions about plans and new purchases."
      }
    ]
  }
}

Save the returned IDs, rather than inventing IDs for new queues. To rename or update a queue, submit its existing ID with name and description in the next complete replacement. Omit a queue to delete it. Supplied IDs must be existing UUID v4 IDs in that tool and cannot repeat. There are at most 100 queues; names and descriptions are trimmed, nonempty and limited to 100 and 500 characters. Names must be unique ignoring case. Unknown fields in the queue configuration or its items are rejected.

Invalid configurations return 400 AGENT_TOOL_CONFIG_VALIDATION. Inspect errors for field paths such as queues.0.name, a stable field code (for example REQUIRED_FIELD, INVALID_FIELD, FIELD_TOO_LONG or DUPLICATE_VALUE) and optional safe bounds. See the tool configuration reference for the full response.

Move an already transferred session​

POST /v1/agent/sessions/{sessionId}/transfer changes the queue of a session whose status is already transferred. It does not initiate Agent handoff. Use a queue ID saved from this session's workspace and keep the queue-routing tool enabled.

curl -X POST 'https://app.chatt2.me/v1/agent/sessions/SESSION_UUID/transfer' \
  -H 'x-api-key: YOUR_APPLICATION_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"queueId":"3531b4db-70b6-4cc9-a66a-ceb1f96fa4c0"}'

The 200 response is:

{
  "sessionId": "76c70ac5-4bd9-43dc-8af9-7de4f8f1f0e4",
  "status": "transferred",
  "queue": {
    "id": "3531b4db-70b6-4cc9-a66a-ceb1f96fa4c0",
    "name": "Support"
  }
}

A changed queue emits a subscribed session_transfer event with reason manual_queue_transfer; selecting the current queue is a successful no-op. 400 SESSION_NOT_TRANSFERRED means the lifecycle state is unsuitable; QUEUE_ROUTING_NOT_CONFIGURED means the enabled tool is missing; QUEUE_ROUTING_QUEUE_UNKNOWN means the queue ID is not configured. See the transfer reference.

Close a session​

Close an active, awaiting_human or transferred session before evaluating its CX Score:

curl -X POST 'https://app.chatt2.me/v1/agent/sessions/SESSION_UUID/close' \
  -H 'x-api-key: YOUR_APPLICATION_API_KEY'

The 200 response is:

{
  "sessionId": "76c70ac5-4bd9-43dc-8af9-7de4f8f1f0e4",
  "status": "closed"
}

Closing an already closed session is a no-op. An expired session stays expired and returns that status. See the close reference. For draft replies during an ongoing conversation, use Session Assist.