Integración de Webhooks de entrada

TimelinesAI te permite automatizar el envío de mensajes de WhatsApp en respuesta a eventos o acciones en herramientas que ya estés utilizando: CRM, Soporte, Sistemas de contratación, etc.

"Evento "Enviar mensaje

Es posible ordenar a TimelinesAI que envíe un mensaje (con o sin archivo adjunto) a un contacto específico (puede ser un grupo). Si hay varias cuentas de WhatsApp conectadas en su espacio de trabajo, también es posible especificar una cuenta de WhatsApp concreta que se utilizará para enviar el mensaje.

Para configurar la integración, el propietario de un espacio de trabajo debe ir a la pantalla "Integraciones / Webhooks de entrada" y generar una nueva URL. El sistema externo debe enviar el mensaje en un formato específico (ver detalles más abajo) a esa URL.

Limitaciones

• El tamaño máximo de los archivos adjuntos es de 2 MB.
• No hay validación inmediata del formato del número de teléfono del destinatario ni de la conexión a WhatsApp. Vaya a la interfaz de líneas de tiempo para comprobar el estado de envío o lectura de los mensajes.

Envío de archivos mediante Webhooks de entrada

Enviar un archivo: Descarga directa frente a servicios de alojamiento de archivos

Es imprescindible enviar archivos utilizando enlaces de descarga directa. Esto permite al destinatario recibir realmente el archivo.

Debe utilizarse un servicio de alojamiento de archivos que pueda proporcionar un enlace de descarga directa. La mejor forma de probar un enlace de este tipo es a través de la navegación de incógnito/privada, pegando el enlace en la barra de búsqueda. Si la descarga del archivo se inicia inmediatamente, el enlace es aceptable. Si, por el contrario, se muestra cualquier tipo de página web, entonces, el enlace no puede utilizarse para enviar archivos.

El caso de los enlaces del Servicio de Alojamiento de Archivos es que los archivos no se pueden descargar. En su lugar, lo que se descarga y envía es una página web compartida, que puede dar lugar a un archivo "corrupto".

Esto, a su vez, afectará a su mensaje, ya que los destinatarios no podrán acceder a los medios que les envíe, haciendo que los archivos queden inutilizables. Por lo tanto, es crucial que te asegures de enviar enlaces de descarga directa, ya que esto les permitirá acceder al archivo sin ningún problema.

También puede ejecutar esta prueba enviando un mensaje webhook a uno de sus números de prueba. Podrá determinar cómo se comportará el archivo basándose en lo que hemos revisado aquí; si recibe un mensaje de error como "El archivo está dañado", "Archivo incompatible"; o "Error al cargar X documento", después de hacer clic en el archivo adjunto, entonces se trata de un Enlace de Servicio de Alojamiento de Archivos y debe ser reemplazado por un Enlace de Descarga Directa.

Utilización del crédito

• El envío de un mensaje consume 1 crédito de la cuota de envío de mensajes.
• El envío de un mensaje con texto no vacío y archivo adjunto consume 2 créditos de la cuota de envío de mensajes.
• Si no se puede enviar un mensaje (número de WhatsApp no válido o no conectado, error del servidor de WhatsApp), se restablecerá la cuota de envío de mensajes (normalmente en un par de horas).

Velocidad de envío de mensajes

• Los mensajes se enviarán con un retardo aleatorio de unos 2 segundos entre cada dos mensajes (para evitar los mecanismos de detección de spam de WhatsApp).
• Si activa los webhooks con una frecuencia inferior a 2 segundos, los mensajes se pondrán en cola y se enviarán con retraso. Cada mensaje en cola consumirá un crédito de envío de mensajes, por lo que el número de mensajes en cola no puede superar la cuota disponible.

Configuración y acciones de Webhook

• "Webhook habilitado" - permite deshabilitar el webhook sin eliminarlo por completo.
• "Generar nueva URL" - creará una nueva URL única, que aceptará notificaciones. La URL anterior ya no estará disponible.
• "Últimos intentos de envío" - estado de los últimos intentos de activación del webhook
• "Registro de descargas": un registro detallado de los 100 últimos intentos de activación, útil para solucionar problemas de formato.

Formato de solicitud de webhook

El Webhook acepta datos en formato JSON, mediante petición POST.

• "action" (obligatorio) - actualmente, sólo se admite el valor "send" (enviar)
• "text" (obligatorio)- un mensaje codificado en texto plano UTF-8 a enviar (no admite markdown, excepto el separador de línea "\n"), puede dejarse vacío, si se especifica archivo.
• "file_url" (opcional) - una URL de acceso público de un archivo que se descargará y enviará como adjunto.
• "nombre_archivo" (opcional) - un nombre para el archivo adjunto (debe proporcionarse, si se especifica URL).

El destinatario puede especificarse proporcionando uno de los siguientes parámetros:

• "chat_id" - un id del chat tal y como aparece en TimelinesAI (puede encontrarse en la URL de la página de chat, o en la carga útil del webhook saliente). Esto permite enviar mensajes a un grupo.
• "jid" - un JID de WhatsApp que especifica el contacto o el grupo
• "phone" - un número de teléfono, formateado según el estándar internacional de números de teléfono, es decir:
  [+][código de país][código de área][número de teléfono local] (por ejemplo: +14151231234)
• "chat_name" - nombre exacto del chat tal y como aparece en TimelinesAI

Si hay varias cuentas de WhatsApp conectadas en el espacio de trabajo, utilice el siguiente parámetro adicional para especificar la cuenta de WhatsApp que se utilizará:

• "whatsapp account phone" (opcional) - especifica (como número de teléfono, en formato internacional) la cuenta de WhatsApp que usе para el envío. Si se omite, se utilizará para el envío la cuenta de WhatsApp activa conectada más recientemente en el espacio de trabajo. Nota: si se especifica el parámetro "chat_id", no se tendrá en cuenta "whatsapp account phone", porque cada chat ya está conectado a una cuenta de WhatsApp específica.

Respuesta Webhook

En caso de éxito (la solicitud fue validada y aceptada para su envío), el Webhook responderá con el estado HTTP 200 y JSON, conteniendo message_id del mensaje creado:

{
    "status": "success",
    "data": {
        "message_id": "wa_backend:3EB09FCC85FE99662E46"
    }
}

 

En caso de error, el Webhook responderá con el estado HTTP 40X y JSON con los detalles del error, por ejemplo:

{
"status": 40X,
"data": {},
"message": "Webhook not found"
}

Ejemplos

Ejemplo 1: envío de un mensaje a través de una cuenta WA específica a un número de teléfono concreto:

{
"action": "send",
"whatsapp account phone" : "+15105566777", 
"phone": "+14151231234", 
"text": "lorem ipsum"
}

Ejemplo 2 - enviar un mensaje con texto y archivo adjunto a un chat (o grupo) especificado por id:

{
"action": "send", 
"chat_id": "77234", 
"text": "lorem ipsum"
"file_url" : "https://timelines.ai/logo.png",
"file_name" : "logo.png"
}