Overview

This guide walks you through managing support sessions in the Take Control platform. The Session API allows you to create new support sessions and retrieve historical session data. In this guide, you'll learn how to:

Create a new support session
Retrieve session history

Create Support Session

To initiate a new support session with a customer, use the Create Session endpoint. This allows you to set up immediate remote support connections with customizable parameters.

Required Header Parameters:

INTEGRATION-KEY: Your public integration key for authentication

Optional Request Parameters:

department_id: Specific department for the session
technician_username: Email of the assigned technician
language: Preferred session language (e.g., "fr" for French)
customer_name: Name of the customer
customer_email: Customer's email address
customer_number: Customer's reference number
problem_description: Description of the issue
ask_customer_info: Flag to request customer information
show_waiting_queue: Flag to display waiting queue status

Request

POST https://api.us0.swi-rc.com/rest/session
INTEGRATION-KEY: <YOUR_PUBLIC_KEY>
Content-Type: application/json

{
    "department_id": 123,
    "technician_username": "[email protected]",
    "language": "fr",
    "customer_name": "John Doe",
    "customer_email": "[email protected]",
    "customer_number": "d4f%d$3",
    "problem_description": "Unable to access network drive",
    "ask_customer_info": 1,
    "show_waiting_queue": 1
}

This request creates a new support session with a French-speaking customer named John Doe, assigning them to a specific technician and department. The system will collect additional customer information and show them their position in the waiting queue.

Response

Upon success, Take Control returns a 200 status code along with session details.

{
    "result": "SUCCESS",
    "details": {
        "nrequests": 22,
        "requests": [
            {
                "computer_name": "VM2",
                "computer_domain": "WORKGROUP",
                "tech_username": "[email protected]",
                "waiting_time": 1
            }
        ]
    }
}

Key points to note in the response:

nrequests: Total number of active requests
computer_name: Name of the customer's computer
computer_domain: Domain of the customer's computer
waiting_time: Estimated wait time in minutes

Retrieve Session History

To access historical session data, use the Get Session History endpoint. This allows you to analyze past support sessions with detailed filtering options.

Required Header Parameters:

INTEGRATION-KEY: Your private integration key for authentication

Request Parameters:

The request body allows you to specify:

Variables to retrieve (vars)
Filtering criteria (filters)

Request

GET https://api.us0.swi-rc.com/rest/session/history
INTEGRATION-KEY: <YOUR_PRIVATE_KEY>
Content-Type: application/json

{
    "vars": [
        "COMPUTER_NAME",
        "COMPUTER_DOMAIN",
        "COMPUTER_OS",
        "TECH_USERNAME",
        "TECH_NAME",
        "CUSTOMER_NAME",
        "CUSTOMER_EMAIL",
        "PROBLEM_DESCRIPTION",
        "DATE_START",
        "DATE_END"
    ],
    "filters": {
        "FILTER_DATE_START_INI": "2024-01-01 00:00:00",
        "FILTER_DATE_START_END": "2024-01-31 23:59:59",
        "FILTER_CUSTOMER_NAME": "John Doe",
        "FILTER_CUSTOMER_EMAIL": "[email protected]",
        "FILTER_COMPUTER_NAME": "VM2",
        "FILTER_TECH_USERNAME": "[email protected]",
        "FILTER_START_METHOD": "ALL",
        "FILTER_PROCESSED": "ALL",
        "FILTER_HAS_VIDEOS": true
    }
}

This request retrieves session history for January 2024, filtered by specific customer and technician information. It includes sessions with video recordings and pulls various session details like computer information, customer details, and session timestamps.

Response

The response includes the filtered session history data.

{
    "result": "SUCCESS",
    "details": [
        {
            "nrequests": 22,
            "requests": [
                {
                    "computer_name": "VM2",
                    "computer_domain": "WORKGROUP",
                    "tech_username": "[email protected]",
                    "waiting_time": 1
                }
            ]
        }
    ]
}

Key points to note in the response:

Array of session records matching the filter criteria
Each session includes requested variables specified in the vars array
Session details like computer information, technician details, and timing data

Error Handling

Both endpoints may return the following error codes:

400: Invalid request - Check your request parameters
403: Invalid key - Verify your integration key
429: Too many requests - Implement appropriate request rate limiting