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".

1. Vaya a la pestaña Canales del proyecto.

1. Pulse el botón Crear canal.

1. Se abrirá el panel de selección de canal final.

1. Seleccione Chat API.

2. Se abrirá el panel de creación del Canal Proyecto.

1. Opcionalmente, introduzca un título para este Canal de Proyectos en el campo Nombre con el marcador de posición Nuevo canal.

1. 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*.*

1. 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 .

1. Copie el enlace webhook para el canal del agente (URL webhook Chatbot) haciendo clic en el botón Copiar este webhook.

1. Para guardar el Canal Proyecto sin activarlo, pulse el botón CREAR.

1. 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.

1. 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.

1. Para editar cualquier campo, haga clic en él e introduzca un nuevo valor.

2. 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.

1. Para desactivar el Canal Proyecto, pulse el botón DESACTIVAR.

1. Para aplicar los cambios a un Canal Proyecto no activado, pulse el botón GUARDAR.

1. 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.

1. Para cancelar los cambios, pulse el botón CANCELAR.

1. 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": "[phone]",
  "email": "[e-mail]",
  "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

Canal variable	Canal final	Variable en el cuerpo de una solicitud entrante de un canal	Peculiaridades
channel_conversation_id	Chat API	chat.id
channel_visitor_id	Chat API	visitor.id
channel_visitor_firstname	Chat API	visitor.fields.name
channel_visitor_lastname	Chat API	No
channel_visitor_account	Chat API	visitor.fields.login
channel_visitor_phone	Chat API	visitor.fields.phone
channel_visitor_email	Chat API	visitor.fields.email
channel_visitor_source	Chat API	visitor.fields.site
channel_service_data	Chat API	service_data
channel_reply_to	Chat API	no

Comunicación en la API de chat

Funcionalidad	Canal	Disponibilidad	Description
channel_chat_id	Chat API	Si	Format:<client chat_id>|omnichannel
Los mensajes llegarán al Usuario Bot si el Agente escribe primero en un chat existente	Chat API	Depende del canal
Botones	Chat API	Si	Al hacer clic en el botón aparece el texto de la etiqueta del botón.
Transferencia al operador	Chat API	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
Transferencia de archivos como archivos del Agente	Chat API	No
Transferencia de archivos como enlaces desde el Agente	Chat API	Si
Recepción de un archivo del Usuario Bot en un script	Chat API	Si	Formato: archivo:Tipo de archivo|ID archivo|Referencia archivo
Entrega de mensajes de más de 1000 caracteres del Agente al Usuario Bot	Chat API	Depende del canal
Uso de Markdown	Chat API	No
Envío con notificación	Chat API	No