PulbotDocumentación

Conectar recursos con un enlace

Pides a Pulbot un enlace de conexión y se lo das a tu cliente. Tu cliente lo abre, ve la pantalla «Conectar Google Workspace», pulsa «Conectar con Google» y elige su cuenta y permisos en Google. El recurso (su Gmail) queda en tu cuenta Pulbot, listo para usarlo en tus flows. Tu cliente no necesita cuenta en Pulbot, y nunca le pides contraseñas ni tokens.

¿Cuándo usarlo?

Cuando tu aplicación, tu equipo o un agente de IA tiene que conectar el Gmail, el Google Calendar o el WhatsApp Business de otra persona sin entrar al panel de Pulbot.

Pasos

  1. 1Crea una API key en Pulbot → Configuración → API keys. Guárdala en tu servidor: nunca en el navegador ni dentro de un enlace.
  2. 2Pide el enlace: POST https://api.pulbot.com/api/v1/connection-links/ con el header X-API-Key y el cuerpo {"provider": "google", "connector_name": "Gmail de Ana"}. Responde 201 con data.connect_url.
  3. 3Entrega data.connect_url a tu cliente por correo, por WhatsApp o en un botón de tu aplicación.
  4. 4Tu cliente pulsa «Conectar con Google», elige su cuenta y acepta los permisos. Al terminar ve «¡Listo! Tu cuenta quedó conectada».
  5. 5Consulta el recurso nuevo con GET /api/v1/resource-connectors/. Su id es el que usas en los nodos de tus flows.

Referencia

Tu propio botón (sin pantalla de Pulbot)
Si tienes tu propio front, pon tu botón «Conectar Google» o «Conectar WhatsApp». Al pulsarlo, tu servidor llama a POST /api/v1/connection-links/authorize/ con {"provider": "google", "return_url": "https://tu-sitio.com/integraciones"} y redirige al navegador a data.authorize_url (Google). Al terminar, Pulbot crea el recurso y devuelve al usuario a tu return_url con ?oauth=success&connector_id=… o ?oauth=cancelled. return_url: https (http solo localhost). La API key nunca va al navegador. Con {"provider": "whatsapp"} es igual, pero authorize_url abre Meta (Embedded Signup); si algo falla vuelve con ?oauth=error&reason=…, y cada URL sirve para un solo intento.
Varios clientes en una cuenta (external_ref)
Si tu cuenta Pulbot atiende a N clientes, manda en cada conexión tu propio id del cliente: {"external_ref": "cliente-123"} (en /connection-links/ y en /connection-links/authorize/). Queda guardado en el recurso, vuelve en el return_url (?connector_id=…&external_ref=cliente-123&oauth=success) y filtras con GET /api/v1/resource-connectors/?external_ref=cliente-123. Si el mismo cliente reconecta, se actualiza su recurso con el mismo connector_id (no se duplica). Solo lo ve tu cuenta. Formato: letras, números y . _ : @ - hasta 128. Funciona en Gmail, Calendar y WhatsApp.
provider
google (Gmail / Google Workspace), google-calendar o whatsapp. Por defecto, google.
connector_name
Opcional. Nombre del recurso. Si no lo envías, se usa el correo que conecte tu cliente.
Vigencia
El enlace vence a los 10 minutos (expires_in = 600) y sirve para una sola conexión. Abrir la página no lo gasta; pulsar el botón sí.
Dueño del recurso
El recurso queda en el usuario y la organización de la API key que pidió el enlace, aunque tu cliente conecte otra cuenta de Google.
Permisos de la API key
* (todo) o tool:write. Tu usuario debe poder editar recursos en la organización (el dueño ya puede).
WhatsApp
Con provider = whatsapp se abre Meta en lugar de Google, por enlace o con tu propio botón. Tu cliente necesita una cuenta de Facebook con acceso a su portafolio comercial de Meta y el número a conectar. Con tu propio botón se conecta el primer número de su cuenta de WhatsApp Business; si tiene varios, usa el enlace.
MCP
Un agente hace lo mismo con la herramienta create_connection_link(provider, connector_name, external_ref) y entrega connect_url. Servidor: https://api.pulbot.com/mcp/ con el header X-API-Key.
Recursos con API key
OpenAI y otras plataformas sin OAuth no usan enlace: se crean con POST /api/v1/resource-connectors/ enviando la clave del proveedor.

Errores comunes

401
La API key falta, se revocó o venció.
403
La API key no tiene tool:write, o tu usuario no puede editar recursos en esa organización.
400 provider_not_configured
Ese proveedor no está habilitado en el entorno.
«Este enlace ya no sirve»
El enlace venció o ya se usó. Pide uno nuevo.
«No se completó la conexión»
Tu cliente canceló en Google. Pide un enlace nuevo para reintentar.

Siguiente paso

Continúa con API → Armar flows por API para usar el recurso en un flow.

¿Necesitas ayuda?