Integrations & connectors

Integrations & connectors

Telenow agents don't just talk — they act. An agent can append a row to your Google Sheet, create a CRM lead, send a WhatsApp confirmation, raise a Razorpay payment link, or book a Calendly slot, all mid-call. It can also fetch a caller's record before it starts speaking so it can open with "Hi Sarah, I see you're on the Premium plan."

This page is the complete guide to connecting those tools yourself — no developer, no Telenow support ticket. You connect a vendor account once under Workplace → Integrations, then add its actions to any agent as one-click tools.

The big idea: connect once, swap anytime. Credentials live in a workspace connection vault (encrypted). Agents reference the connection and a capability (e.g. whatsapp.send) — never the credentials, and never a specific vendor. So you can move from one WhatsApp provider to another, or from HubSpot to Salesforce, by repointing the tool — the agent doesn't change, and the model's tool schema stays identical.

Related reading: Tools & function calling for the full tool spec · Building agents for the Tools step · WhatsApp for messaging specifics · Automation platforms for Zapier/Make/n8n.

How it fits together

There are three layers, and you only ever touch the first one:

One connection serves every agent in the workspace. One agent tool points at one connection + capability.

Step 1 — Connect a provider

1. Go to Workplace → Integrations in the sidebar.
2. Under Available, providers are grouped by category — Messaging, CRM, Calendars & scheduling, Support & ticketing, Commerce & payments, Spreadsheets & data, Forms, Other. Each card shows a short blurb, the actions it offers, and how many connections you already have.
3. Click Connect (or Add another if you've connected this provider before).
4. A form appears, built from the provider's own field spec:
   • Label — a friendly name (e.g. "Sales Razorpay"). You'll pick connections by label later, so make it memorable when you have several.
   • Credential fields — paste the API key / token. Secret fields are masked as •••••••• the moment they're saved and never shown again.
   • Connection settings — non-secret values some providers need (a Freshdesk domain, a Plivo sender number, a Salesforce instance URL).
5. Click Connect. For API-key and built-in providers, Telenow runs a quick verification immediately, so the row lands with a truthful status.

Only owners and admins can add, edit, test, or remove connections; any member can see them (the agent builder needs the list).

The three auth types

The catalog flags each provider with one of three auth kinds:

Some API-key providers actually use HTTP Basic auth under the hood (Razorpay, Plivo, Freshdesk) — you still just paste two values (a key/ID and a secret), and Telenow synthesizes the Basic base64(id:secret) header for you.

Connecting an OAuth provider (consent flow)

OAuth providers don't take a pasted key — you grant access on the vendor's site:

1. Fill any required settings (e.g. Salesforce's Instance URL), then click Connect with <provider>.
2. You're sent to the provider's sign-in / consent screen. Approve the requested scopes.
3. The provider redirects back to Telenow, which exchanges the code for tokens, encrypts them, and marks the connection active. A toast confirms the result.

A few details worth knowing:

• From Workplace → Integrations, consent opens in the same window and you return to the Integrations page with a status flag.
• From inside the agent builder (Add integration slide-over), consent opens in a new tab so your unsaved agent form survives — approve there, then come back; the new connection's actions appear automatically.
• Tokens auto-refresh. When an access token is within ~60 seconds of expiry, Telenow silently refreshes it using the stored refresh token before dispatching the call — you don't re-authorize routinely. If a refresh ever fails, the connection is parked in an error state with the reason, and you click Reconnect.
• An OAuth connection that hasn't completed sign-in shows Disconnected until the callback lands.

Admin one-time setup for OAuth providers. OAuth uses Telenow's registered app for each vendor, configured by the platform via environment variables (e.g. GOOGLE_OAUTH_CLIENT_ID, SALESFORCE_OAUTH_CLIENT_ID). If an OAuth provider doesn't appear or sign-in fails, the platform operator hasn't configured that app yet — see Troubleshooting.

Test, edit, remove

On the Connected tab each connection has:

• Test — re-runs the provider's verification request and surfaces the vendor's own error message if it fails. The status chip updates (Active / Needs attention / Disconnected).
• Edit — change the label, settings, or rotate a key. Leave a masked secret untouched to keep the stored value; only type a new value to replace it.
• Remove — deletes the connection. You can't remove a connection while an agent still references it (as a tool or a pre-call lookup) — Telenow blocks the deletion and names the agents so you can detach it first.

The connector catalog

These ship as catalog rows, so the list grows without app updates. Categories shown are the ones used to group the Available tab.

Messaging (WhatsApp)

Five providers all implement the same whatsapp.send capability with identical parameters (to, message), so you can switch WhatsApp vendors without touching your agents. Full setup for each is in WhatsApp.

Free-form text only reaches a contact inside an open 24-hour session window; business-initiated messages may need an approved template (provider-dependent). See WhatsApp.

CRM

Lookups return a trimmed result (a few relevant fields) to save latency and tokens on a live call. For HubSpot/Intercom lookups, searching by the national number without the country code is usually the most reliable match.

Calendars & scheduling

Spreadsheets & data

Forms

Commerce & payments

Support & ticketing

Money-moving actions are always confirmed. Any payment.* capability (e.g. Razorpay's payment.link) makes the agent read the action back and wait for a verbal yes before it runs — even if you forget to tick the confirmation box. See Confirm before executing.

Step 2 — Attach a connection as an agent tool

Open the agent in the builder and go to the Tools step. Connections you've made appear under Workspace integrations · click to add — one card per action your connections offer (shared by all agents).

1. Click the card for the action you want (e.g. Send WhatsApp on your Razorpay/Sheets/CRM connection). A tool is added to the agent.
2. The stored tool references the connection by id and the capability — never the credentials:

{
  "name": "send_whatsapp",
  "kind": "connector",
  "description": "Send a WhatsApp message to a phone number…",
  "config": { "connectionId": "…", "capability": "whatsapp.send" },
  "handoff": "Sending that over WhatsApp now."
}

3. Optionally set a handoff line (spoken while the tool runs) and tick Confirm with the caller before running (see below).
4. For actions that target a specific spreadsheet / base / form, complete the per-tool binding and click Load fields.

Don't have the connection yet? Use the + Add integration link right in the Tools step — see the slide-over.

Per-tool binding ("Load fields")

Some actions need to know which target this particular tool points at — which spreadsheet, which Airtable base, which form, which Calendly event type. That choice lives on the tool, not the connection, so one connection serves any number of targets: a single Google Sheets connection can back 50 tools writing to 50 different sheets.

When you add such a tool, the card shows extra fields:

For Sheets / Airtable / JotForm, after entering the target click Load fields. Telenow fetches the live columns/fields/questions and turns each into a parameter the model fills from the conversation. The discovered field names show as chips on the card.

• A green dropdown for the tab/event type. Where a setting can be enumerated (Sheets tabs, Calendly event types), the field becomes a live picker populated from the vendor; otherwise it's a text box where you paste an ID.
• Where to find the ID. Spreadsheet ID is in the sheet URL (docs.google.com/spreadsheets/d/<ID>/edit); Airtable base ID is the app… segment of the base URL; form IDs are in the form's public URL.
• Re-load after schema changes. Discovery runs at configure time, not on every call. If you add or rename a column later, the card warns that "the target changed since these fields were loaded" — click Refresh fields so the agent collects the right columns.

Test action with sample data

On any connector tool card, click Test action with sample data. Telenow runs the real action once (no caller involved) with the JSON arguments you supply, applying the same binding and packing as a live call, and shows the raw result. Use it to confirm a row really lands in your sheet or a payment link really generates — before you publish.

Confirm before executing

For anything irreversible — send money, message a customer, write a record — tick Confirm with the caller before running. The first time the model calls the tool, Telenow doesn't execute it: it returns a "read this back and ask the caller to confirm" result, so the agent says something like "I'll send a payment link for ₹500 to +1… — shall I go ahead?" and only runs it on a later turn once the caller agrees. The read-back uses only the tool's arguments, never secrets.

Payments (payment.*) are forced on regardless of the checkbox — a careless config can't ship an unconfirmed money-moving tool. Full mechanics in Confirm before executing.

The "Add integration" slide-over

You don't have to leave the builder to connect a new vendor. In the Tools step, click + Add integration next to Workspace integrations. A right-hand slide-over opens with the full catalog (searchable, grouped by category). Pick a provider, fill the same connection form, and click Connect:

• API-key providers are verified on the spot; the connection's actions appear in the one-click list immediately.
• OAuth providers open consent in a new tab (your unsaved agent form is safe) — approve there, then return; the connections list refreshes when this window regains focus, so the new action shows up without a reload.

Pre-call lookups (screen-pop personalization)

A connector or your own API can run at the very start of a call, before the agent speaks, and drop the result into your context variables. That's how an agent opens with the caller's name, plan, or last order — a CRM "screen pop" for voice.

Set them up in the agent builder's Tools step, under Pre-call lookups · optional. Each lookup is one of two kinds:

Workspace integration lookup

Run a connected action (e.g. HubSpot's Look up a contact by phone) keyed on the caller, and map fields from the response into variables:

1. Add a lookup, choose Workspace integration.
2. Pick the connection and action.
3. Set arguments using caller placeholders, e.g. phone → {caller_number}.
4. Map response fields to variables, e.g. customer_name → results.0.properties.firstname.value. The map uses a dot-path into the response (array indices supported: data.0.name).

Custom API lookup

Call your own HTTPS endpoint instead:

1. Add a lookup, choose Custom API.
2. Pick GET or POST and enter the URL with caller placeholders, e.g. https://api.example.com/customers?phone={caller_number}.
3. Add an optional Bearer token and any headers; map response fields into variables the same way.

The placeholders available to a lookup are the trusted caller envelope only:

Custom API lookups never see auth.* or connection.* placeholders, only the caller envelope — so the URL must be public or carry its own bearer token.

Once mapped, the variables are available to the opening line and prompt: "Hi {customer_name}, I see you're on the {account_tier} plan." Works for outbound calls (and campaigns) and inbound calls.

Pre-call lookups are best-effort. They run concurrently with a short per-lookup timeout (~10 s); a slow or failed lookup logs a warning but never blocks the call — the agent simply starts without those variables. They run before any billable session exists, so they are not metered toward integration usage.

For why you should trust caller.number over a value the model collects, see caller identity.

MCP servers

Beyond the built-in catalog, an agent can call tools from any remote MCP (Model Context Protocol) server — your own, or a third party's. Manage these under Workplace → Integrations → MCP (a directory of curated servers plus your authenticated connections), and attach individual tools in the builder's Tools → Connect MCP server.

• Directory — curated remote servers (GitHub, Linear, Atlassian, Stripe, Notion, Asana, Sentry, PayPal). Pick one or paste a custom server URL.
• Verify — Telenow lists the server's tools. If the server requires sign-in, it reports needsAuth and you start OAuth.
• OAuth (DCR + PKCE) — for servers that need it, Telenow performs OAuth discovery and Dynamic Client Registration with PKCE, caches the discovery + client info, stores tokens encrypted, and refreshes them at dispatch time (same ~60 s pre-expiry logic as connectors). Static-token servers just take a pasted token.
• Attach tools — in the builder, verify the server, pick the tools you want, and they're stored inline on the agent as kind: "mcp". Unlike connectors, MCP tools have no per-tool binding — each server is a single connection and the agent uses the tools you selected.

Only remote servers reachable over https:// are supported (an SSRF guard blocks loopback/private addresses); stdio / locally-spawned servers are not. A server can't be removed while an agent still references its tools. Full tool-spec details are in Tools & function calling.

Connect thousands of apps (aggregators)

The MCP directory also features aggregators — Composio, Pipedream Connect, and Zapier MCP — that front 250 to 7,000+ apps (Salesforce, HubSpot, Slack, Gmail, Sheets, and the long tail) behind one managed integration. Generate your personal MCP URL in the aggregator's dashboard, then add it under an agent's Tools → Connect MCP server. See Automation platforms.

OpenAPI import

Telenow can generate connector actions from an OpenAPI spec (request templates, parameter schemas, and response shaping derived from the spec). This is platform/admin-driven today and not yet a self-serve org upload. Until it is, the equivalent self-serve options are: a request-template (curl) tool for a single endpoint, or an MCP server / aggregator for a whole API surface.

Integration billing & plans

Integration usage can be metered against per-tier plans (Starter / Pro / Enterprise), but this is an admin-controlled feature that is OFF by default. When it's off — the default — every org has all categories and no quota, and nothing on this page is gated.

When an operator turns plans on, the Integrations page shows a banner with your plan, allowed categories, and this cycle's usage. The shipped tiers:

• Connect-time gating — on a gated plan, connecting a provider whose category isn't allowed is rejected with a clear "upgrade to connect" message.
• Overage vs. hard cap — by default, going over quota accrues an overage charge (posted once per calendar month, for the previous month, via the billing ledger). A per-plan hard cap flag (admin-set) can instead block connector calls mid-call when over quota. The billing cycle is the UTC calendar month.
• Pre-call lookups are not metered (they run before a billable session exists).

See Billing & usage for how charges appear on your invoice.

Tips

• Name connections clearly. You'll pick them by label in the builder and pre-call lookups — "Sales Razorpay" beats "Razorpay" when you have two.
• Swap vendors without rework. Moving from one WhatsApp/CRM vendor to another? Connect the new one and repoint the tool's connection — the capability and the model's schema stay the same.
• Load fields after editing a sheet/base/form. Adding a column doesn't update existing tools automatically; click Refresh fields.
• Confirm anything irreversible. Tick Confirm with the caller for sends and writes; payments are always confirmed.
• Use pre-call lookups for warm openers, but keep them best-effort — never write a greeting that requires a variable a lookup might not return.
• Dry-run before you publish. The Test action bench on each tool card runs the real action once so you can verify it end-to-end.

Troubleshooting

See also

• Tools & function calling — the full tool spec, confirm-before-execute, caller identity, placeholder filters
• Building agents — the Tools step in context
• WhatsApp — pairing + all five WhatsApp providers
• Context variables — variables pre-call lookups populate
• Automation platforms — Zapier / Make / n8n / viaSocket + the REST-hook API
• Billing & usage — how integration charges appear