Resumen de conectores

TelegramWhatsAppMessengerInstagramDiscordKakaoTalk

Los conectores reciben eventos de una plataforma de mensajería externa, normalizan el texto o el audio compatible, ejecutan el mismo agente del sitio y devuelven una respuesta adecuada para el canal. Cada usuario externo tiene un historial de conversación propio del canal, visible en Conversaciones.

Conectar un canal nuevo requiere el plan Operate o Scale. Las conexiones existentes siguen funcionando en Launch.

Matriz de capacidades#

«Voz entrante» significa que se descarga y se transcribe un mensaje de voz o audio compatible. «Voz saliente» requiere un proveedor de voz que funcione y la opción Responder con voz del conector. Los adjuntos no compatibles, como imágenes y ubicaciones, se ignoran en lugar de interpretarse como instrucciones para el agente.

Antes de conectar#

1. Prueba el agente que quieres usar en el panel. Un conector en borrador también puede responder.
2. No necesitas una clave de modelo: la plataforma proporciona los modelos. Las claves de proveedor son opcionales y exclusivas del plan Scale; consulta Claves de proveedor.
3. Crea una app, un bot, un número o un canal dedicado en el proveedor externo. No reutilices una credencial que pertenezca a una integración de producción sin relación.
4. Confirma que tu despliegue tiene una URL base HTTPS pública para el conector. Los webhooks de los proveedores no pueden entregar a localhost sin un túnel de desarrollo seguro.
5. Abre la página Canales del agente y elige el canal.

Al guardar, Make Agent Fast llama al proveedor para validar la credencial enviada. La etiqueta de conectado significa que la validación de la credencial y cualquier aprovisionamiento automático se completaron; no demuestra que se haya completado un paso manual en la consola de Meta, Discord o Kakao.

Gestión de credenciales#

Los formularios de conector solo aceptan credenciales de proveedor desde el panel autenticado o desde la API pública del lado del servidor. Los secretos se cifran en reposo y nunca se devuelven en las respuestas de listado de conectores. Trata los siguientes valores como contraseñas:

• Token del bot de Telegram
• Tokens de acceso de Meta y secreto de la app
• Token del bot de Discord
• Clave de la REST API de Kakao y secreto del bot

No los coloques en JavaScript del navegador, capturas de pantalla, tickets de soporte ni control de código fuente. La URL del webhook y el token de verificación de Meta son valores de configuración pensados para copiarse en la consola del proveedor correspondiente; no sustituyen a las credenciales del proveedor.

Conectar mediante la API#

Usa una clave de API de MAF guardada en el servidor con connectors:write. El objeto credentials específico del canal es de solo escritura. La respuesta omite los secretos en texto plano e incluye la URL del webhook necesaria para la configuración manual en el proveedor.

curl -X POST "https://makeagent.fast/api/v1/sites/$SITE_ID/connectors" \
  -H "Authorization: Bearer $MAF_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: connector-telegram-v1" \
  -d '{
    "channel": "telegram",
    "credentials": { "bot_token": "'$TELEGRAM_BOT_TOKEN'" },
    "reply_with_voice": false
  }'

reply_with_voice y el campo opcional display_label son campos de nivel superior, no van dentro de un objeto config. Guardar de nuevo el mismo bot o cuenta actualiza su credencial y su configuración conservando su token de enrutamiento. En Telegram e Instagram, un bot o una cuenta distintos añaden una nueva conexión (hasta cinco por agente); en los demás canales, guardar reemplaza la conexión existente. Consulta Autenticación de la API, Ámbitos y errores y la Referencia de la API para conocer las reglas de integración en producción.

Probar y supervisar#

Usa un usuario de prueba del proveedor y una pregunta realista que dependa del conocimiento del agente. Confirma todo lo siguiente:

• El proveedor acepta o verifica el endpoint del webhook.
• Un mensaje llega al agente y recibe la respuesta esperada.
• Último mensaje cambia en la tarjeta del conector.
• La conversación aparece en Conversaciones con el canal correcto.
• Se entiende cualquier restricción de revisión o de modo de desarrollo del proveedor antes del lanzamiento público.
• La voz se prueba por separado del texto cuando el canal la admite.

La tarjeta del conector muestra el último error del proveedor o de entrega. Los paneles de los proveedores también conservan registros de entrega; compara las marcas de tiempo y los identificadores de evento cuando solo uno de los lados informe de la solicitud.

Desactivar, rotar o eliminar#

Desactivar detiene el procesamiento pero conserva el registro del conector. El webhook de Telegram permanece registrado mientras la conexión está desactivada (Make Agent Fast no llama a deleteWebhook) y los mensajes entrantes se ignoran; al activarla, el webhook se registra de nuevo. Las suscripciones configuradas en la consola del proveedor se mantienen y, si es necesario, también deben pausarse desde el lado del proveedor. Eliminar borra el conector de Make Agent Fast e intenta desmontar lo configurado en el proveedor en la medida de lo posible, pero no elimina la app externa, no revoca su credencial ni borra el historial de conversaciones existente.

Para rotar una credencial, crea el nuevo token en el proveedor, actualiza el conector, pruébalo y después revoca el token anterior. Si una credencial quedó expuesta, revócala primero en el proveedor y trata el intervalo de exposición como un incidente de seguridad.

Fallos comunes#

Continúa con la guía del canal para ver los campos exactos del proveedor y la secuencia en su consola.