Endpoint API della piattaforma di chat

Gli endpoint API della piattaforma di chat forniscono l'accesso agli oggetti della chat. Viene creato un oggetto chat per ogni chat inviata e ricevuta da Contact Center AI Platform (CCAI Platform).

Di seguito sono riportati gli endpoint API della piattaforma di chat:

Oggetto chat

Viene creato un oggetto chat per ogni sessione di chat mobile e web su CCAI Platform. Di seguito è riportato l'oggetto della chat:

{
    "id": "integer",
    "status": "string",
    "status_text": "string",
    "features": [
        "string",
        "string"
    ],
    "created_at": "string",
    "ends_at": "string",
    "timeout_at": "string",
    "agent": {
        "id": "integer",
        "name": "string",
        "first_name": "string",
        "avatar_url": "string",
        "status": "string"
    },
    "virtual_agent": {
        "id": "integer",
        "name": "string",
        "avatar_url": "string",
        "status": "string"
    },
    "all_agents": [
        {
            "id": "integer",
            "name": "string",
            "first_name": "string",
            "avatar_url": "string",
            "status": "string"
        },
        {
            "id": "integer",
            "name": "string",
            "first_name": "string",
            "avatar_url": "string",
            "status": "string"
        }
    ],
    "all_virtual_agents": [
        {
            "id": "integer",
            "name": "string",
            "avatar_url": "string",
            "status": "string"
        },
        {
            "id": "integer",
            "name": "string",
            "avatar_url": "string",
            "status": "string"
        }
    ],
    "lang": "string",
    "menus": [
        {
            "id": "integer",
            "name": "string"
        },
        {
            "id": "integer",
            "name": "string"
        }
    ],
    "end_user": {
        "id": "integer",
        "identifier": "string"
    }
}

Aggiornare una chat

Parametro Obbligatorio Tipo di dati Definizione
id VERO Numero intero L'ID della chat da aggiornare

Endpoint:

Method: PATCH
Type: RAW
URL: https://{subdomain}.​{domain}​/apps/api/v1/chats/:id

Intestazioni:

Chiave Valore Descrizione
Content-Type application/json
Accetta application/json

Corpo:

{
    "finished_by_user_id": "integer",
    "chat": {
        "deflection_channel": "string",
        "status": "string",
        "escalation_id": "integer"
    }
}

Esempio di richiesta e risposte

Le sezioni seguenti forniscono richieste di esempio all'endpoint.

Aggiornare una chat

Questo esempio mostra l'aggiornamento riuscito di una chat esistente

Richiesta

Intestazioni:

Chiave Valore Descrizione
Content-Type application/json
Accetta application/json

Query:

Chiave Valore Descrizione
id Numero intero (Obbligatorio)

Corpo:

{
    "finished_by_user_id": "integer",
    "chat": {
        "deflection_channel": "string",
        "status": "finished",
        "escalation_id": "integer"
    }
}
Risposta
{
    "id": "integer",
    "status": "string",
    "status_text": "string",
    "features": [
        "string",
        "string"
    ],
    "created_at": "string",
    "ends_at": "string",
    "timeout_at": "string",
    "agent": {
        "id": "integer",
        "name": "string",
        "first_name": "string",
        "avatar_url": "string",
        "status": "string"
    },
    "virtual_agent": {
        "id": "integer",
        "name": "string",
        "avatar_url": "string",
        "status": "string"
    },
    "all_agents": [
        {
            "id": "integer",
            "name": "string",
            "first_name": "string",
            "avatar_url": "string",
            "status": "string"
        },
        {
            "id": "integer",
            "name": "string",
            "first_name": "string",
            "avatar_url": "string",
            "status": "string"
        }
    ],
    "all_virtual_agents": [
        {
            "id": "integer",
            "name": "string",
            "avatar_url": "string",
            "status": "string"
        },
        {
            "id": "integer",
            "name": "string",
            "avatar_url": "string",
            "status": "string"
        }
    ],
    "lang": "string",
    "menus": [
        {
            "id": "integer",
            "name": "string"
        },
        {
            "id": "integer",
            "name": "string"
        }
    ],
    "end_user": {
        "id": "integer",
        "identifier": "string"
    }
}

Codice di stato: 200

Inviare un messaggio in una chat

Questo metodo consente di inviare un messaggio in una sessione di chat esistente.

Parametro Obbligatorio Tipo di dati Definizione
id VERO Numero intero L'ID chat in cui deve essere inviato il messaggio.

Endpoint:

Method: POST
Type: RAW
URL: https://{subdomain}.​{domain}​/apps/api/v1/chats/:id/message

Intestazioni:

Chiave Valore Descrizione
Content-Type application/json

Corpo:

{
    "from_user_id": integer,
    "message": {
            "type": "string",
            "content": "string"
            }
    }
}

Esempio di richiesta e risposte

Le sezioni seguenti forniscono richieste di esempio all'endpoint.

Invio del messaggio riuscito

Questo esempio mostra l'invio riuscito di un messaggio a una sessione di chat esistente.

Richiesta

Intestazioni:

Chiave Valore Descrizione
Content-Type application/json
Accetta application/json

Query:

Chiave Valore Descrizione
id Numero intero (Obbligatorio)

Corpo:

{
    "from_user_id": integer,
    "message": {
            "type": "string",
            "content": : "string"
            }
    }
}
Risposta
{
}

Codice di stato: 200

Riassegnare la chat dell'agente virtuale

Riassegna una chat da un agente virtuale a un agente umano.

Parametro Obbligatorio Tipo di dati Definizione
chat_id VERO Numero intero L'ID chat richiesto per la riassegnazione.

Endpoint:

Method: POST
Type: RAW
URL: https://{subdomain}.​{domain}​/apps/api/v1/chats/:chat_id/escalations

Intestazioni:

Chiave Valore Descrizione
Content-Type application/json
Accetta application/json

Corpo:

{
    "reason": "string",
    "force_escalate": "boolean"
}

Esempio di richiesta e risposte

Le sezioni seguenti forniscono richieste di esempio all'endpoint.

Riassegnazione della richiesta via chat riuscita

Questo esempio mostra la richiesta di riassegnazione di una chat esistente a un operatore umano.

Richiesta

Intestazioni:

Chiave Valore Descrizione
Content-Type application/json
Accetta application/json

Query:

Chiave Valore Descrizione
chat_id Numero intero (Obbligatorio)

Corpo:

{
    "reason": "by_end_user_ask",
    "force_escalate": true
}
Risposta
{
    "id": "integer",
    "chat_id": "integer",
    "status": "string"
}

Codice di stato: 200

Aggiornamento della riassegnazione

Utilizzato solo per selezionare il canale di deviazione.

Parametro Obbligatorio Tipo di dati Definizione
chat_id VERO Numero intero L'ID chat richiesto per aggiornare l'ID menu di deviazione.
id VERO Numero intero L'ID menu richiesto.

Endpoint:

Method: PATCH
Type: RAW
URL: https://{subdomain}.​{domain}​/apps/api/v1/chats/:chat_id/escalations/:id

Intestazioni:

Chiave Valore Descrizione
Content-Type application/json

Corpo:

{
    "deflection_channel": "string"
}

Esempio di richiesta e risposte

Le sezioni seguenti forniscono richieste di esempio all'endpoint.

Aggiornamento della riassegnazione riuscito

Questo esempio mostra un aggiornamento riuscito del canale di riassegnazione.

Richiesta

Intestazioni:

Chiave Valore Descrizione
Content-Type application/json
Accetta application/json

Query:

Chiave Valore Descrizione
chat_id Numero intero (Obbligatorio)
id Numero intero (Obbligatorio)

Corpo:

{
    "deflection_channel": "string"
}
Risposta
{
    "id": "integer",
    "chat_id": "integer",
    "status": "string"
}

Codice di stato: 200

Aggiungere la foto caricata alla chat

Aggiungere a una chat una foto caricata in uno spazio di archiviazione multimediale

Parametro Obbligatorio Tipo di dati Definizione
chat_id VERO Numero intero L'ID chat richiesto a cui aggiungere la foto.

Endpoint:

Method: POST
Type: RAW
URL: https://{subdomain}.​{domain}/apps/api/v1/chats/:chat_id/photos

Intestazioni:

Chiave Valore Descrizione
Content-Type application/json
Accetta application/json

Corpo:

{
    "photo": [
        {
            "s3_path": "string",
            "photo_type": "string"
        },
        {
            "s3_path": "string",
            "photo_type": "string"
        }
    ]
}

Esempio di richiesta e risposte

Le sezioni seguenti forniscono richieste di esempio all'endpoint.

Foto aggiunta alla chat

L'esempio seguente mostra l'aggiunta di una foto caricata in uno spazio di archiviazione multimediale a una conversazione di chat esistente.

Richiesta

Intestazioni:

Chiave Valore Descrizione
Content-Type application/json
Accetta application/json

Query:

Chiave Valore Descrizione
chat_id Numero intero (Obbligatorio)

Corpo:

{
    "photo": [
        {
            "s3_path": "string",
            "photo_type": "string"
        },
        {
            "s3_path": "string",
            "photo_type": "string"
        }
    ]
}
Risposta
{
    "url": "string",
    "media_id": "integer"
}

Codice di stato: 200

Recuperare tutte le foto dalla chat

Recupera l'ID media e l'URL di archiviazione di tutte le foto allegate alla chat.

Parametro Obbligatorio Tipo di dati Definizione
chat_id VERO Numero intero L'ID chat richiesto per ottenere le informazioni sui contenuti multimediali.

Endpoint:

Method: GET
Type:
URL: https://{subdomain}.​{domain}​/apps/api/v1/chats/:chat_id/photos

Intestazioni:

Chiave Valore Descrizione
Accetta application/json

Esempio di richiesta e risposte

Le sezioni seguenti forniscono richieste di esempio all'endpoint.

Recupero riuscito delle informazioni sulla foto di una chat

Questo esempio mostra una chiamata riuscita all'API per ottenere le informazioni sulla foto per una sessione di chat esistente.

Richiesta

Intestazioni:

Chiave Valore Descrizione
Accetta application/json

Query:

Chiave Valore Descrizione
chat_id Numero intero (Obbligatorio)
Risposta
[
    {
        "url": "string",
        "media_id": "integer"
    },
    {
        "url": "string",
        "media_id": "integer"
    }
]

Codice di stato: 200

Recuperare l'URL di caricamento delle foto pre-firmato

Utilizzato per ottenere un URL di caricamento pre-firmato per le foto.

Parametro Obbligatorio Tipo di dati Definizione
chat_id VERO Numero intero L'ID chat obbligatorio che verrà associato all'URL della foto pre-firmato.

Endpoint:

Method: POST
Type: RAW
URL: https://{subdomain}.​{domain}​/apps/api/v1/chats/:chat_id/photos/upload

Intestazioni:

Chiave Valore Descrizione
Content-Type application/json
Accetta application/json

Esempio di richiesta e risposte

Le sezioni seguenti forniscono richieste di esempio all'endpoint.

Recupero riuscito dell'URL firmato per il caricamento

Di seguito è riportato un esempio di richiesta riuscita con recupero di un URL firmato per il caricamento di foto.

Richiesta

Intestazioni:

Chiave Valore Descrizione
Accetta application/json

Query:

Chiave Valore Descrizione
chat_id Numero intero (Obbligatorio)
Risposta
{
    "url": "string",
    "fields": {
        "key": "string",
        "success_action_status": "string",
        "Content-Type": "string",
        "Cache-Control": "string",
        "acl": "string",
        "policy": "string",
        "x-amz-credential": "string",
        "x-amz-algorithm": "string",
        "x-amz-date": "string",
        "x-amz-security-token": "string",
        "x-amz-signature": "string",
        "x-goog-algorithm": "string",
        "x-goog-credential": "string",
        "x-goog-date": "string",
        "x-goog-signature": "string"
    }
}

Codice di stato: 200

Aggiungere il video caricato alla chat

Aggiungi a una chat un video caricato nello spazio di archiviazione dei contenuti multimediali.

Parametro Obbligatorio Tipo di dati Definizione
chat_id VERO Numero intero L'ID chat obbligatorio a cui deve essere associato il video.

Endpoint:

Method: POST
Type: RAW
URL: https://{subdomain}.​{domain}​/apps/api/v1/chats/:chat_id/videos

Intestazioni:

Chiave Valore Descrizione
Content-Type application/json
Accetta application/json

Corpo:

{
    "video": {
        "s3_path": "string",
        "gcs_path": "string"
    }
}

Esempio di richiesta e risposte

Le sezioni seguenti forniscono richieste di esempio all'endpoint.

Caricamento riuscito di un video in una sessione di chat

Questo esempio mostra il caricamento riuscito di un video in una sessione di chat.

Richiesta

Intestazioni:

Chiave Valore Descrizione
Accetta application/json

Query:

Chiave Valore Descrizione
chat_id Numero intero (Obbligatorio)

Corpo:

{
    "photo": [
        {
            "s3_path": "string",
            "photo_type": "string"
        },
        {
            "s3_path": "string",
            "photo_type": "string"
        }
    ]
}
Risposta
Body
{
    "url": "string",
    "media_id": "integer"
}

Codice di stato: 200

Recuperare tutti i video dalla chat

Recupera l'ID media e l'URL di archiviazione di tutti i video allegati alla chat.

Parametro Obbligatorio Tipo di dati Definizione
chat_id VERO Numero intero L'ID chat obbligatorio per cui verranno recuperati gli URL dei video.

Endpoint:

Method: GET
Type:
URL: https://{subdomain}.​{domain}​/apps/api/v1/chats/:chat_id/videos

Intestazioni:

Chiave Valore Descrizione
Content-Type application/json
Accetta application/json

Esempio di richiesta e risposte

Le sezioni seguenti forniscono richieste di esempio all'endpoint.

Recuperare tutti gli URL dei video per una chat

Questo esempio mostra il recupero di tutti gli URL dei video per una chat esistente.

Richiesta

Intestazioni:

Chiave Valore Descrizione
Accetta application/json

Query:

Chiave Valore Descrizione
chat_id Numero intero (Obbligatorio)
Risposta
[
    {
        "url": "string",
        "media_id": "integer"
    },
    {
        "url": "string",
        "media_id": "integer"
    }
]

Codice di stato: 200

Recuperare l'URL di caricamento del video pre-firmato

Utilizzato per ottenere un URL di caricamento pre-firmato per i video.

Parametro Obbligatorio Tipo di dati Definizione
chat_id VERO Numero intero L'ID chat obbligatorio che verrà associato all'URL del video pre-firmato.

Endpoint:

Method: POST
Type: RAW
URL: https://{subdomain}.​{domain}​/apps/api/v1/chats/:chat_id/videos/upload

Intestazioni:

Chiave Valore Descrizione
Content-Type application/json
Accetta application/json

Esempio di richiesta e risposte

Le sezioni seguenti forniscono richieste di esempio all'endpoint.

Recupero riuscito dell'URL firmato per il caricamento del video

Di seguito è riportato un esempio di richiesta riuscita con recupero di un URL firmato per il caricamento di video.

Richiesta

Intestazioni:

Chiave Valore Descrizione
Accetta application/json

Query:

Chiave Valore Descrizione
chat_id Numero intero (Obbligatorio)
Risposta
{
    "url": "string",
    "fields": {
        "key": "string",
        "success_action_status": "string",
        "Content-Type": "string",
        "Cache-Control": "string",
        "acl": "string",
        "policy": "string",
        "x-amz-credential": "string",
        "x-amz-algorithm": "string",
        "x-amz-date": "string",
        "x-amz-security-token": "string",
        "x-amz-signature": "string",
        "x-goog-algorithm": "string",
        "x-goog-credential": "string",
        "x-goog-date": "string",
        "x-goog-signature": "string"
    }
}

Codice di stato: 200

Creare una chat

Avvia una nuova sessione di chat.

Esempio di richiesta

Metodo: POST

URL: https://{subdomain}.{domain}/apps/api/v1/chats

Intestazioni

Chiave Valore Descrizione
Content-Type application/json
Accetta application/json

Corpo

{
    "chat": {
        "menu_id": "integer",
        "end_user_id": "integer",
        "lang": "string",
        "email": "string",
        "context": "object",
        "transcript": "object"
    },
    "end_user": {
        "phone": "string"
    }
}

Contesto:

L'oggetto context include l'oggetto value, che passa i metadati alla conversazione di chat. Puoi trasmettere l'oggetto context agli agenti virtuali come parametro di dati non firmato. Vedi il seguente esempio:

{
    "context": {
        {"value":
            {"foo": "bar",
             "key": "value"}
        }
    }
}

In questo esempio, il valore parametro di dati non firmati per il campo in entrata è context e il campo di destinazione potrebbe essere impostato su context. In questo modo potrai utilizzare $session.params.context.foo o $session.params.context.key.

Esempio di risposta

{
    "id": "integer",
    "status": "string",
    "status_text": "string",
    "features": [
        "string",
        "string"
    ],
    "created_at": "string",
    "ends_at": "string",
    "timeout_at": "string",
    "agent": {
        "id": "integer",
        "name": "string",
        "first_name": "string",
        "avatar_url": "string",
        "status": "string"
    },
    "virtual_agent": {
        "id": "integer",
        "name": "string",
        "avatar_url": "string",
        "status": "string"
    },
    "all_agents": [
        {
            "id": "integer",
            "name": "string",
            "first_name": "string",
            "avatar_url": "string",
            "status": "string"
        },
        {
            "id": "integer",
            "name": "string",
            "first_name": "string",
            "avatar_url": "string",
            "status": "string"
        }
    ],
    "all_virtual_agents": [
        {
            "id": "integer",
            "name": "string",
            "avatar_url": "string",
            "status": "string"
        },
        {
            "id": "integer",
            "name": "string",
            "avatar_url": "string",
            "status": "string"
        }
    ],
    "lang": "string",
    "menus": [
        {
            "id": "integer",
            "name": "string"
        },
        {
            "id": "integer",
            "name": "string"
        }
    ],
    "end_user": {
        "id": "integer",
        "identifier": "string"
    }
}

Restituisce una chat in base all'ID

Questo metodo restituisce l'oggetto chat per un determinato ID chat.

Endpoint:

Method: GET
Type:
URL: https://{subdomain}.​{domain}/apps/api/v1/chats/:id

Intestazioni:

Chiave Valore Descrizione
Content-Type application/json
Accetta application/json

Query:

Chiave Valore Descrizione
chat_id Numero intero (Obbligatorio)

Esempio di richiesta e risposte

Le sezioni seguenti forniscono richieste di esempio all'endpoint.

Recuperare una chat

L'esempio seguente mostra la richiesta riuscita di un ID chat esistente.

Richiesta

Intestazioni:

Chiave Valore Descrizione
Content-type application/json
Accetta application/json

Query:

Chiave Valore Descrizione
chat_id Numero intero (Obbligatorio)
Risposta
{
    "id": "integer",
    "status": "string",
    "status_text": "string",
    "features": [
        "string",
        "string"
    ],
    "created_at": "string",
    "ends_at": "string",
    "timeout_at": "string",
    "agent": {
        "id": "integer",
        "name": "string",
        "first_name": "string",
        "avatar_url": "string",
        "status": "string"
    },
    "virtual_agent": {
        "id": "integer",
        "name": "string",
        "avatar_url": "string",
        "status": "string"
    },
    "all_agents": [
        {
            "id": "integer",
            "name": "string",
            "first_name": "string",
            "avatar_url": "string",
            "status": "string"
        },
        {
            "id": "integer",
            "name": "string",
            "first_name": "string",
            "avatar_url": "string",
            "status": "string"
        }
    ],
    "all_virtual_agents": [
        {
            "id": "integer",
            "name": "string",
            "avatar_url": "string",
            "status": "string"
        },
        {
            "id": "integer",
            "name": "string",
            "avatar_url": "string",
            "status": "string"
        }
    ],
    "lang": "string",
    "menus": [
        {
            "id": "integer",
            "name": "string"
        },
        {
            "id": "integer",
            "name": "string"
        }
    ],
    "end_user": {
        "id": "integer",
        "identifier": "string"
    }
}

Codice di stato: 200

Recuperare gli attributi dei dati riservati durante una chat

Endpoint

Method: GET
Type: RAW
URL: https://{subdomain}.{domain}/apps/api/v1/chats/:id/customer_flag

Esempio di richiesta e risposte

Questa sezione contiene una richiesta e una risposta di esempio per l'endpoint.

Operazione riuscita

Questo esempio mostra una chiamata riuscita.

Richiesta

Intestazioni

Chiave Valore Descrizione
Accetta application/json

Variabili URL

Chiave Valore Descrizione
id integer (Obbligatorio)
Risposta
{
    "verified_customer": "boolean",
    "bad_actor": "boolean",
    "repeat_customer": "boolean"
}

Codice di stato 0

Aggiornare gli attributi dei dati riservati durante una chat

Endpoint

Method: POST
Type: RAW
URL: https://{subdomain}.{domain}/apps/api/v1/chats/:id/customer_flag

Variabili URL

Chiave Valore Descrizione
id integer (Obbligatorio)

Body

{
    "verified_customer": "boolean",
    "bad_actor": "boolean",
    "repeat_customers": "boolean"
}

Inviare dati personalizzati nella chat

Inviare dati personalizzati in una chat.

Esempio di richiesta

Metodo: POST

URL: https//{subdomain}.{domain}/apps/api/v1/chats/:id/custom_data

Intestazioni

Chiave Valore Descrizione
Content-Type application/json

Variabili URL

Chiave Valore Descrizione
id (Obbligatorio)

Esempio di risposta

// Use unsecured parameter
{
"signed": false,
"data": {
// Start customer_flag fields
"reserved_verified_customer": {
"label": "LABEL 1",
"value": true
},
"reserved_bad_actor": {
"label": "LABEL 2",
"value": false
},
"reserved_repeat_customer": {
"label": "LABEL 3",
"value": true
},
// End customer_flag fields
"field1": {
"label": "LABEL 4",
"value": "dummy1"
},
"field2": {
"label": "LABEL 5",
"value": "dummy2"
}
}
}
// Use secured parameter
// {
// "signed": true,
// "signed_data": "eyJhbGciOiJIUzI1NiJ9.eyJjdXN0b21fZGF0YSI6eyJyZXNlcnZlZF92ZXJpZmllZF9jdXN0b21lciI6eyJ2YWx1ZSI6ZmFsc2V9LCJyZXNlcnZlZF9iYWRfYWN0b3IiOnsidmFsdWUiOnRydWV9LCJyZXNlcnZlZF9yZXBlYXRfY3VzdG9tZXIiOnsidmFsdWUiOmZhbHNlfSwiZmllbGQxIjp7InZhbHVlIjoiZHVtbXkxMTEifSwiZmllbGQyIjp7InZhbHVlIjoiZHVtbXkyMjIifX0sImV4cCI6MTcyOTY4MzU5MywiaWF0IjoxNzI5Njc5OTkzfQ.BMskgKTM3DbgrMLWjI46ZJ1K73H25JRd16SgHK0A1Ts"
// }
// ======================= How to create <signed_data> =======================
// payload = {
// "custom_data": {
// // Start customer_flag fields
// "reserved_verified_customer": {
// "label": "LABEL 1",
// "value": true
// },
// "reserved_bad_actor": {
// "label": "LABEL 2",
// "value": false
// },
// "reserved_repeat_customer": {
// "label": "LABEL 3",
// "value": true
// },
// // End customer_flag fields
// "field1": {
// "label": "LABEL 4",
// "value": "dummy1"
// },
// "field2": {
// "label": "LABEL 5",
// "value": "dummy2"
// }
// },
// "exp": 1734567890, // expiration timestamp
// "iat": 1734560000 // issue timestamp
// }
// signed_data = JWT.encode(payload, 'Company secret', 'HS256')
// ======================= End how to create <signed_data> =======================

Aggiornare l'utente finale durante la sessione di chat in corso

Aggiorna l'utente finale associato alla sessione di chat attiva corrente. Inoltre, aggiorna anche i dati di contatto collegati al ticket CRM. _Identifier è obbligatorio, mentre name, email e phone sono facoltativi.

Esempio di richiesta

Metodo: POST

URL: https//{subdomain}.{domain}/apps/api/v1/chats/:chat_id/end-user

Intestazioni

Chiave Valore Descrizione
Content-Type application/json

Variabili URL

Chiave Valore Descrizione
chat_id

Corpo

{
    "identifier": "string",
    "name": "string",
    "email": "string",
    "phone": "string"
}

Esempio di risposta

{
    "message": "accepted"
}