Scripts en Python de Chat2Desk
Los scripts en Python permiten añadir lógica propia al flujo de mensajes de tu centro de atención. Se guardan en los servidores de Chat2Desk y los editas en línea, sin montar un servidor propio. Además de los comandos de scripts, dentro del código puedes usar la API de Chat2Desk.
En resumen
- Código en Python 3 que se ejecuta en Chat2Desk cuando ocurre un evento (mensaje nuevo, diálogo cerrado, etiqueta asignada, una llamada desde un sistema externo, cada 60 segundos…).
- 14 eventos y 20 comandos para enviar mensajes, consultar clientes y operadores y transferir chats.
- Es una función de pago que activa la administración de Chat2Desk a solicitud.
- El envío de mensajes desde scripts tiene un límite de 15 por segundo.
Para qué sirven
- Enrutar diálogos: asigna chats a tus operadores según frases, etiquetas del cliente, la hora o la carga de trabajo de cada operador.
- Vigilar retrasos: reasigna a otros operadores o supervisores los chats que se atrasaron por culpa del equipo.
- Enviar información a tu CRM: manda los datos del cliente y del diálogo a tu CRM mediante su API.
- Asignar etiquetas a clientes y solicitudes y, a partir de ellas, lanzar otros escenarios: otros scripts o un Chatbot Conversacional.
Una solicitud (request) es el conjunto de mensajes de un diálogo con un cliente. Normalmente empieza con el primer mensaje del cliente y termina cuando se cierra el diálogo. Si el cliente vuelve a escribir en un diálogo cerrado, este se reabre y empieza una solicitud nueva.
Cómo empezar
- Pide a la administración de Chat2Desk que active la función de scripts.
- Como administrador, entra en la sección Scripts de la configuración de tu cuenta.
- Activa el registro de errores (logging), al final de la sección, para recibir los mensajes de error de tus scripts en tu propio mensajero. Para ello necesitas tu
client id(te explicamos cómo obtenerlo abajo). - Marca los eventos que activarán tu script.
- Edita los manejadores (handlers) de esos eventos.
- Pulsa Guardar.
- Pruébalo con datos de prueba: en Test input data revisa los datos de entrada, elige el evento y pulsa Run on test input_data; el resultado aparece en Output.
Aviso: si usas scripts para repartir chats entre operadores, conviene desactivar las opciones de asignación automática del Chatbot Autoservicio y de los chatbots, para evitar conflictos.
Cómo obtener tu client id
Activa el evento Mensaje nuevo en la parte superior de la sección y comprueba que el new_message_handler incluya este código (viene por defecto):
class Handler:
def new_message_handler(self, input_data, c2d):
c2d.send_message(input_data['client']['id'],
"Este es tu client id: " + str(input_data['client']['id']) +
".\n\nPara desactivar este mensaje, quita la opción 'Mensajes entrantes' en la configuración de Scripts.",
"system")Escribe desde cualquier mensajero conectado a tu cuenta. Verás un mensaje del sistema con tu client id en el chat contigo mismo, dentro de Todos los chats. Escribe ese client id en el apartado de registro para recibir los mensajes de depuración.
Cómo llamar a un script
Los manejadores se ejecutan solos cuando ocurre el evento que activaste. Además, puedes escribir tus propias funciones y llamarlas de estas formas:
- Desde un chatbot, al activarse una palabra clave.
- Desde una opción del Chatbot Autoservicio, cuando el cliente la elige.
- Desde una macro, como una de sus acciones. Las macros se ejecutan desde Chats con el botón de la estrella.
- Desde un servicio externo, llamando a la dirección propia de tu empresa (el evento
manually_handler), por GET o POST.
Cada función debe estar dentro de la clase Handler y su nombre debe terminar en _handler. Por ejemplo:
class Handler:
def macro_call_handler(self, input_data, c2d):
...Eventos que activan un script
Hay 14 eventos y se activan o desactivan en Configuración > Scripts.
| Evento | Manejador | Cuándo ocurre |
|---|---|---|
| Mensaje nuevo recibido | new_message_handler | Después de que tu centro de atención recibe un mensaje. Ocurre antes de la respuesta automática y del mensaje del Chatbot Autoservicio; para bloquearlos, devuelve 'not send menu'. |
| Antes de enviar un mensaje | before_sending_message_handler | Cuando un operador envía un mensaje, justo antes de enviarlo. |
| Antes de cerrar un diálogo | before_closing_dialog_handler | Al cerrarse un diálogo (manual o automáticamente), justo antes del cierre. |
| Después de cerrar un diálogo | after_closing_dialog_handler | Después de cerrarse un diálogo (manual o automáticamente). |
| Cada 60 segundos | auto_checking_handler | Cada 60 segundos; los datos de entrada incluyen la hora actual ("time"). |
| Código QR reconocido | qr_code_result_handler | Cuando se reconoce un código QR en un mensaje entrante. Requiere que la opción esté habilitada para tu empresa (contactar a Chat2Desk). |
| Llamada desde un sistema externo | manually_handler | Cuando se llama a la dirección (webhook) propia de tu empresa, por GET o POST, con información en JSON. Sirve para integrar los scripts con telefonía o un CRM. La dirección está en la configuración de scripts, en «Web hook call from external service». |
| El chatbot no se activó | chat_bot_not_triggered_handler | Cuando llega un mensaje y el chatbot no se activa. |
| Chat transferido entre operadores | dialog_transfer_handler | Cuando un chat pasa de un operador a otro. Solo funciona en el sitio web. |
| Cliente nuevo (solicitud nueva) | new_request_handlers | Cuando empieza una solicitud nueva (no confundir con un mensaje). |
| Datos del cliente modificados | client_updated_handler | Al cerrar la ficha del cliente con el botón Ok. No ocurre al asignar etiquetas. |
| Se pide el teléfono | request_phone_handler | Cuando un operador pulsa «Solicitar número de teléfono» en Chats. Disponible para Facebook, Viber público y Telegram; requiere habilitarlo para tu empresa. |
| Etiqueta asignada a la solicitud | add_tag_to_request_handler | Cuando se agrega una etiqueta manualmente, desde el Chatbot Autoservicio o desde un chatbot. |
| Etiqueta eliminada de la solicitud | delete_tag_from_request_handler | Cuando se elimina una etiqueta de esas mismas formas. |
Los datos del evento llegan en input_data. Por ejemplo, el de mensaje nuevo trae message (id, is_menu, dialogID, operatorID, text, transport, y la URL del adjunto —photo, video, audio o pdf— o coordinates), client (id, phone, name, assigned_name) y channel (id, phone, name).
Comandos disponibles
Se llaman desde el objeto c2d que recibe cada manejador.
| Comando | Qué hace |
|---|---|
send_message(client_id, text, type, file, channel_id) | Envía un mensaje de texto a un cliente. type (opcional): to_client (predeterminado), autoreply (respuesta automática sin asignar el chat a un operador) o system (mensaje del sistema en el chat, que no se envía al cliente). file (opcional): URL directa a una imagen o PDF. channel_id (opcional): si el cliente tiene diálogos en varios canales; si se omite, se usa el del último mensaje. Límite: 15 mensajes por segundo; si se excede, devuelve «429 Too many requests». |
send_question(client_id, question_id) | Envía al cliente una opción del Chatbot Autoservicio. |
get_client_info(client_id) | Devuelve los datos de un cliente: nombre, nombre asignado, comentario, fechas del primer y último mensaje, teléfono o ID, país y región (según el teléfono), último transporte, canal, avatar y más. |
get_operators() | Lista de operadores: nombre, diálogos abiertos, última visita, correo, teléfono, rol, estado en línea y más. |
get_online_operators(true o false) | Operadores en línea; con True, solo los que pueden recibir chats nuevos. |
get_client_dialogs(client_id) | Información del diálogo actual del cliente. También sirve para saber qué operador lo atendió por última vez. |
get_questions(client_id, desde, hasta) | Opciones del Chatbot Autoservicio que el cliente pidió en un periodo (fechas como '10-10-2021'). |
get_last_question(client_id) | Última opción del chatbot enviada al cliente. |
get_unanswered_dialogs(limit) | Diálogos con un mensaje del cliente sin responder tras limit segundos, y sus clientes. Útil para pasar chats «atorados» a un operador libre. |
get_new_messages() | Mensajes nuevos (chats nuevos), para revisarlos y asignarlos. |
transfer_dialog(dialog_id, operator_id, comentario) | Transfiere un diálogo que ya tiene operador a otro operador. |
transfer_message(message_id, operator_id, comentario) | Asigna a un operador un diálogo nuevo que aún no tiene operador. |
transfer_message_to_group(message_id, group_id) | Transfiere el diálogo a un grupo de operadores; el operador lo elige la configuración del administrador. |
get_operators_groups() | Lista de grupos de operadores. |
get_operator_group_ids(operator_id) | IDs de los grupos de un operador. |
get_company_info() | Datos de la empresa: nombre, horario, modo actual (en línea o fuera de línea) y más. |
get_last_message_id(dialog_id, tipo, periodo) | ID del último mensaje de un diálogo. Tipo: 1 cliente, 2 operador, 3 respuesta automática, 4 mensaje del sistema. periodo en segundos. |
send_template('abc', client_id) | Envía una plantilla por su comando rápido. |
get_menu_items(channel_id, nivel) | Lista las opciones del Chatbot Autoservicio (el nivel raíz es 1, a diferencia de la API). |
send_menu_item(client_id, menu_item_id) | Envía una opción del chatbot; si se omite el ID, envía el menú raíz del canal del último mensaje. |
Dentro de un script también puedes llamar a la API con requests, por ejemplo para cerrar un diálogo:
import requests
r = requests.put(
'https://api.chat2desk.com.mx/v1/dialogs/' + str(dialog_id),
params={'state': 'closed', 'operator_id': operator_id},
headers={'Authorization': api_token},
)Ejemplos de uso
- Enviar una tarjeta de presentación por WhatsApp tras una llamada telefónica. El sistema de telefonía llama a la dirección (webhook) de tu empresa con el número de quien llamó. El script comprueba si ese cliente ya existe en tu centro de atención, lo crea si no, y le envía un mensaje que depende de la hora (horario laboral, fuera de horario o fin de semana). Incluye un tope diario de clientes nuevos para evitar bloqueos por spam y requiere activar «Escribir primero».
- No molestar a los operadores mientras el cliente usa el Chatbot Autoservicio. Los mensajes nuevos se asignan a un operador «bot» (de apellido
bot); cuando el cliente escribe algo que no es una opción del menú, el script transfiere el diálogo al operador en línea con menos chats abiertos.
Consejos
- Dispara acciones desde cualquier servicio. Llama a la dirección del evento
manually_handlerdesde tu sistema para que el script haga algo en Chat2Desk; por ejemplo, enviar un WhatsApp cuando un cliente deja su teléfono en tu sitio o cuando llega su pedido. - Atiende las calificaciones bajas. Asigna una etiqueta a las calificaciones que elijas (se asigna a la solicitud, no al cliente), crea un webhook del evento
add_tag_to_requestque apunte almanually_handlery, en el script, revisa qué etiqueta se asignó para reenviar la calificación a un supervisor, por ejemplo por correo. - Genera enlaces de pago. Con un Chatbot Conversacional puedes crear un enlace de pago automáticamente cuando el operador escribe ciertas palabras o envía una plantilla.
Preguntas frecuentes
¿Qué versión de Python usan los scripts? Python 3.x.
¿Necesito un servidor propio? No. Los scripts se guardan y se ejecutan en los servidores de Chat2Desk.
¿Tiene costo? Es una función de pago; la administración de Chat2Desk la activa a solicitud.
¿Cómo depuro un script? Activa el registro de errores con tu client id y prueba el script con la opción «Run on test input_data».
¿Cuántos mensajes puedo enviar desde un script? Hasta 15 por segundo; al excederlo la API responde «429 Too many requests».
¿Cómo conecto mis scripts con mi sistema de telefonía o mi CRM? Con el evento «Llamada desde un sistema externo»: tu sistema llama por GET o POST a la dirección de tu empresa y envía los datos en JSON.
¿Puedo pedir que me hagan un script? Sí: el manual indica que el equipo de Chat2Desk puede crear scripts a medida.
¿Necesitas ayuda con tu integración?
Cuéntanos qué quieres conectar y te orientamos. Si todavía no tienes cuenta, empieza con la prueba gratuita.
¿Prefieres escribirnos? Habla con un asesor de Chat2Desk por WhatsApp.