Integrations

An integration is a stored connection to an external service. It comes in one of two shapes, and the provider decides which:

Tool integrations give an agent tools the model can call. You attach one in the agent’s mcps list, so attaching takes a publish. See MCP servers.
Channel integrations (Telegram, WhatsApp) put a published agent on a messaging channel. They are never attached to an agent config; a trigger binds them to an agent.

Providers

`provider`	Shape	`auth_type`	Tools come from
`google_calendar`	Tool	`oauth`	Native: nine tools run against the Calendar API (Google Calendar)
`cal_com`, `calendly`	Tool	`oauth`	The vendor’s hosted MCP server
`asana`, `jira`	Tool	`oauth`	The vendor’s hosted MCP server
`hubspot`	Tool	`oauth`	HubSpot’s hosted MCP server. One integration per portal
`rocketreach`	Tool	`oauth`	RocketReach’s hosted MCP server
`exa`, `tavily`	Tool	`manual` (API key)	The vendor’s hosted MCP server
`resend`	Tool	`manual` (API key)	Resend’s hosted MCP server; also the account email batches send from
`custom_mcp`	Tool	`manual` (URL)	Your own server (custom MCP servers)
`telegram`	Channel	`manual` (bot token)	None (Telegram)
`whatsapp`	Channel	`manual` (Twilio or Gupshup credential)	None (WhatsApp)

A service not on this list is reachable only as a custom MCP server. GET /v1/integrations/catalog returns the same list live, with each provider’s setup_fields (the exact keys to send on create, their target and whether they are required), capabilities (attachable_as_mcp, trigger_types) and enabled. enabled is false for an OAuth provider whose OAuth app is not configured on this deployment; it cannot be connected.

curl https://api.talqing.com/v1/integrations/catalog \
  -H "Authorization: Bearer $TALQING_API_KEY"

RocketReach lookups spend credits from your RocketReach plan, and nothing on our side caps that. Searching is free; each lookup or export is not. An agent task run once per row of a 5,000-row list spends 5,000 credits.

Connecting an API-key provider

Manual providers take their credentials on POST /v1/integrations. A field of type secret_ref (such as credentials_ref) accepts the plaintext value, which the platform stores as a workspace secret and replaces with a reference (TAVILY_API_KEY, RESEND_API_KEY, EXA_API_KEY, TELEGRAM_BOT_TOKEN, suffixed if the name is taken). Or send an existing {{secrets.NAME}} reference; one naming a missing secret is refused.

curl -X POST https://api.talqing.com/v1/integrations \
  -H "Authorization: Bearer $TALQING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "Tavily",
    "provider": "tavily",
    "credentials_ref": "tvly-your-api-key"
  }'

const integration = await talqing.integrations.create({
  createIntegrationRequest: {
    display_name: "Tavily",
    provider: "tavily",
    credentials_ref: "tvly-your-api-key",
  },
});
// integration.credentials_ref === "{{secrets.TAVILY_API_KEY}}"

integration = talqing.integrations.create(
    display_name="Tavily",
    provider="tavily",
    credentials_ref="tvly-your-api-key",
)
# integration["credentials_ref"] == "{{secrets.TAVILY_API_KEY}}"

exa, tavily and resend require a key. Exa’s keyless tier is a shared pool whose rate limit strangers exhaust, so it is not accepted.
Telegram, Resend and WhatsApp credentials are checked with the provider before the row is written; a key the provider rejects fails the create with a 400.
custom_mcp header values are not turned into secrets; see custom MCP servers.
Reads never return a secret value: secret fields come back as {{secrets.NAME}}.

To rotate a key, send credentials_ref again on PATCH /v1/integrations/{integration_id}. Omitting it keeps the current one.

Connecting an OAuth provider

OAuth providers connect from the dashboard only: POST /v1/integrations refuses them with connect <Provider> with OAuth.

Start

Integrations → Add integration → pick the provider.

Authorize

Approve the access on the provider’s page. The flow must finish in the same browser, login and workspace that started it.

Approve tools

The tool-approval modal opens on return. Approve only what the agent needs (approving tools).

The integration is named <Provider> - <account> (Google Calendar - ada@northwind.com), with (2) appended if the name is taken. Connecting an account that already has an integration is refused with an integration for this account already exists. Reconnect (the button on the integration’s row) replaces the tokens on the existing row and keeps allowed_tools and tools_namespace. Use it when the status is needs_reconnect or the grant was revoked. An OAuth integration with no stored credential cannot be PATCHed back to active.

Statuses

`status`	Meaning	Fix
`active`	Usable. The only status an agent can attach or a trigger can run on	—
`disabled`	Switched off with `PATCH {"status": "disabled"}`	`PATCH` back to `active`
`needs_reconnect`	Set by the platform when an OAuth token refresh is refused, or the provider answers 401 again after a refresh	Reconnect from the dashboard
`error`	Never set by the platform; available for you to mark a broken connection. Behaves like `disabled`	`PATCH` back to `active`

Any status other than active: the integration cannot be attached, its tools drop out of published agents on their next session (validate and publish warn integration '<name>' is disabled - its tools are left out until you enable it), its triggers cannot be enabled, and GET …/mcp-tools returns 400.

A published agent naming a non-active or deleted integration still starts — without those tools. The prompt still describes them, so the model will try to use tools it no longer has. Remove the attachment and republish if the outage is not momentary.

Disabling a channel integration also unregisters its enabled triggers with the provider; enabling it registers them again.

Deleting

DELETE /v1/integrations/{integration_id} is permanent and deletes its triggers. It also removes the Telegram bot’s webhook, clears a Twilio WhatsApp sender’s webhook and calling, or revokes OAuth tokens with the provider.

Two connections to one provider

Two Asana workspaces or two Google accounts are fine, but both integrations default tools_namespace to the provider key. Attaching both to one agent is refused until you give one a different namespace (asana_eu). See namespacing.

Field reference

Field	Notes
`display_name`	1–120 characters, unique in the workspace (`409` `an integration with that name already exists`). A label only; renaming breaks nothing
`provider`	One of the providers above. Fixed after create
`credentials_ref`	Plaintext or `{{secrets.NAME}}`; stored as a reference
`provider_account_info`	Account identity. Written by the platform for OAuth, Telegram and Resend; required input for WhatsApp, fixed after create
`mcp_config`	`custom_mcp` only: `url`, `headers`
`webhook_config`	Telegram only: `secret_token`
`allowed_tools`, `tools_namespace`	Tool providers only. See MCP servers
`status`	See statuses
`webhook_setup`	Response only, on channel integrations: `callback_url`, `delivery_status` (`waiting` or `receiving`), `last_received_at`
`metadata`	Yours, returned untouched

MCP servers

Attach an integration to an agent, approve its tools, set its namespace.

Triggers

Bind a Telegram or WhatsApp integration to a published agent.

Get started

Build

Guides

Providers

Connecting an API-key provider

Connecting an OAuth provider

Statuses

Deleting

Two connections to one provider

Field reference

Next

MCP servers

Triggers

​Providers

​Connecting an API-key provider

​Connecting an OAuth provider

​Statuses

​Deleting

​Two connections to one provider

​Field reference

​Next

MCP servers

Triggers

Providers

Connecting an API-key provider

Connecting an OAuth provider

Statuses

Deleting

Two connections to one provider

Field reference

Next