PulbotDocumentation

Connect resources with a link

You ask Pulbot for a connection link and give it to your customer. They open it, see the «Connect Google Workspace» screen, press «Connect with Google» and choose their account and permissions on Google. The resource (their Gmail) lands in your Pulbot account, ready for your flows. Your customer needs no Pulbot account, and you never ask for passwords or tokens.

When to use it

When your app, your team or an AI agent needs to connect someone else's Gmail, Google Calendar or WhatsApp Business without using the Pulbot dashboard.

Steps

  1. 1Create an API key in Pulbot → Settings → API keys. Keep it on your server: never in the browser or inside a link.
  2. 2Request the link: POST https://api.pulbot.com/api/v1/connection-links/ with the X-API-Key header and the body {"provider": "google", "connector_name": "Ana's Gmail"}. It returns 201 with data.connect_url.
  3. 3Give data.connect_url to your customer by email, WhatsApp or a button in your app.
  4. 4Your customer presses «Connect with Google», picks their account and accepts the permissions. They then see «Done! Your account is connected».
  5. 5Fetch the new resource with GET /api/v1/resource-connectors/. Its id is what you use in your flow nodes.

Reference

Your own button (no Pulbot screen)
If you have your own front end, add your «Connect Google» or «Connect WhatsApp» button. When it's pressed, your server calls POST /api/v1/connection-links/authorize/ with {"provider": "google", "return_url": "https://your-site.com/integrations"} and redirects the browser to data.authorize_url (Google). Afterwards Pulbot creates the resource and sends the user back to your return_url with ?oauth=success&connector_id=… or ?oauth=cancelled. return_url: https (http only for localhost). The API key never reaches the browser. With {"provider": "whatsapp"} it works the same, but authorize_url opens Meta (Embedded Signup); on failure it comes back with ?oauth=error&reason=…, and each URL is good for a single attempt.
Many customers in one account (external_ref)
If your Pulbot account serves N customers, send your own customer id on every connection: {"external_ref": "customer-123"} (on /connection-links/ and /connection-links/authorize/). It's stored on the resource, comes back on the return_url (?connector_id=…&external_ref=customer-123&oauth=success) and you filter with GET /api/v1/resource-connectors/?external_ref=customer-123. If the same customer reconnects, their resource is updated with the same connector_id (no duplicates). Only your account sees it. Format: letters, digits and . _ : @ - up to 128. Works for Gmail, Calendar and WhatsApp.
provider
google (Gmail / Google Workspace), google-calendar or whatsapp. Defaults to google.
connector_name
Optional. Resource name. If omitted, the email your customer connects is used.
Lifetime
The link expires after 10 minutes (expires_in = 600) and works for one connection. Opening the page does not use it; pressing the button does.
Resource owner
The resource belongs to the user and organization of the API key that requested the link, even if your customer connects a different Google account.
API key permissions
* (everything) or tool:write. Your user must be able to edit resources in the organization (owners can).
WhatsApp
With provider = whatsapp Meta opens instead of Google, by link or with your own button. Your customer needs a Facebook account with access to their Meta business portfolio, and the number to connect. With your own button the first number of their WhatsApp Business account is connected; if they have several, use the link.
MCP
An agent does the same with the create_connection_link(provider, connector_name, external_ref) tool and hands over connect_url. Server: https://api.pulbot.com/mcp/ with the X-API-Key header.
API key resources
OpenAI and other non-OAuth platforms don't use a link: create them with POST /api/v1/resource-connectors/ sending the provider's key.

Common errors

401
The API key is missing, revoked or expired.
403
The API key lacks tool:write, or your user can't edit resources in that organization.
400 provider_not_configured
That provider isn't enabled in this environment.
«This link no longer works»
The link expired or was already used. Request a new one.
«The connection was not completed»
Your customer cancelled on Google. Request a new link to retry.

Next step

Continue with API → Build flows via API to use the resource in a flow.

¿Necesitas ayuda?