Chat API
Chat API es un canal genérico con una API pública diseñada para permitir al Agente conectarse a Canales Finales para los que no existe un conector incorporado dentro de la Plataforma. Puede organizar un canal genérico de este tipo utilizando el Conector Genérico de la API de Chat.
Conexión
Configuración del canal del proyecto en la plataforma
Debe crear y configurar un canal de proyecto con el conector "Chat API".
Vaya a la pestaña Canales del proyecto.
Pulse el botón Crear canal.
Se abrirá el panel de selección de canal final.
Seleccione Chat API.
Se abrirá el panel de creación del Canal Proyecto.
Opcionalmente, introduzca un título para este Canal de Proyectos en el campo Nombre con el marcador de posición Nuevo canal.
Introduzca la dirección de su servidor en el campo URL del webhook del canal como https://{dirección_del_servidor}, donde {dirección_del_servidor} es la dirección de la Plataforma.
Importante: El método especificado se añadirá a la dirección cuando el Agente envíe una respuesta a una petición del canal/servidor del cliente: https://your_company.com/send_message*.*
Si es necesario, establezca el token en el campo Token del canal.
Importante: El token debe especificarse si la autenticación del lado del cliente se realiza a través de la cabecera. Más detalles en .
Copie el enlace webhook para el canal del agente (URL webhook Chatbot) haciendo clic en el botón Copiar este webhook.
Para guardar el Canal Proyecto sin activarlo, pulse el botón CREAR.
Para guardar y activar el Canal Proyecto, haga clic en el botón CREAR Y ACTIVAR.
a. El Canal Proyecto se guardará y activará si:
i. Se publica el proyecto;
ii. El token del campo token del canal es único (no hay canales activos del mismo tipo con el mismo token);
iii. La dirección del canal es accesible;
iv. El webhook del canal se ha registrado correctamente.
b. El Canal Proyecto se guardará pero no se activará si no se cumplen una o varias condiciones.
Para cancelar la creación del Canal Proyecto, pulse el botón CANCELAR.
Editar y eliminar el canal del proyecto
Para editar un Canal de Proyectos, haga clic en su ficha en la lista de Canales de Proyectos.
Para editar cualquier campo, haga clic en él e introduzca un nuevo valor.
Para aplicar los cambios a un Canal Proyecto activado, pulse el botón APLICAR.
a. Los cambios se aplicarán si:
i. Se publica el proyecto;
ii. El token del campo token del canal es único (no hay canales activos del mismo tipo con el mismo token);
iii. La dirección del canal es accesible;
iv. El webhook del canal se ha registrado correctamente.
b. Los cambios no se aplicarán si no se cumplen una o varias condiciones.
Para desactivar el Canal Proyecto, pulse el botón DESACTIVAR.
Para aplicar los cambios a un Canal Proyecto no activado, pulse el botón GUARDAR.
Para aplicar los cambios y activar el Canal Proyecto, pulse el botón GUARDAR Y ACTIVAR
a. Los cambios se aplicarán y el Canal Proyecto se activará si:
i. Se publica el proyecto;
ii. El token del campo token del canal es único (no hay canales activos del mismo tipo con el mismo token);
iii. La dirección del canal es accesible;
iv. Se puede registrar el webhook del canal.
b. Los cambios se aplicarán pero el Canal Proyecto no se activará si no se cumplen una o varias condiciones.
Para cancelar los cambios, pulse el botón CANCELAR.
Para eliminar el Canal Proyecto, pulse el botón ELIMINAR.
Solicitudes del canal cliente/servidor al Agente
Método:
HTTPS, POST con tipo de contenido JSON
Punto final de la API para recibir solicitudes por canal de proyectos
URL del webhook del chatbot especificada al conectar el para aceptar solicitudes.
Formato del punto final (URL del webhook de Chatbot):
Nube
https://{server_address}/connector/chatapi/chatapi_message/{token}/bot_api_webhook
En las instalaciones
https://{server_address}/connector/chatapi/chatapi_message/bot_api_webhookWhere:
{server_address} —Dirección de la plataforma,
{token} — token.
Solicitar estructura
Solicitar estructura corporal:
{
"event": (string),
"chat_id": (string),
"visitor"(optional object): {
"id": (string),
"fields": {
Fields (object)
}
},
"message": {
Message (object)
},
"service_data"(optional object): {
Service data (object)
}
}Importante: La estructura del objeto Mensaje depende del tipo de mensaje que se transmita (texto, archivo, clic de botón) y puede constar de diferentes tipos de datos y campos.
Tipo de acontecimiento
Evento es el tipo de evento sujeto a procesamiento por el Agente de acuerdo a una cierta lógica.Eventos soportados:
new_message - un evento transmitido al Agente por el canal/servidor del cliente que contiene un Mensaje del usuario Bot.
Identificador Chat_id
chat_id es un identificador de Chat/Dialog/Usuario Bot en el lado del cliente (en la aplicación social conocida como canal final), es la base para crear un Chat con este Usuario Bot en la Plataforma.
Objeto Visitante
Visitante es un objeto opcional que contiene información sobre el usuario del bot.
Formato visitante:
{
"id": (string — user ID pseudo-unique, assigned by the client's server),
"fields": {
"name": (string),
"login": (string),
"phone": (string),
"email": (string),
"site": (string)
}
}Ejemplo de visitante:
{
"id": "03e1c040d8214bfa8ccfbb053186a24a",
"fields": {
"name": "Mike",
"login": "mike",
"phone": "+18891111111",
"email": "mike@gmail.com",
"site": "https://site.com"
}
}Objeto de mensaje
Mensaje es un objeto que contiene información enviada al Agente para su procesamiento.
{
"kind": (string — message type),
"text": (string — message text),
"data": (JSON — file or button clicked data)
}Tipos de contenido admitidos
A continuación se muestran ejemplos del contenido del objeto Mensaje para distintos tipos de mensajes.
Texto
Formato del mensaje:
{
"kind": "text",
"text": (string — message text)
}Archivo
Formato del mensaje:
{
"kind": "attachment",
"attachment": {
"id": (string — file id),
"content_type": (string — Internet Media Type),
"url": (string — file URL)
}
}Si kind == attachment entonces Public Chat API obtiene los datos del archivo y los convierte en un mensaje de texto para el Agente en el siguiente formato: file:{file_type}|{file_id}|{file_url} . El Agente no descarga el archivo.
Objeto de datos de servicio
Los datos de servicio son cualquier objeto que contenga datos personalizados enviados al Agente para su procesamiento (por ejemplo, para utilizar estos datos en el Diálogo). Objeto opcional.
Pulsación de botones
Formato del mensaje:
{
"kind": "keyboard_response",
"keyboard_response": {
"button": {
"id": (string — button id),
"text": (string — button label)
}
}
}Respuesta a las solicitudes del canal cliente/servidor al Agente en la Plataforma
Platformrespuesta en caso de solicitud correcta
Estado HTTP: 200 OK
BODY:
{
"result": "ok"
}Plataforma respuesta a solicitud fallida
El canal del proyecto está inactivo o hay un error en el token del webhook Chatbot en la URL:
HTTP status: 400 Bad Request
BODY:
{
"error": "There is no active channel for received event."
}Falta un parámetro de requisito en el cuerpo de la solicitud
HTTP estado: 400 Bad Request
URL incorrecta
HTTP estado: 404: No encontrado
Cuerpo de la petición JSON incorrecto: parámetro de tipo o evento no válido
HTTP estado: 200 OK
Solicitudes de la plataforma al canal cliente/servidor
A continuación se muestran los formatos, ejemplos y descripciones de las solicitudes de la API de chat público al servidor cliente.
URL básica
Las solicitudes se envían a la URL del servidor cliente introducida en el Canal Webhook : URL al conectar el Canal Proyecto.
Formato de URL: https://{dirección_del_servidor}/{método}, donde:
{server_address} — Platform address,
{method} —un método de la API de chat público.
Métodos de la API de chat público:
/send_message — envío de un mensaje por parte del Agente al Usuario Bot.
/close_chat — enviando un evento para cerrar el Diálogo.
Autorización en el lado del cliente
La autorización puede realizarse a través de:
Único URL.
Especifique la URL que contiene el token en el campo Channel webhook: URL al conectar el Canal Proyecto. El campo Channel webhook: Token no debe rellenarse:
Header
Especifique el token de autorización en el campo Channel webhook: Token al conectar el canal del proyecto. El token del webhook Channel: Token será sustituido en la cabecera por defecto.
Formato de autorización cuando se utiliza un token:
Autorización: Token {token}
Ejemplo de autorización:
Autorización: Token ac650a3c369a4b9599ad52ab71943712
Estructura general de la solicitud
Método: /send_message
Tipo de solicitud: POST
Tipo de contenido: application/json
Parámetros de la cadena de consulta: not required
Formato URL en caso de que el Agente envíe un mensaje al visitante:
https://{server_address}/send_message
donde {server_address} es la dirección de la Plataforma.
Formato del cuerpo de la solicitud:
{
"message": Message (object),
"chat_id": (string)
}Importante: La estructura del objeto Mensaje depende del tipo de mensaje transmitido (texto, fichero, botones).
Identificador Chat_id
chat_id - identificador del Chat/Dialog/Usuario Bot en el servidor del cliente (en una aplicación de comunicación - el Canal Final), en base al cual se crea el Chat con este Usuario Bot en la Plataforma.
Objeto de mensaje
Mensaje -un objeto que contiene información enviada al Agente para su procesamiento.
{
"kind": (string — message type),
"text": (string — Agent's message text),
"data": (JSON — file data),
"buttons": (object — button info)
}Tipos de contenido admitidos
A continuación se muestran ejemplos del contenido del objeto Mensaje para distintos tipos de mensajes.
Texto
Formato del mensaje:
{
"kind": "text",
"text": (string — Agent's message text)
}Ejemplo de mensaje:
{
"kind": "text",
"text": "Hi, how can I help you?"
}Archivo
Formato del mensaje:
{
"kind": "attachment",
"attachment": {
"url": (string — file URL),
"type": (string — Internet Media Type),
"caption": (string — Attachment Caption. Optional field)
}
}Ejemplo de mensaje:
{
"kind": "attachment",
"attachment": {
"url": "https://site.com/wp-content/uploads/2019/04/diagram.png",
"type": "image/png",
"caption": "Here is the diagram!"
}
}Importante: el envío de archivos se realiza desde la ranura de adjuntos.
Mensaje con botones
Formato del mensaje:
{
"kind": "keyboard",
"buttons": [
{
"text": (string — button label),
"id": (string — button id)
}
]
}Ejemplo de mensaje:
{
"kind": "keyboard",
"buttons": [
{
"text": "Transfer to Support",
"id": "fedc60c4dc0d4348b48b524d"
},
{
"text": "Transfer to Sales",
"id": "574f2caad88a41a7a2d6b667"
}
]
}Importante: El identificador del botón sólo puede contener letras latinas, números, guiones y guiones bajos, y no debe tener más de 24 caracteres.
Cierre de diálogos y transferencia a un Agente
Estructura general de la solicitud
Método: /close_chat
Tipo de solicitud: POST
Tipo de contenido: application/json
Parámetros de cadena de consulta: not required
Formato URL en caso de que el Agente envíe un mensaje al visitante:
https://{server_address}/close_chat
donde {dirección_servidor} es la dirección de la plataforma.
Formato del cuerpo de la solicitud:
{
"chat_id": (string)
}Importante: El cierre de diálogos se implementa desde la ranura Cambiar modo de chat. El diálogo se cierra automáticamente en la plataforma del chatbot.
Importante: La API de chat público tiene un conjunto limitado de funciones. Si necesita que el Agente utilice otros métodos del lado de la API del cliente (por ejemplo, transferir el Diálogo a un operador/departamento específico), entonces el trabajo con estos métodos se puede configurar dentro del Agente utilizando el constructor de peticiones (Petición Externa).
Comunicación
La interacción con el servidor cliente se produce a través de la API pública "Chat API" según la configuración de la cuenta en el servicio cliente.
Asignación de variables de canal desde la API de chat
Comunicación en la API de chat
Los mensajes llegarán al Usuario Bot si el Agente escribe primero en un chat existente
Depende del canal
Transferencia al operador
No
La transferencia a un operador a través de la ranura Cambiar modo de chat no se admite en la implementación actual de la funcionalidad de la Plataforma. La transferencia al operador puede realizarse "manualmente" a través de Solicitud externa
Recepción de un archivo del Usuario Bot en un script
Si
Formato: archivo:Tipo de archivo|ID archivo|Referencia archivo
Last updated