Extremos de API de la plataforma de chat

Los extremos de la API de la plataforma de chat proporcionan acceso a los objetos de chat. Se crea un objeto de chat para cada chat que se realiza hacia y desde Contact Center AI Platform (CCAI Platform).

A continuación, se indican los extremos de la API de la plataforma de chat:

Objeto de chat

Se crea un objeto de chat para cada sesión de chat web y móvil en la plataforma de CCAI. A continuación, se muestra el objeto de 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"
    }
}

Actualiza un chat

Parámetro Obligatorio Tipo de datos Definición
id TRUE Número entero ID del chat que se actualizará

Endpoint:

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

Encabezados:

Clave Valor Descripción
Content-Type application/json
Aceptar application/json

Cuerpo:

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

Ejemplo de solicitud y respuestas

En las siguientes secciones, se proporcionan ejemplos de solicitudes al extremo.

Actualiza un chat

En este ejemplo, se muestra la actualización exitosa de un chat existente.

Solicitud

Encabezados:

Clave Valor Descripción
Content-Type application/json
Aceptar application/json

Consulta:

Clave Valor Descripción
id Número entero (Obligatorio)

Cuerpo:

{
    "finished_by_user_id": "integer",
    "chat": {
        "deflection_channel": "string",
        "status": "finished",
        "escalation_id": "integer"
    }
}
Respuesta
{
    "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"
    }
}

Código de estado: 200

Enviar un mensaje en un chat

Este método permite enviar un mensaje en una sesión de chat existente.

Parámetro Obligatorio Tipo de datos Definición
id TRUE Número entero Es el ID del chat en el que se debe enviar el mensaje.

Endpoint:

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

Encabezados:

Clave Valor Descripción
Content-Type application/json

Cuerpo:

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

Ejemplo de solicitud y respuestas

En las siguientes secciones, se proporcionan ejemplos de solicitudes al extremo.

Envío de mensaje exitoso

En este ejemplo, se muestra el envío correcto de un mensaje a una sesión de chat existente.

Solicitud

Encabezados:

Clave Valor Descripción
Content-Type application/json
Aceptar application/json

Consulta:

Clave Valor Descripción
id Número entero (Obligatorio)

Cuerpo:

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

Código de estado: 200

Cómo derivar el chat del agente virtual

Derivar un chat de un agente virtual a un agente humano

Parámetro Obligatorio Tipo de datos Definición
chat_id TRUE Número entero Es el ID de chat obligatorio para derivar el caso.

Endpoint:

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

Encabezados:

Clave Valor Descripción
Content-Type application/json
Aceptar application/json

Cuerpo:

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

Ejemplo de solicitud y respuestas

En las siguientes secciones, se proporcionan ejemplos de solicitudes al extremo.

Derivación exitosa del chat

En este ejemplo, se muestra la solicitud para derivar un chat existente a un agente humano.

Solicitud

Encabezados:

Clave Valor Descripción
Content-Type application/json
Aceptar application/json

Consulta:

Clave Valor Descripción
chat_id Número entero (Obligatorio)

Cuerpo:

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

Código de estado: 200

Actualización de la derivación

Solo se usa para seleccionar el canal de desvío.

Parámetro Obligatorio Tipo de datos Definición
chat_id TRUE Número entero Es el ID de chat obligatorio para actualizar el ID del menú de desvío.
id TRUE Número entero Es el ID del menú requerido.

Endpoint:

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

Encabezados:

Clave Valor Descripción
Content-Type application/json

Cuerpo:

{
    "deflection_channel": "string"
}

Ejemplo de solicitud y respuestas

En las siguientes secciones, se proporcionan ejemplos de solicitudes al extremo.

Actualización exitosa de la derivación

En este ejemplo, se muestra una actualización exitosa del canal de derivación.

Solicitud

Encabezados:

Clave Valor Descripción
Content-Type application/json
Aceptar application/json

Consulta:

Clave Valor Descripción
chat_id Número entero (Obligatorio)
id Número entero (Obligatorio)

Cuerpo:

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

Código de estado: 200

Agregar la foto subida al chat

Cómo agregar a un chat una foto que se subió al almacenamiento de medios

Parámetro Obligatorio Tipo de datos Definición
chat_id TRUE Número entero Es el ID de chat obligatorio para agregar la foto.

Endpoint:

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

Encabezados:

Clave Valor Descripción
Content-Type application/json
Aceptar application/json

Cuerpo:

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

Ejemplo de solicitud y respuestas

En las siguientes secciones, se proporcionan ejemplos de solicitudes al extremo.

Se agregó correctamente una foto al chat

En el siguiente ejemplo, se muestra la adición de una foto que se subió a un almacenamiento de medios a una conversación de chat existente.

Solicitud

Encabezados:

Clave Valor Descripción
Content-Type application/json
Aceptar application/json

Consulta:

Clave Valor Descripción
chat_id Número entero (Obligatorio)

Cuerpo:

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

Código de estado: 200

Recupera todas las fotos del chat

Obtiene el ID de los medios y la URL de almacenamiento de todas las fotos adjuntas al chat.

Parámetro Obligatorio Tipo de datos Definición
chat_id TRUE Número entero Es el ID de chat obligatorio para obtener la información del contenido multimedia.

Endpoint:

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

Encabezados:

Clave Valor Descripción
Aceptar application/json

Ejemplo de solicitud y respuestas

En las siguientes secciones, se proporcionan ejemplos de solicitudes al extremo.

Se recuperó correctamente la información de la foto de un chat.

En este ejemplo, se muestra una llamada exitosa a la API para obtener la información de la foto de una sesión de chat existente.

Solicitud

Encabezados:

Clave Valor Descripción
Aceptar application/json

Consulta:

Clave Valor Descripción
chat_id Número entero (Obligatorio)
Respuesta
[
    {
        "url": "string",
        "media_id": "integer"
    },
    {
        "url": "string",
        "media_id": "integer"
    }
]

Código de estado: 200

Obtén una URL de carga de fotos previamente firmada

Se usa para obtener una URL de carga previa firmada para las fotos.

Parámetro Obligatorio Tipo de datos Definición
chat_id TRUE Número entero Es el ID de chat obligatorio que se asociará con la URL de la foto previa a la firma.

Endpoint:

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

Encabezados:

Clave Valor Descripción
Content-Type application/json
Aceptar application/json

Ejemplo de solicitud y respuestas

En las siguientes secciones, se proporcionan ejemplos de solicitudes al extremo.

Se recuperó correctamente la URL firmada para la carga

A continuación, se muestra un ejemplo de una solicitud exitosa con la recuperación de una URL firmada para la carga de fotos.

Solicitud

Encabezados:

Clave Valor Descripción
Aceptar application/json

Consulta:

Clave Valor Descripción
chat_id Número entero (Obligatorio)
Respuesta
{
    "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"
    }
}

Código de estado: 200

Agrega el video subido al chat

Agrega a un chat un video que se subió al almacenamiento de contenido multimedia.

Parámetro Obligatorio Tipo de datos Definición
chat_id TRUE Número entero Es el ID de chat obligatorio con el que se debe asociar el video.

Endpoint:

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

Encabezados:

Clave Valor Descripción
Content-Type application/json
Aceptar application/json

Cuerpo:

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

Ejemplo de solicitud y respuestas

En las siguientes secciones, se proporcionan ejemplos de solicitudes al extremo.

Se subió correctamente un video a una sesión de chat

En este ejemplo, se muestra la carga exitosa de un video en una sesión de chat.

Solicitud

Encabezados:

Clave Valor Descripción
Aceptar application/json

Consulta:

Clave Valor Descripción
chat_id Número entero (Obligatorio)

Cuerpo:

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

Código de estado: 200

Recupera todos los videos del chat

Obtiene el ID de medios y la URL de almacenamiento de todos los videos adjuntos al chat.

Parámetro Obligatorio Tipo de datos Definición
chat_id TRUE Número entero Es el ID de chat obligatorio para el que se recuperarán las URLs de los videos.

Endpoint:

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

Encabezados:

Clave Valor Descripción
Content-Type application/json
Aceptar application/json

Ejemplo de solicitud y respuestas

En las siguientes secciones, se proporcionan ejemplos de solicitudes al extremo.

Recupera todas las URLs de video de un chat

En este ejemplo, se muestra la recuperación de todas las URLs de video de un chat existente.

Solicitud

Encabezados:

Clave Valor Descripción
Aceptar application/json

Consulta:

Clave Valor Descripción
chat_id Número entero (Obligatorio)
Respuesta
[
    {
        "url": "string",
        "media_id": "integer"
    },
    {
        "url": "string",
        "media_id": "integer"
    }
]

Código de estado: 200

Obtén la URL de carga de video previamente firmada

Se usa para obtener una URL de carga previa firmada para videos.

Parámetro Obligatorio Tipo de datos Definición
chat_id TRUE Número entero Es el ID de chat obligatorio que se asociará con la URL de video previa a la firma.

Endpoint:

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

Encabezados:

Clave Valor Descripción
Content-Type application/json
Aceptar application/json

Ejemplo de solicitud y respuestas

En las siguientes secciones, se proporcionan ejemplos de solicitudes al extremo.

Se recuperó correctamente la URL firmada para la carga de video

El siguiente es un ejemplo de una solicitud correcta con la recuperación de una URL firmada para la carga de un video.

Solicitud

Encabezados:

Clave Valor Descripción
Aceptar application/json

Consulta:

Clave Valor Descripción
chat_id Número entero (Obligatorio)
Respuesta
{
    "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"
    }
}

Código de estado: 200

Crear chat

Inicia una nueva sesión de chat.

Ejemplo de solicitud

Método: POST

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

Encabezados

Clave Valor Descripción
Content-Type application/json
Aceptar application/json

Cuerpo

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

Contexto:

El objeto context incluye el objeto value, que pasa metadatos a la conversación de chat. Puedes pasar el objeto context a los agentes virtuales como un parámetro de datos sin firma. Consulta el siguiente ejemplo:

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

En este ejemplo, el valor del parámetro de datos sin firmar para el campo entrante es context y el campo de destino se podría establecer en context. Esto te permitiría usar $session.params.context.foo o $session.params.context.key.

Respuesta de ejemplo

{
    "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"
    }
}

Devuelve un chat por ID

Este método devuelve el objeto de chat para un ID de chat determinado.

Endpoint:

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

Encabezados:

Clave Valor Descripción
Content-Type application/json
Aceptar application/json

Consulta:

Clave Valor Descripción
chat_id Número entero (Obligatorio)

Ejemplo de solicitud y respuestas

En las siguientes secciones, se proporcionan ejemplos de solicitudes al extremo.

Recupera un chat correctamente

En el siguiente ejemplo, se muestra la solicitud exitosa de un ID de chat existente.

Solicitud

Encabezados:

Clave Valor Descripción
Content-type application/json
Aceptar application/json

Consulta:

Clave Valor Descripción
chat_id Número entero (Obligatorio)
Respuesta
{
    "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"
    }
}

Código de estado: 200

Obtén atributos de datos reservados durante un chat

Extremo

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

Ejemplo de solicitud y respuestas

En esta sección, se incluye un ejemplo de solicitud y respuesta para el extremo.

Listo

En este ejemplo, se muestra una llamada exitosa.

Solicitud

Encabezados

Clave Valor Descripción
Aceptar application/json

Variables de URL

Clave Valor Descripción
id integer (Obligatorio)
Respuesta
{
    "verified_customer": "boolean",
    "bad_actor": "boolean",
    "repeat_customer": "boolean"
}

Código de estado 0

Actualiza los atributos de datos reservados durante un chat

Extremo

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

Variables de URL

Clave Valor Descripción
id integer (Obligatorio)

Body

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

Envía datos personalizados en el chat

Envía datos personalizados en un chat.

Ejemplo de solicitud

Método: POST

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

Encabezados

Clave Valor Descripción
Content-Type application/json

Variables de URL

Clave Valor Descripción
id (Obligatorio)

Respuesta de ejemplo

// 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> =======================

Actualiza al usuario final durante la sesión de chat en curso

Actualiza el usuario final asociado con la sesión de chat activa actual. Además, también actualiza la información de contacto vinculada al ticket del CRM. _Identifier es obligatorio, mientras que name, email y phone son opcionales.

Ejemplo de solicitud

Método: POST

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

Encabezados

Clave Valor Descripción
Content-Type application/json

Variables de URL

Clave Valor Descripción
chat_id

Cuerpo

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

Respuesta de ejemplo

{
    "message": "accepted"
}