Para agentes de IA

Conecta tu agente de IA a BDC AI

Contactos, conversaciones, campañas y plantillas de tu organización, con la misma autenticación y los mismos límites que usa el dashboard. Elige el camino que le queda a tu cliente: un click si usas Claude Desktop o claude.ai, una llave si usas Claude Code, Cursor o un script propio.

Tres caminos para conectar un agente

Conector con un click (OAuth)

Usa este camino si trabajas desde Claude Desktop o claude.ai: no hay llave que copiar ni que rotar, el agente actúa con tus propios permisos de usuario.

En Claude, abre Configuración → Conectores → Agregar conector personalizado.
Pega la URL https://bdcai.com/mcp y confirma.
Claude descubre el servidor de autorización automáticamente (RFC 9728, vía /.well-known/oauth-protected-resource) e inicia el flujo OAuth.
Inicia sesión con tu cuenta de BDC AI y autoriza el acceso en /oauth/consent. El agente queda conectado con tus permisos, sin scopes propios que configurar.

Claude Desktop / claude.ai

Configuración → Conectores → Agregar conector personalizado
URL: https://bdcai.com/mcp

El descubrimiento OAuth y el consentimiento corren solos: no hay nada que copiar aparte de la URL.

Llave de API

Usa este camino si trabajas desde Claude Code, Cursor, n8n o un script propio: necesitas una credencial de larga duración con scopes explícitos que puedas revocar sin tocar la sesión de nadie.

Crea una llave en Ajustes → Integraciones → API y agentes (/settings/canales/api). El módulo API debe estar encendido en tu organización.
Elige solo los scopes que tu integración necesita (contacts:read, conversations:write, messages:send…). El valor completo (bdc_live_…) se muestra una sola vez.
Configura tu cliente MCP con la URL https://bdcai.com/mcp y el header Authorization: Bearer bdc_live_….
Si algo se ve raro, revoca la llave desde el mismo panel: el acceso se corta de inmediato, sin afectar a otras llaves.

Claude Code

claude mcp add --transport http bdcai https://bdcai.com/mcp \
  --header "Authorization: Bearer bdc_live_…"

Cursor

{
  "mcpServers": {
    "bdcai": {
      "url": "https://bdcai.com/mcp",
      "headers": {
        "Authorization": "Bearer bdc_live_…"
      }
    }
  }
}

Va en .cursor/mcp.json (por proyecto) o en el mcp.json global de Cursor.

n8n

Nodo "MCP Client Tool"
Endpoint del servidor MCP: https://bdcai.com/mcp
Authentication: Bearer
Bearer Token: bdc_live_…

El nombre exacto del campo de endpoint y el selector de transporte varían entre versiones de n8n; confirma contra la documentación del nodo en tu instancia.

Las 22 tools, agrupadas

Qué puede hacer un agente conectado

Cada tool es exactamente una operación del contrato público /api/v1: mismo scope, misma validación, mismo límite de uso. Nada extra, nada oculto.

Campañas

escribeCrea una campaña (email o WhatsApp) en borrador
leeDetalle de una campaña
escribeEnvía ahora o programa una campaña
leeLista segmentos de la organización
escribeCuenta y muestrea una audiencia (segmento o filtros)
leeLista plantillas de WhatsApp aprobadas

Contactos

escribeAgrega un vehículo a un contacto
escribeCrea un contacto
leeObtiene un contacto por id, con sus vehículos
leeBusca contactos por nombre, email o teléfono
escribeActualiza un contacto

Conversaciones

escribeAgrega una nota interna a una conversación
escribeAsigna (o desasigna) una conversación a un asesor
leeObtiene una conversación por id, con sus últimos mensajes
leeLista conversaciones con filtros
escribeMueve una conversación a otro stage del pipeline
escribePausa o reanuda el AI agent para una conversación
escribeInicia una conversación saliente enviando una plantilla
leeLista los mensajes de una conversación
escribeEnvía un mensaje de WhatsApp (texto, plantilla o media)

Cuenta

leeDescribe la organización y el actor autenticado (usuario, API key o agente)
leeDescribe la organización: líneas, pipelines, sucursales, equipo

Lo que un agente no puede saltarse

Ventana de 24 horas

Fuera de la ventana de servicio de WhatsApp (24 horas desde el último mensaje del contacto) solo se puede reabrir la conversación con una plantilla aprobada, igual que en el dashboard. Un agente no puede saltarse esa regla porque es la misma que aplica la API.

Solo plantillas aprobadas

conversations_start y messages_send solo aceptan plantillas que Meta ya aprobó para tu organización. Una plantilla en revisión o rechazada responde con un error, nunca se manda a medias.

Aviso de frecuencia

Al crear una campaña (campaigns_create) sobre una lista que ya recibió marketing hace poco, o que sigue limitada por WhatsApp, el aviso de frecuencia BLOQUEA la creación con 409 frequency_warning: no se crea la campaña ni se manda nada. Un agente sale de ahí de dos formas: repetir la llamada con acknowledge_frequency_warning: true (la campaña se crea y el aviso vuelve en warnings), o repetirla con los blocked_contact_ids que trajo el error puestos en exclude_contact_ids, para dejar fuera a los contactos limitados.

Scopes acotados

Una llave o una sesión OAuth solo puede hacer lo que sus scopes permiten. Un agente con contacts:read no puede escribir contactos aunque el modelo se lo proponga: la validación corre en el servidor, no en el prompt.

Idempotencia obligatoria en envíos

messages_send y conversations_start exigen idempotency_key. Si un agente reintenta la misma llamada por un timeout de red, el servidor re-sirve la respuesta original en vez de mandar el mensaje dos veces.

Preguntas frecuentes

¿Qué puede hacer un agente conectado a BDC AI?

Buscar y crear contactos, leer y escribir conversaciones, enviar mensajes de WhatsApp con plantillas aprobadas, crear y programar campañas, y consultar segmentos y plantillas. Las mismas 22 operaciones que expone /api/v1, ni una más.

¿Qué NO puede hacer?

No puede saltarse la ventana de 24 horas de WhatsApp, mandar una plantilla no aprobada, crear una campaña sobre una lista con aviso de frecuencia sin reconocerlo (acknowledge_frequency_warning o exclude_contact_ids), ignorar un scope que su llave no tiene, ni reenviar un mensaje ya entregado si usa idempotency_key. Todas esas reglas viven en el servidor, no en el criterio del modelo.

¿Cómo revoco el acceso de un agente?

Si conectaste por llave de API, revócala en Ajustes → Integraciones → API y agentes: el acceso se corta de inmediato. Si conectaste por OAuth (Claude Desktop, claude.ai), desconecta el conector desde el propio cliente; si necesitas revocarlo del lado del servidor, escríbenos por WhatsApp y lo hacemos por ti.

¿Cuánto cuesta conectar un agente?

Depende de tu plan. Escríbenos para activar el módulo de API y agentes en tu cuenta; el resto de los precios está en /pricing.

¿Prefieres ver la referencia completa primero?

La guía de inicio de /docs/api tiene los mismos pasos con curl real, la lista de scopes y el explorador interactivo del contrato.

Ir a /docs/api Hablar con soporte por WhatsApp