Operatori

Gestisci gli operatori di chat all'interno delle tue organizzazioni ChatHub. Gli operatori sono agenti che gestiscono le conversazioni dei clienti.

Panoramica

Operatori in ChatHub:

Gestire le conversazioni chat dei clienti
Appartengono a organizzazioni specifiche
Avere lo stato attivo, inattivo o eliminato
Può avere token di autenticazione individuali
Ricevere e rispondere ai messaggi

Elenca gli operatori

Recupera tutti gli operatori per un'organizzazione specifica.

Punto finale

GET /api/operator?organizationId={id}

Richiesta

curl -X GET "https://chatapi.smsbat.com/api/operator?organizationId=24" \
  -H "Authorization: Bearer {company-token}" \
  -H "Accept: text/plain"

Parametri

Parametro	Digitare	Posizione	Obbligatorio	Descrizione
`IDorganizzazione`	intero	Domanda	Sì	ID organizzazione

Intestazioni

Intestazione	Valore	Obbligatorio
"Autorizzazione"	Portatore	Sì
"Accetta"	testo/semplice	Sì

Risposta

CODICE_BLOCCO_2

Campi di risposta

Campo	Digitare	Descrizione
`id`	intero	Identificatore univoco dell'operatore
`nome`	stringa	Nome visualizzato dall'operatore
`stato`	intero	Stato operatore (0=Attivo, 1=Inattivo, 2=Eliminato)
`organizzazione`	oggetto	Dettagli dell'organizzazione madre
`organizzazione.id`	intero	ID organizzazione
`nome.organizzazione`	stringa	Nome dell'organizzazione

Stato dell'operatore

Stato	Valore	Descrizione
Attivo	0	L'operatore sta attualmente lavorando e può ricevere chat
Inattivo	1	L'operatore è temporaneamente disabilitato
Eliminato	2	L'operatore è stato rimosso dal sistema

Aggiungi operatori

Aggiungi nuovi operatori alle organizzazioni utilizzando l'endpoint di sincronizzazione.

Punto finale

POST /api/operator/synchronize

Richiesta

curl -X POST https://chatapi.smsbat.com/api/operator/synchronize \
  -H "Authorization: Bearer {company-token}" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "organizationId": 24,
      "name": "Alex Brown"
    },
    {
      "organizationId": 24,
      "name": "Emma Davis"
    }
  ]'

Richiedi corpo

Matrice di oggetti operatore:

CODICE_BLOCCO_5

Campi richiesta

Campo	Digitare	Obbligatorio	Descrizione
`IDorganizzazione`	intero	Sì	ID organizzazione di destinazione
`nome`	stringa	Sì	Nome visualizzato dall'operatore

Risposta

CODICE_BLOCCO_6

Modifica lo stato dell'operatore

Aggiorna lo stato dell'operatore (Attivo/Inattivo/Eliminato).

Punto finale

CODICE_BLOCCO_7

Richiesta

curl -X POST https://chatapi.smsbat.com/api/operator/status \
  -H "Authorization: Bearer {company-token}" \
  -H "Content-Type: application/json" \
  -d '{
    "id": 104,
    "status": 1
  }'

Richiedi corpo

{
  "id": 0,
  "status": 0
}

Campi richiesta

Campo	Digitare	Obbligatorio	Descrizione
`id`	intero	Sì	ID operatore
`stato`	intero	Sì	Nuovo stato (0=Attivo, 1=Inattivo, 2=Eliminato)

Risposta

200 OK

L'esito positivo restituisce HTTP 200 senza corpo della risposta.

Valori di stato

Stato	Valore	Descrizione
Attivo	0	L'operatore può gestire le chat
Inattivo	1	Operatore temporaneamente disabilitato
Eliminato	2	Operatore rimosso dal sistema

Esempio: Disattiva operatore

curl -X POST https://chatapi.smsbat.com/api/operator/status \
  -H "Authorization: Bearer {company-token}" \
  -H "Content-Type: application/json" \
  -d '{
    "id": 104,
    "status": 1
  }'

Esempio: riattivazione dell'operatore

CODICE_BLOCCO_12

Esempio: Elimina operatore

curl -X POST https://chatapi.smsbat.com/api/operator/status \
  -H "Authorization: Bearer {company-token}" \
  -H "Content-Type: application/json" \
  -d '{
    "id": 104,
    "status": 2
  }'

Esempi di implementazione

Pitone

CODICE_BLOCCO_14

JavaScript (Node.js)

CODICE_BLOCCO_15

PHP

<?php

class OperatorManager {
    private $companyToken;
    private $baseUrl;

    public function __construct($companyToken, $baseUrl = 'https://chatapi.smsbat.com') {
        $this->companyToken = $companyToken;
        $this->baseUrl = $baseUrl;
    }

    public function listOperators($organizationId) {
        $url = $this->baseUrl . '/api/operator?organizationId=' . $organizationId;

        $ch = curl_init($url);
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer ' . $this->companyToken,
            'Accept: text/plain'
        ]);

        $response = curl_exec($ch);
        curl_close($ch);

        return json_decode($response, true);
    }

    public function addOperators($operators) {
        $ch = curl_init($this->baseUrl . '/api/operator/synchronize');

        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_POST, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer ' . $this->companyToken,
            'Content-Type: application/json',
            'Accept: text/plain'
        ]);
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($operators));

        $response = curl_exec($ch);
        curl_close($ch);

        return json_decode($response, true);
    }

    public function getActiveOperators($organizationId) {
        $operators = $this->listOperators($organizationId);
        return array_filter($operators, function($op) {
            return $op['status'] === 0;
        });
    }

    public function findOperatorByName($organizationId, $name) {
        $operators = $this->listOperators($organizationId);

        foreach ($operators as $operator) {
            if (strcasecmp($operator['name'], $name) === 0) {
                return $operator;
            }
        }

        return null;
    }

    public function changeOperatorStatus($operatorId, $status) {
        $ch = curl_init($this->baseUrl . '/api/operator/status');

        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_POST, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer ' . $this->companyToken,
            'Content-Type: application/json'
        ]);
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
            'id' => $operatorId,
            'status' => $status
        ]));

        $response = curl_exec($ch);
        $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
        curl_close($ch);

        return $httpCode === 200;
    }
}

// Usage
$manager = new OperatorManager('your-company-token');

// List operators
$operators = $manager->listOperators(24);
echo "Found " . count($operators) . " operators\n";

// Get active operators
$active = $manager->getActiveOperators(24);
echo count($active) . " active operators\n";

// Add new operators
$newOperators = $manager->addOperators([
    ['organizationId' => 24, 'name' => 'John Doe'],
    ['organizationId' => 24, 'name' => 'Jane Smith']
]);
echo "Added " . count($newOperators) . " operators\n";

// Find operator
$operator = $manager->findOperatorByName(24, 'John Doe');
if ($operator) {
    echo "Found: " . $operator['name'] . " (ID: " . $operator['id'] . ")\n";
}

// Change operator status
$manager->changeOperatorStatus(104, 1); // Deactivate
echo "Operator deactivated\n";

$manager->changeOperatorStatus(104, 0); // Reactivate
echo "Operator reactivated\n";

Casi d'uso comuni

Integra nuovi membri del team

CODICE_BLOCCO_17

Monitora lo stato dell'operatore

CODICE_BLOCCO_18

Bilanciamento del carico

CODICE_BLOCCO_19

Importazione in blocco

CODICE_BLOCCO_20

Migliori pratiche

Gestione degli errori

async function addOperatorsSafely(operators) {
  try {
    return await addOperators(operators);
  } catch (error) {
    if (error.response?.status === 400) {
      console.error('Invalid operator data:', error.response.data);
      // Handle validation errors
    } else if (error.response?.status === 401) {
      console.error('Authentication failed');
      // Refresh token
    } else {
      console.error('Unexpected error:', error);
    }

    throw error;
  }
}

Memorizzazione nella cache

CODICE_BLOCCO_22

Convalida

function validateOperatorData(operators) {
  const errors = [];

  operators.forEach((op, index) => {
    if (!op.organizationId) {
      errors.push(`Operator ${index}: Missing organizationId`);
    }

    if (!op.name || op.name.trim().length === 0) {
      errors.push(`Operator ${index}: Name is required`);
    }

    if (op.name && op.name.length > 100) {
      errors.push(`Operator ${index}: Name too long (max 100 chars)`);
    }
  });

  if (errors.length > 0) {
    throw new Error('Validation failed:\n' + errors.join('\n'));
  }
}

// Usage
try {
  validateOperatorData(operatorData);
  await addOperators(operatorData);
} catch (error) {
  console.error(error.message);
}

Limitazione della velocità

CODICE_BLOCCO_24

Risoluzione dei problemi

Nessun operatore restituito

Verificare che l'ID organizzazione sia corretto
Verificare che l'organizzazione esista e abbia operatori
Garantire che il token aziendale abbia accesso all'organizzazione

Impossibile aggiungere gli operatori

Verificare che l'ID organizzazione esista
Controllare il formato del nome dell'operatore
Assicurarsi che il token aziendale sia valido
Verificare che il formato JSON sia corretto

401 Non autorizzato

Verificare che il token aziendale sia valido
Controlla che il token non sia scaduto
Richiedi un nuovo token se necessario

Operatori duplicati

L'endpoint di sincronizzazione può consentire nomi duplicati. Implementare la deduplicazione:

CODICE_BLOCCO_25

Passaggi successivi

Autenticazione - Ottieni token operatore
Organizzazioni - Gestisci le organizzazioni
Integrazione widget - Integra il widget chat