Integrate your assistant with Gmail, Calendar and WhatsApp

Steps

1. 1Keep the Pulbot API key on your assistant’s server. Send X-API-Key with requests. Do not include it in model messages, browsers, connection links or public code.
2. 2Define the Pulbot account and organization that will own the resources. For multiple businesses, maintain the mapping from each business to its Pulbot identity and resource IDs; do not assume a central key identifies the person chatting.
3. 3Discover platforms with GET /api/v1/core/platforms/ and connections with GET /api/v1/resource-connectors/. Gmail uses Google Workspace; WhatsApp uses Whatsapp. Store real IDs rather than inventing them.
4. 4For Gmail, generate a link with POST /api/v1/resource-connectors/oauth2/start/ and share data.authorize_url. The user grants permissions in Google. The new link behavior is local and awaits deployment and real verification; see API → Connect Gmail and OAuth resources for the full contract.
5. 5For WhatsApp, first connect the business account through Pulbot’s Meta Embedded Signup and retrieve the resource ID. Do not use Gmail’s generic endpoint for WhatsApp: its current configuration does not declare that OAuth2 flow.
6. 6Discover actions with GET /api/v1/tools/?category=all&platform=<platform_id> and inspect GET /api/v1/tools/<tool_id>/. Use the inputs declared by each tool and send resource_connection_id with the correct resource ID.
7. 7Test first with controlled accounts and recipients. The current POST /api/v1/tools/<tool_id>/execute/ endpoint runs as a Pulbot simulation; this does not guarantee the absence of real provider calls or effects. Its use as the assistant’s production contract still needs validation and agreement.

Reference

Architecture

User → customer assistant → customer server with API key → Pulbot REST API → connected resource → Gmail or WhatsApp. Provider tokens are managed by Pulbot; the assistant uses resource IDs.

Hosts

DEV: https://dev.pulbot.com/api/v1. Production: https://api.pulbot.com/api/v1. An existing route does not prove the new behavior is deployed.

API key scopes

tool:write starts OAuth; flow:simulate permits the execute endpoint. * permits what the key owner is authorized to do. Organization capabilities are evaluated separately. The reviewed scope catalog has no dedicated gmail:send or whatsapp:send scope.

Gmail: link example

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

Gmail: actions

The catalog contains Gmail - Listar mensajes, Gmail - Obtener mensaje, Gmail - Listar etiquetas, Gmail - Enviar mensaje and Gmail - Etiquetar mensaje. A created connection does not confirm that every action is authorized or verified.

Gmail: test example

POST /api/v1/tools/<gmail_list_labels_tool_id>/execute/ — body: {"resource_connection_id":"<gmail_connector_id>"}. Obtain the Gmail - Listar etiquetas ID from the catalog. This remains an integration test to perform with the customer’s actual account.

Gmail: sending

Gmail - Enviar mensaje accepts resource_connection_id and raw_message. raw_message is the RFC 2822 message encoded as base64url, not plain message text. No dedicated /gmail/send endpoint is documented here.

WhatsApp: signup

GET /api/v1/whatsapp/config/ obtains Meta configuration. POST /api/v1/whatsapp/signup/ consumes auth_code and IDs from Embedded Signup. It is not a universal hosted-link generator. Signup can register the number, subscribe webhooks and send a test message; do not invoke signup as a read operation.

WhatsApp: signup permissions

The reviewed signup endpoint declares no dedicated scope. The global guard rejects writes with scoped keys when a route has no explicit scope contract. External signup with a scoped key is not promised until that contract is defined and tested; use existing app onboarding for the pilot.

WhatsApp: test example

POST /api/v1/tools/<whatsapp_text_tool_id>/execute/ — body: {"resource_connection_id":"<whatsapp_connector_id>","recipient_number":"<controlled_recipient>","message_text":"Integration test"}. Obtain the Envío de Mensaje de Texto WhatsApp ID from the catalog. This can send a real message; it is not a dry run.

Execution response

execute returns an object without a data wrapper: {"success":true,"outputs":{},"duration_ms":0,"error":null,"result":{}} is an illustrative shape only. Check success/error and the provider result; HTTP 200 alone does not mean success.

Incoming messages

Sending messages does not mean receiving events in your assistant. Pulbot has conversations and provider webhook reception; this guide does not yet offer a validated event-subscription contract to the customer’s server. Delivery, authentication, retries and correlation must be agreed before implementing external reception.

Inbox and human replies

POST /api/v1/conversations/<id>/messages/ is a human-reply operation with active agent_takeover, not automatically the assistant’s send contract. It does not replace tool execution and external-event design.

Multiple accounts

Each request must select the resource authorized for that customer. Do not mix IDs between businesses. Delegation through Pulbot OAuth, allowing any external-app user to authorize their Pulbot account, is not part of this API-key contract.

Optional MCP

MCP code and a route exist, but the customer can integrate through REST alone. start_connector_oauth2 is a new local tool awaiting deployment. The equivalent REST call does not depend on it.

Pilot acceptance

Before production: verify authentication and customer isolation; connect Gmail with partial consent; use connected WhatsApp; run a controlled read and send; check denied permissions, expiry/revocation and errors; agree incoming events and handling of sends with uncertain outcomes. Record the date and deployed API versions.

Google Calendar

A connection independent of Gmail: Google Calendar platform. Seven declarative tools and dedicated scopes; local code with mocked tests. See API → Google Calendar for inputs, permissions and pending configuration.

Common errors

401 / 403

Invalid, expired or revoked API key, insufficient scope or missing organization capability. A key does not automatically grant permissions in Google or Meta.

Provider rejects operation

Check the selected resource, granted permissions and channel configuration. Do not assume ACTIVE guarantees an authorized operation.

Timeout after sending

Do not automatically repeat a send: it may have succeeded. This contract has no verified send-idempotency key; agree reconciliation before automating retries.

Gmail status

A synthetic send through the previous flow is recorded as successful. Reading/listing and labeling had pending parameter issues; the new link has not yet been verified with real Google accounts. Mock tests do not replace pilot acceptance.

Next step

Start with API → Authentication and API → Connect Gmail and OAuth resources. Use this page as the pilot contract and confirm the production gaps with Pulbot before committing to the assistant launch.