Integrar tu asistente con Gmail, Calendar y WhatsApp

Pasos

1. 1Mantén la API key de Pulbot en el servidor de tu asistente. Envía X-API-Key en las peticiones. No la incluyas en mensajes al modelo, navegador, enlaces de conexión o código público.
2. 2Define la cuenta Pulbot y la organización que serán propietarias de los recursos. Para varias empresas conserva la relación entre cada empresa, identidad de Pulbot y IDs de recursos; no uses una key central suponiendo que identifica al usuario del chat.
3. 3Descubre plataformas con GET /api/v1/core/platforms/ y conexiones con GET /api/v1/resource-connectors/. Gmail corresponde a Google Workspace; WhatsApp corresponde a Whatsapp. Guarda los IDs reales, no los inventes.
4. 4Para Gmail, genera el enlace con POST /api/v1/resource-connectors/oauth2/start/ y entrega data.authorize_url. El usuario concede permisos en Google. El nuevo comportamiento por enlace está local y pendiente de despliegue y validación real; el contrato completo está en API → Conectar Gmail y recursos OAuth.
5. 5Para WhatsApp, conecta primero la cuenta empresarial con el alta integrada de Meta que ofrece Pulbot y recupera el ID del recurso. No uses el endpoint genérico de Gmail para WhatsApp: su configuración actual no declara ese OAuth2.
6. 6Descubre acciones con GET /api/v1/tools/?category=all&platform=<platform_id> y consulta GET /api/v1/tools/<tool_id>/. Usa los inputs declarados por cada herramienta y envía resource_connection_id con el ID del recurso correcto.
7. 7Prueba primero con cuentas y destinatarios controlados. El endpoint actual POST /api/v1/tools/<tool_id>/execute/ se ejecuta como simulación de Pulbot; eso no garantiza ausencia de llamadas o efectos reales en proveedores. Falta validar y acordar su uso como contrato productivo del asistente.

Referencia

Arquitectura

Usuario → asistente del cliente → servidor del cliente con API key → API REST de Pulbot → recurso conectado → Gmail o WhatsApp. Los tokens del proveedor se gestionan en Pulbot; el asistente usa IDs de recursos.

Hosts

DEV: https://dev.pulbot.com/api/v1. Producción: https://api.pulbot.com/api/v1. La existencia de una ruta no demuestra que el nuevo comportamiento esté desplegado.

Scopes de la API key

tool:write inicia OAuth; flow:simulate permite el endpoint execute. * permite lo que autorice el dueño de la key. Las capacidades de organización se evalúan aparte. No existe en el catálogo de scopes revisado un gmail:send o whatsapp:send específico.

Gmail: ejemplo de enlace

POST /api/v1/resource-connectors/oauth2/start/ — X-API-Key: <key>; Content-Type: application/json; body: {"platform_id":"<google_workspace_id>"}. Respuesta relevante: {"data":{"authorize_url":"<url>","expires_in":600}}.

Gmail: acciones

El catálogo contiene Gmail - Listar mensajes, Gmail - Obtener mensaje, Gmail - Listar etiquetas, Gmail - Enviar mensaje y Gmail - Etiquetar mensaje. Una conexión creada no confirma que todas estén autorizadas o verificadas.

Gmail: ejemplo de prueba

POST /api/v1/tools/<gmail_list_labels_tool_id>/execute/ — body: {"resource_connection_id":"<gmail_connector_id>"}. Obtén el ID de Gmail - Listar etiquetas del catálogo. Es una prueba de integración pendiente con la cuenta real del cliente.

Gmail: envío

Gmail - Enviar mensaje recibe resource_connection_id y raw_message. raw_message es el mensaje RFC 2822 codificado como base64url; no es un texto libre. No existe aquí un endpoint dedicado /gmail/send documentado.

WhatsApp: alta

GET /api/v1/whatsapp/config/ obtiene la configuración de Meta. POST /api/v1/whatsapp/signup/ consume auth_code y los IDs obtenidos del Embedded Signup. No es un generador de enlace alojado universal. El alta puede registrar el número, suscribir webhooks y enviar un mensaje de prueba; no invoques signup como consulta.

WhatsApp: permisos de alta

El endpoint signup revisado no declara un scope específico. La protección global rechaza escrituras con keys limitadas si la ruta no tiene contrato explícito de scope. No prometemos alta externa con una key limitada hasta definir y probar ese contrato; para el piloto usa el alta existente en la app.

WhatsApp: ejemplo de prueba

POST /api/v1/tools/<whatsapp_text_tool_id>/execute/ — body: {"resource_connection_id":"<whatsapp_connector_id>","recipient_number":"<destinatario_controlado>","message_text":"Prueba de integración"}. Obtén el ID de Envío de Mensaje de Texto WhatsApp del catálogo. Puede enviar un mensaje real; no es un dry-run.

Respuesta de ejecución

execute devuelve un objeto sin envoltorio data: {"success":true,"outputs":{},"duration_ms":0,"error":null,"result":{}} es solo una forma ilustrativa. Valida success/error y el resultado del proveedor; HTTP 200 por sí solo no significa éxito.

Mensajes entrantes

Enviar mensajes no equivale a recibir eventos en tu asistente. Pulbot tiene conversaciones y recepción de webhooks del proveedor; esta guía no ofrece todavía un contrato validado de suscripción de eventos hacia el servidor del cliente. Deben acordarse entrega, autenticación, reintentos y correlación antes de implementar recepción externa.

Inbox y respuesta humana

POST /api/v1/conversations/<id>/messages/ corresponde a respuesta humana con agent_takeover activo, no es automáticamente el contrato de envío del asistente. No sustituye al diseño de ejecución de herramientas y eventos externos.

Cuentas múltiples

Cada solicitud debe seleccionar el recurso autorizado para ese cliente. No mezcles IDs entre empresas. La delegación mediante OAuth de Pulbot para que cualquier usuario de una app externa autorice su cuenta Pulbot no forma parte de este contrato por API key.

MCP opcional

Existe código y ruta MCP, pero el cliente puede integrar solo REST. start_connector_oauth2 es una herramienta nueva local pendiente de despliegue. No depende de ella la llamada REST equivalente.

Aceptación del piloto

Antes de producción: comprobar autenticación y aislamiento entre clientes; conectar Gmail con aceptación parcial; usar WhatsApp conectado; ejecutar una lectura y un envío controlados; comprobar permisos rechazados, expiración/revocación y errores; acordar eventos entrantes y tratamiento de envíos con respuesta incierta. Guardar fecha y versiones de API desplegadas.

Google Calendar

Conexión independiente de Gmail: plataforma Google Calendar. Siete herramientas declarativas y scopes específicos; código local con pruebas simuladas. Consulta API → Google Calendar para inputs, permisos y configuración pendiente.

Errores comunes

401 / 403

API key inválida, vencida, revocada, scope insuficiente o capacidad de organización faltante. Una key no concede automáticamente permisos en Google o Meta.

Proveedor rechaza la operación

Comprueba el recurso seleccionado, los permisos concedidos y la configuración del canal. No asumas que ACTIVE garantiza una operación autorizada.

Timeout tras enviar

No repitas un envío automáticamente: puede haberse realizado. Este contrato no ofrece una clave de idempotencia de envío verificada; acuerda conciliación antes de automatizar reintentos.

Estado de Gmail

El envío sintético del flujo anterior está registrado como exitoso. Lectura/listado y etiquetado tenían incidencias de parámetros pendientes; el nuevo enlace aún no tiene validación real. Las pruebas simuladas no sustituyen la aceptación del piloto.

Siguiente paso

Empieza por API → Autenticación y API → Conectar Gmail y recursos OAuth. Usa esta página como contrato del piloto y confirma con Pulbot las brechas de producción antes de comprometer el lanzamiento del asistente.